ICA connections using Powershell – Part 3

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.Domain = "LAB"
$ICA.Application = ""
$ICA.Launch = $true
$ICA.OutputMode = [WFICALib.OutputMode]::OutputModeNormal
$ICA.DesiredHRes = 1024
$ICA.DesiredVRes = 768
$ICA.DesiredColor = [WFICALib.ICAColorDepth]::Color16bit

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:


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.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..." }

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.

13 thoughts to “ICA connections using Powershell – Part 3”

  1. 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?

    1. 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…

  2. 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 ?

    1. 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.

  3. 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 ?

  4. 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?

    1. 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 :)).

      1. 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;)

        1. 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.

  5. 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?

  6. 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).

    .Net example on Citrix website

    Using inline events

Leave a Reply

Your email address will not be published. Required fields are marked *

Complete the following sum: * Time limit is exhausted. Please reload CAPTCHA.