Now that the XenApp 6.0 Server SDK download is available at http://community.citrix.com/display/xa/XenApp+6+PowerShell+SDK, many people will be excited to try out the functionality for themselves.  This is a quick primer to get people off on the right foot.  This article assumes that you have already downloaded the XenApp 6.0 Server SDK and have installed it on your XenApp 6 server.

First, let’s examine what is in the SDK download.  Once you install it, you will see some new entries in your start menu, under the “Citrix\XenApp Server SDK” folder.  Here you’ll find a link to a help file containing help about all of the PowerShell commands and the Group Policy Provider that are used to configure a XenApp 6 server.  You will also find links that launch a PowerShell command prompt with the Citrix snap-ins already loaded, either in 32-bit or 64-bit mode.

If you have not used PowerShell on your system before, the first thing you must do is to change the default script execution policy.  PowerShell ships out-of-the-box with the execution policy set to “Restricted”. This execution policy will prevent any of the scripts included with the SDK from functioning, including the script that causes the snap-ins to be automatically loaded.  If your execution policy is set to Restricted, you can expect a nice, red error when you try to launch the SDK command prompt.  The error says:

File C:\Program Files\Citrix\XenApp Server SDK\Citrix.XenApp.Sdk.ps1 cannot be loaded because the execution of scripts is disabled on this system. Please see “get-help about_signing” for more details.
In addition to the about_signing help topic, you may want to review the meaning of the execution policies using the command:

Get-Help about_Execution_Policies

So the first thing you must do is to change the execution policy to allow at least signed scripts to run. I usually choose to set the execution policy to “RemoteSigned” since that provides protection against downloaded scripts but does not present any barriers when I write my own scripts.

Set-ExecutionPolicy RemoteSigned

Once the execution policy is set, you can launch the “Windows PowerShell with Citrix XenApp Server SDK” link from the start menu.  If you have chosen the “AllSigned” execution policy, you will be presented with this question:

Do you want to run software from this untrusted publisher?
File C:\Program Files\Citrix\XenApp Server SDK\Citrix.XenApp.Sdk.ps1 is published by CN=”Citrix Systems, Inc.”, OU=AVG Bangalore, OU=Digital ID Class 3 – Microsoft Software Validation v2, O=”Citrix Systems, Inc.”, L=Fort Lauderdale, S=Florida, C=US and is not trusted on your system. Only run scripts from trusted publishers.
[V] Never run  [D] Do not run  [R] Run once [A] Always run  [?] Help (default is “D”):

It is important that you select “[A] Always run” for this prompt.  If you do not, remote PowerShell sessions that are launched on the server will hang indefinitely.  Note that this problem does not happen if you use “RemoteSigned”, “Unrestricted”, or “Bypass” execution policies.

Once past the execution policy and certificate checks, you’ll see that three PowerShell snap-ins are automatically loaded:

Loading Citrix.Common.Commands snapin…
Loading Citrix.XenApp.Commands snapin…
Loading Citrix.Common.GroupPolicy snapin…

Two common questions you may have are:

  1. What do these three snap-ins each do?
  2. Why are there three snap-ins instead of just one?

To answer these questions:

Citrix.Common.Commands contains PowerShell cmdlets that are either used by multiple Citrix products, or which are not possible (nor necessary) to remote.

  • An example of the former is the cmdlet Get-CtxIcon.  This cmdlet can be used (and will be used in the future) by any Citrix product for which there is a need to extract icons from executables, DLLs, and icon libraries. Having this in a separate snap-in allows it to be shared when scripting against multiple Citrix products from the same client machine.
  • An example of the latter case is the cmdlet Get-CtxProfileApplication.  This cmdlet reads the manifest of a streamed application profile off of a network share. If the cmdlet were remoted, the remote server would typically be able toimpersonate but not delegate the user’s credentials.  If you don’t understand the terms, suffice it to say that the cmdlet would not have the proper credentials to access the network share, even if the user using the cmdlet was able to access the network share directly.  Having this in a separate snap-in allows it to be installed independently of the bulk of the XenApp cmdlets when installing on a client machine.

Citrix.XenApp.Commands contains all of the PowerShell cmdlets that interact with XenApp’s “Independent Management Architecture” (IMA) to read or edit configuration of all objects that are not stored in policies.  This includes applications, sessions, worker groups, administrators, load evaluators, and more.

Citrix.Common.GroupPolicy contains a PowerShell provider which is capable of reading and editing Citrix settings within policies.  These settings are used by multiple Citrix products.

These three snap-ins are installed under different scenarios, which is why they must be independent.

  • Citrix.Common.Commands is installed on XenApp servers, plus other Citrix product servers, plus any SDK client machine.
  • Citrix.XenApp.Commands is installed only on XenApp servers.  To use these commands from an SDK client machine, you must use PowerShell remoting.  This will be a blog topic for another day.
  • Citrix.Common.GroupPolicy is installed on XenApp servers, plus other Citrix product servers, plus any machine on which the Delivery Services Console or other Citrix product management consoles are installed, plus any SDK client machine, plus any machine where GPMC and GPEdit tools are used to manage Active Directory policies.

If you ever want to know what Citrix snap-ins are installed on the computer, you can use the PowerShell command:

Get-PSSnapIn -Registered

Look in the list for snap-ins whose name starts with “Citrix”.  If you want to add the snap-ins manually, for instance into a PowerShell console which you started from a different start menu link, you can use:

Add-PSSnapIn Citrix*

Next time, I’ll introduce the PowerShell commands provided within the Citrix.Common.Commands and Citrix.XenApp.Commands snap-ins.