In part 1 of this series, I talked about the basics. Part 2 was about the overall session appearance. This part will be about using the events which are available in the ICO SDK. The ICO SDK has a lot of events we can use, but we will be talking about a few so that you get a basic idea on how to use them.
Available Events
First of all, let’s start with the code we use to view all events in the ICAClientClass. We already had the following code:
[System.Reflection.Assembly]::LoadFile("C:\Program Files (x86)\Citrix\ICA Client\WfIcaLib.dll")
$ICA = New-Object WFICALib.ICAClientClass
$ICA.Address = "XASRV001"
$ICA.Username = "TestUser01"
$ICA.SetProp("Password","MyUsersPassword")
$ICA.Domain = "LAB"
$ICA.Application = ""
$ICA.Launch = $true
$ICA.OutputMode = [WFICALib.OutputMode]::OutputModeNormal
$ICA.DesiredHRes = 1024
$ICA.DesiredVRes = 768
$ICA.DesiredColor = [WFICALib.ICAColorDepth]::Color16bit
$ICA.Connect()
This will connect an ICA session. To view all event available, we can use the following code:
[System.Reflection.Assembly]::LoadFile("C:\Program Files (x86)\Citrix\ICA Client\WfIcaLib.dll")
$ICA = New-Object WFICALib.ICAClientClass
$ICA | Get-Member -MemberType Event
This will output the following:
Name MemberType Definition ---- ---------- ---------- OnACRReconnected Event WFICALib._IICAClientEvents_OnACRReconnectedEventHandler OnACRReconnected() OnACRReconnectFailed Event WFICALib._IICAClientEvents_OnACRReconnectFailedEventHandler OnACRReconnectFail... OnCGPDisconnect Event WFICALib._IICAClientEvents_OnCGPDisconnectEventHandler OnCGPDisconnect() OnCGPReconnect Event WFICALib._IICAClientEvents_OnCGPReconnectEventHandler OnCGPReconnect() OnCGPUnwarn Event WFICALib._IICAClientEvents_OnCGPUnwarnEventHandler OnCGPUnwarn() OnCGPWarn Event WFICALib._IICAClientEvents_OnCGPWarnEventHandler OnCGPWarn() OnChannelDataReceived Event WFICALib._IICAClientEvents_OnChannelDataReceivedEventHandler OnChannelDataRece... OnClick Event WFICALib._IICAClientEvents_OnClickEventHandler OnClick(System.Int32, System.In... OnConnect Event WFICALib._IICAClientEvents_OnConnectEventHandler OnConnect() OnConnectFailed Event WFICALib._IICAClientEvents_OnConnectFailedEventHandler OnConnectFailed() OnConnecting Event WFICALib._IICAClientEvents_OnConnectingEventHandler OnConnecting() OnDisconnect Event WFICALib._IICAClientEvents_OnDisconnectEventHandler OnDisconnect() OnDisconnectFailed Event WFICALib._IICAClientEvents_OnDisconnectFailedEventHandler OnDisconnectFailed() OnDisconnectSessions Event WFICALib._IICAClientEvents_OnDisconnectSessionsEventHandler OnDisconnectSessio... OnDisconnectSessionsFailed Event WFICALib._IICAClientEvents_OnDisconnectSessionsFailedEventHandler OnDisconnect... OnICAFile Event WFICALib._IICAClientEvents_OnICAFileEventHandler OnICAFile() OnICAFileFailed Event WFICALib._IICAClientEvents_OnICAFileFailedEventHandler OnICAFileFailed() OnInitializing Event WFICALib._IICAClientEvents_OnInitializingEventHandler OnInitializing() OnInitialProp Event WFICALib._IICAClientEvents_OnInitialPropEventHandler OnInitialProp() OnLogoffFailed Event WFICALib._IICAClientEvents_OnLogoffFailedEventHandler OnLogoffFailed() OnLogoffSessions Event WFICALib._IICAClientEvents_OnLogoffSessionsEventHandler OnLogoffSessions(Syste... OnLogoffSessionsFailed Event WFICALib._IICAClientEvents_OnLogoffSessionsFailedEventHandler OnLogoffSessions... OnLogon Event WFICALib._IICAClientEvents_OnLogonEventHandler OnLogon() OnLogonFailed Event WFICALib._IICAClientEvents_OnLogonFailedEventHandler OnLogonFailed() OnPublishedApp Event WFICALib._IICAClientEvents_OnPublishedAppEventHandler OnPublishedApp() OnPublishedAppFailed Event WFICALib._IICAClientEvents_OnPublishedAppFailedEventHandler OnPublishedAppFail... OnReadyStateChange Event WFICALib._IICAClientEvents_OnReadyStateChangeEventHandler OnReadyStateChange(S... OnSessionAttach Event WFICALib._IICAClientEvents_OnSessionAttachEventHandler OnSessionAttach(System.... OnSessionDetach Event WFICALib._IICAClientEvents_OnSessionDetachEventHandler OnSessionDetach(System.... OnSessionEventPending Event WFICALib._IICAClientEvents_OnSessionEventPendingEventHandler OnSessionEventPen... OnSessionSwitch Event WFICALib._IICAClientEvents_OnSessionSwitchEventHandler OnSessionSwitch(System.... OnWindowCloseRequest Event WFICALib._IICAClientEvents_OnWindowCloseRequestEventHandler OnWindowCloseReque... OnWindowCreated Event WFICALib._IICAClientEvents_OnWindowCreatedEventHandler OnWindowCreated(System.... OnWindowDestroyed Event WFICALib._IICAClientEvents_OnWindowDestroyedEventHandler OnWindowDestroyed(Sys... OnWindowDisplayed Event WFICALib._IICAClientEvents_OnWindowDisplayedEventHandler OnWindowDisplayed(Sys... OnWindowDocked Event WFICALib._IICAClientEvents_OnWindowDockedEventHandler OnWindowDocked() OnWindowFullscreened Event WFICALib._IICAClientEvents_OnWindowFullscreenedEventHandler OnWindowFullscreen... OnWindowHidden Event WFICALib._IICAClientEvents_OnWindowHiddenEventHandler OnWindowHidden(System.In... OnWindowMaximized Event WFICALib._IICAClientEvents_OnWindowMaximizedEventHandler OnWindowMaximized() OnWindowMinimized Event WFICALib._IICAClientEvents_OnWindowMinimizedEventHandler OnWindowMinimized() OnWindowMoved Event WFICALib._IICAClientEvents_OnWindowMovedEventHandler OnWindowMoved(System.Int3... OnWindowRestored Event WFICALib._IICAClientEvents_OnWindowRestoredEventHandler OnWindowRestored() OnWindowSized Event WFICALib._IICAClientEvents_OnWindowSizedEventHandler OnWindowSized(System.Int3... OnWindowUndocked Event WFICALib._IICAClientEvents_OnWindowUndockedEventHandler OnWindowUndocked()
Like I said; a lot of available events. I will focus on the following events:
- OnConnectFailed
- OnLogon
- OnLogonFailed
Attaching to an Event
To attach to an event in PowerShell, you can use the following CmdLet:
Register-ObjectEvent
It will need an input object (the ICAClientClass Object), an event to register and the action to take as parameters. For example, to register to the OnLogon event:
Register-ObjectEvent -InputObject $ICA -EventName OnLogon -Action { Write-Host "Logged on" }
This code will write “Logged on” in the PowerShell console when the OnLogon event is initiated. Pretty easy right?
So the code should look as follows if we add the events:
[System.Reflection.Assembly]::LoadFile("C:\Program Files (x86)\Citrix\ICA Client\WfIcaLib.dll")
$ICA = New-Object WFICALib.ICAClientClass
$ICA.Address = "XASRV001"
$ICA.Username = "TestUser01"
$ICA.SetProp("Password","MyUsersPassword")
$ICA.Domain = "LAB"
$ICA.Application = ""
$ICA.Launch = $true
$ICA.OutputMode = [WFICALib.OutputMode]::OutputModeNormal
$ICA.DesiredHRes = 1024
$ICA.DesiredVRes = 768
$ICA.DesiredColor = [WFICALib.ICAColorDepth]::Color16bit
Register-ObjectEvent -InputObject $ICA -EventName OnConnectFailed -Action { Write-Host "Connection failed..." }
Register-ObjectEvent -InputObject $ICA -EventName OnLogonFailed -Action { Write-Host "Logon failed..." }
Register-ObjectEvent -InputObject $ICA -EventName OnLogon -Action { Write-Host "User has logged on..." }
$ICA.Connect()
You should see something like this:
PS C:\Users\Administrator> $ICA.Connect() PS C:\Users\Administrator> User has logged on...
Note that the “User has logged on…” string can appear later, since the Connect() method is asynchronous. Hope this post was usefull for you. In my next post, I will be talking about simulation keyboard and mouse in the ICA session.
Great post and tutorial! Thank you
Well written post and I’m able to open session and send keys to the remote session, but I’m not seeing any events. I’ve created watchers for all type of events as a test, still none of them are fired through the course of the session, including disconnect and logoff.
Is there any common setting or security config that is required?
Thanks. But I’m not aware of any security settings or configuration other than registry settings needed for the SimulationAPI to allow input. The events should just fire without configuration. However, I did write this article quite some time ago. So it could be that Citrix changed something here…
Hi Floris,
Great series of posts – many thanks for taking the trouble.
However, when I try the script, I’m unable to connect to the Xen-App server.
I populated the script values from the ICA file used to access the Application.
Using the ICA file directly brings up the App correctly.
However, when I try the Power-Shell script, I’m getting the following errors:
– “$ICA.Address : Connection failed…”
– “$ICA.Address : Logon failed…”
The ‘XEN1_Failed.TXT’ file simply contains “.Address : Connection failed…”.
How can I get more information on debugging this issue ?
Hi Srini,
the fact that you don’t see the actual address is more a PowerShell issue than an ICA Client Object issue. Try this:
Write-Host “$($ICA.Address): Connection failed…”
If you want to use a PowerShell object property between quotes, you will need to put parentheses around the object. If you would use it like this:
Write-Host “$ICA.Address: Connection failed…”
Only the “$ICA” will be considered as a variable. Hope this helps you out.
Hi Floris,
In continuation of my query above, I tried printing the error ( GetLastError ).
Turns out the error is actually error number 13 ( ICO_ERROR_UNSUPPORTED_FUNCTION ).
Any insights into why this error would occur while trying to establish the connection ?
Is this a version issue ?
Hi Floris,
still very great article, tested this on different machines with Citrix Online Plugin / Receiver installed.
The SimulationApi itself works fine, but somehow i can get events working only on one machine. Don’t know where the differences are, have the same client versions installed and both are x64 machines. But only one of the machines shows the events.
Like Doncsi asked, are there any further settings or security configs?
Just wrote a reply to Donsci’s question. Long story short… No clue. 😉 Maybe Citrix changed something in the API (this article is quite old already :)).
I tested it with different ica Client Versions, and after a Bit more researches i found out, that the event subscription works, but only with ps2.0, after updating wsmanagement framework the subscription doesn’t work.
So i think clientversion doesn’t really matter.
Can you say me if it works with powershell versions greater than 2.0 at your site?
Btw.: thanks for your incredible fast response;)
For any interested:
In my project a used the workaround to start ‘powershell -version 2.0’ and do the work there.
Not nice but works in my case.
I think this is a really strange issue. Because the events aren’t fired or catched in ps4.0, but if i use New-PSsession in same powershell instance the ‘long time ago’ occured event is fired.
Hi Floris,
great tutorials but I have one issue. I am testing those events and those works fine:
* OnConnect
* OnConnectFailed
* OnLogon
But I can’t get any of those:
* OnPublishedAppFailed
* OnPublishedApp
And of course application starts successfully… Any ideas why OnPublishedApp won’t appear?
Hi Floris,
Just to inform that on Windows 10 64-bit events (using “Citrix Receiver”) do not fire. Including OnConnect, OnLogon, etc. But I guess I do have some solutions when using XenApp or XenDesktop (which I do not have) … see below. Any workarounds are still welcome though for “Citrix Receiver”.
I tried the following
* Used Powershell 1.0 (using full path to powershell.exe) and 5.0
* Always used x86 (for the compatibility with the DLL).
* Registered an object-event, as well an inline function / sub as an event. Do note that the events get registered though (viewed with Get-EventSubscriber).
* Using the visible events (using get-member) such as OnWindowMinized.
* Set up the event before / after the Connect() call.
* Set up the event during the MonitoringCCMSession moment.
* Created a new-object WFICALib.ICAClient instead of WFICALib.ICAClientClass. Do note that all events work using WFICALib.ICAClient in a .Net application (project referring to the wfica.ocx).
* Used an existing Session (created via the webportal) as well using the powershell code to create a new Session.
* Gave the script the time using Sleep when session was not active yet.
* Pauzed the script with Read-Host before StopMonitoringCCMSession was called.
WMI namespace root/citrix is not available on workstation with only “Citrix Receiver”, thus registering WMI events are not possible for me. But could be a solution to others with XenApp or XenDesktop.
I did note another article at address below saying the events only work when the code is wrapped within Javascript. Using meadco would solve this (did not tried it, because not free).
http://discussions.citrix.com/topic/49009-scripting-the-icaclient-via-wsh-and-vbscript/page-2
.Net example on Citrix website
https://www.citrix.com/blogs/2010/03/02/fun-with-the-ica-client-object-ico-and-net-console-applications
Using inline events
https://social.technet.microsoft.com/wiki/contents/articles/25911.how-to-add-a-powershell-gui-event-handler-part-1.aspx