Getting Started with the Citrix XenApp PowerShell SDK and C#

In XenApp 6, MFCOM is out and PowerShell is in. This post is the first in a series to help you understand how to develop appliations that utilize the Citrix XenApp 6 PowerShell SDK and Microsoft C#.

At BriForum 2010, Brandon Shell and I presented a session on how to make the transition from MFCOM to PowerShell.  At the end of the session, I presented several examples on how to use the XenApp PowerShell SDK in C#.  I wanted to share some of the details on those examples in a few blog posts.  This first blog post will detail what is needed to get started developing applications that leverage the Citrix XenApp 6 PowerShell SDK.

What you need

To get started, you need to set up a development environment.  You really only need two things:

Actually, there isn’t anything set in stone that says you *have* to use Visual Studio, but it will make your life a whole lot easier.  I recommend installing Visual Studio on a XenApp server because remoting in PowerShell is less than desirable for these examples.

Creating your first project

After you install Visual Studio and the Citrix XenApp 6 PowerShell SDK, you are ready to get started with your first project.  The examples I will be showing will be web projects.  So, launch Visual Studio and select  File > New > Project…

Visual Studio New Project

VSNewProject

Add a Reference to System.Management.Automation

After you create your Project, you need to add a reference to System.Management.Automation.dll in order to do stuff with PowerShell in your project.  If you go looking for this DLL in the file system, you will find it at %ProgramFiles%\Reference Assemblies\Microsoft\WindowsPowerShell\v1.0 <- DO NOT USE THIS FILE.  The version of System.Management.Automation you want is in the GAC.

Normally, if you want to add a reference to an assembly that lives in the GAC to your project, you can just right-click your project in Visual Studio, select Add Reference and browse for the name.  But, for some reason, this assembly isn’t like the others.  You actually have to close your project in Visual Studio and manually add a reference to System.Management.Automation by editing the .csproj file.  For example, if your project name was WebApplication1, you would need to edit WebApplication1.csproj (you can use Notepad to edit this file if you like since this file is just XML) and manually add:

<Reference Include=”System.Management.Automation” />

 

Once you manually add this reference to your project file, you will want to add a couple of using statement to your code files that will deal with PowerShell:

using System.Management.Automation;
using System.Management.Automation.Runspaces;

 

To Wrap or not to Wrap

There are basically two ways to use the Citrix XenApp 6 PoweShell SDK in a C# project:

  1. Use “traditional” PowerShell Runspace (uses common PowerShell Runspaces)
  2. Use the XenApp 6 wrapper assemply (wraps each command and paramter in a Class for safe typing)

There are pros and cons for both:

“Traditional” PowerShell Runspace pros:

  • Easy to convert existing PowerShell scripts to C#.
  • You can log all the PowerShell commands and save before running – kind or like Microsoft Exchange 2007 does.

“Traditional” PowerShell Runspace cons:

  • No type safety – meaning that commands and parameters are specified as strings – which means you can mess up by typing the wrong string making troubleshooting difficult.
  • No IntelliSense for XenApp commands/odjects in Visual Studio.

XenApp 6 Wrapper pros:

  • Type safety.  Every command and parameter is wrapped in a class so there is no chance of misspelling a string parameter or passing an incorrect parameter.
  • Enables IntelliSense in Visual Studio.

XenApp 6 Wrapper cons:

  • Does not translate well to PowerShell commands.  For instance, the PowerShell command to get an application is Get-XAApplication.  The wrapper assembly’s command is GetXAApplicationByName().

I like using the wrapper assembly personally, but in the end it is all the same.

What’s Next?

I’ll be writing a few more posts on concrete examples of using the XenApp 6 PowerShell SDK.  Stay tuned…

MFCOM to PowerShell: How to Make the Transition

MFCOM has been the de facto standard for programmatically interfacing with Citrix XenApp. Whether you wanted to write a simple script or develop an application that interfaced with XenApp, MFCOM was the answer. Now, Citrix is committed to building their management architecture on PowerShell–not just for XenApp, but for all Citrix products. That’s great news for standardization across platforms and aligning with Microsoft on using PowerShell for management architectures. Now, the question is how do you take what you know about MFCOM and translate that to PowerShell?

As you may of may not already know, Citrix has committed to building their management architecture (and SDK) on PowerShell – not just for XenApp, but for all Citrix products.

In XenApp 6.0, MFCOM is not available anymore. The underlying architecture has changed dramatically enough to make backward compatibility with MFCOM impossible. The replacement for MFCOM is PowerShell. MFCOM-based scripts need to be completely re-written in XenApp cmdlets. In most cases, the conversion should be simple and most MFCOM scripts can be replaced with one-liner PowerShell commands.

Source: Citrix XenApp 6 PowerShell SDK reference manual.

That’s great news for standardization across platforms and aligning with Microsoft on using PowerShell for management architectures.  But, that begs the question – what do you do about all those scripts and applications that leverage MFCOM going forward?  I’ll be presenting a session at BriForum 2010 with Brandon Shell about this very topic.  The session will cover:

  • General Object Orientation
  • Specific Citrix XenApp objects
  • Examples of how scripts and applications were done with MFCOM
  • Converting scripts and applications to use PowerShell
  • PowerShell remoting
  • Availability of PowerShell cmdlets on XenApp 5 and XenApp 6
  • C# applications leveraging the PowerShell command wrapper

BriForum takes place from June 15th to June 17th at the Hilton Chicago Hotel.  There is still time to register.

Project Mobius Beta 2.1

Migrating or maintaining multiple Citrix farms? Project Mobius is a Microsoft Windows application that allows you to drag and drop published applications and/or folders from one Citrix Presentation Server farm to one or more separate Citrix Presentation Server farms.

Project Mobius Beta 2.1 includes some visual enhancements as well as some bug fixes. The main bug fixed in Project Mobius Beta 2.1 addresses an issue when migrating applications from a Citrix MetaFrame XP farm to a Citrix Presentation Server 3.0 or above farm. You may receive an error that states:

Failed to copy published application ({App_Name}).

Details: Unable to cast COM object of type ‘System.__ComObject’ to interface type ‘MetaFrameCom.IMetaFrameApplication4′, This operation failed because the QueryInterface call on the COM component for the interface with IID'{ED62F58D-63C2-11D4-94D8-00C04FB0F326}’ failed due to the following error: no such interface supported (Exception from HRESULT: 0x80004002 {E_NOINTERFACE)).

This issue has been resolved in the latest code.

  Download Project Mobius Beta 2.1

While we’re on the topic of Project Mobius, let me quickly address Project Mobius Beta 3. Project Mobius Beta 3 will include a “best effort” policy migration. What does a “best effort” policy migration mean you may ask? To explain this, I first need to tell you about my adventures with policies in MFCOM. Let’s just say that the stability of policy manipulation in MFCOM is, um, less that 100%. I consistently received errors on certain methods when trying to manipulate polices programmatically that, according to the documentation, should have worked. That being said, I almost scrapped Beta 3 of Project Mobius altogether.

Fast forward to BriForum Europe 2007. I was chatting with Shawn Bass and Thomas Koetzing during a break and relaying my frustration concerning the roadblocks I was running into with programmatically manipulating policies via MFCOM. Then, a suggestion was made to me. Why not migrate everything you can in code. Then, create a report on anything that failed during the process. That way, you can get 85% – 90% of the way there programmatically on the policy settings and only have to do 10% – 15% manually. That sounded good to me, so I resurrected Beta 3 and started to implement this “best effort” policy migration. Look for this in Project Mobius Beta 3.

Project Mobius Beta 2

Migrating or maintaining multiple Citrix farms? Project Mobius is a Microsoft Windows application that allows you to drag and drop published applications and/or folders from one Citrix Presentation Server farm to one or more separate Citrix Presentation Server farms.

One of the most popular ways to migrate from one Citrix Presentation Server farm to a new Citrix Presentation Server farm is to build the farms in parallel and use Web Interface to aggregate the two separate farms’ published applications. This is a great strategy and I have used parallel farms many times in the past to migrate users to a new farm. One of the challenges of this strategy is duplicating published applications and policies from the old farm to the new farm. Traditionally, you would need to either manually create each published application in the new farm or use scripting to export/import published applications. This is where Project Mobius comes in. Project Mobius is a Microsoft Windows application that allows you to drag and drop published applications and/or folders from one Citrix Presentation Server farm to one or more separate Citrix Presentation Server farms. Project Mobius currently only has capabilities to migrate published applications and content, but the capability to migrate policies is slated for a future release.

  Download Project Mobius Beta 2

What’s New in Beta 2?
The following enhancements have been made for Beta 2:

  • Supports migrating published content.
  • Supports migrating content redirection file type associations.
  • Supports migrating nearly all application settings using a “least common denominator” methodology. This means that applications can be migrated upward or downward across Citrix platforms. For instance, a published application can be migrated from a MetaFrame XP farm to a Presentation Server 4.5 farm. Or, vice versa, a published application can be migrated from a Presentation Server 4.5 farm to a MetaFrame XP farm.
  • Numerous visual feedback enhancements.
  • No policy migration yet. I am still working on getting the bugs ironed out of policy migration. I have a lot of the policy migration code written, but it is still a little “less than stable” so I excluded it from the latest build. If you would like to be a tester for Beta 3 (with policy migration), shoot me an email.

* Special thanks goes to David Taig for enhancement suggestions and testing the various builds of Project Mobius.
Project Mobius requires Microsoft .Net Framework version 2.0.

Installation

Project Mobius utilizes MFCOM to perform application migration. Thus, Project Mobius must be run from either a Citrix Presentation Server or a workstation that has the Citrix Presentation Server SDK installed and registered for DCOM (utilizing mfreg.exe).

Project Mobius does not require an install. Simply copy Mobius.exe as well as Interop.MetaFrameCOM.dll to a location on your Presentation Server (or workstation).

Tested Platforms
The MFCOM interfaces and methods used in the source code for Project Mobius should be compatible with Citrix MetaFrame XP 1.0 and above. However, Project Mobius has specifically been tested on the following platforms:

  • Citrix MetaFrame XP FR3 (Microsoft Windows 2000)
  • Citrix Presentation Server 3.0 (Microsoft Windows 2003)
  • Citrix Presentation Server 4.0 (Microsoft Windows 2003)
  • Citrix Presentation Server 4.5 (Microsoft Windows 2003)

Using Project Mobius

Step 1 – Click File -> Connect to Farm. Then, specify any Citrix Presentation/MetaFrame Server in any farm you want to manage.  Project Mobius uses the specified server to enumerate all published applications and folders in a given farm.  Repeat this step for any additional farms you want to manage. (Tip: you may also right click on the Enterprise Farms tree node or click the Connect to Farm icon to connect to a farm.

Connect to Farm
Click to enlarge Click to enlarge


Step 2
– Highlight a folder in the left hand tree view containing the published applications and folders you want to migrate.  Drag and drop the published applications and folders from the right hand side to the appropriate location in any farm on the left hand side. (Tip: you may use Ctrl or Shift to select multiple published applications or folders).

Farm Applications
Click to enlarge Click to enlarge


Optional
– Farms that have a large number of applications may take several minutes to enumerate all published applications.  This is due to the fact that Project Mobius has to use the LoadData() method of the IMetaFrameApplication interface for each published application in order to retrieve the application object and bind the object to the tree view.  This can be time consuming as each call to LoadData retrieves all properties for a published application.  To mitigate this time consuming process, click on Tools -> Options.  Then, select Enable dynamic population.  This option will only load published applications for the selected folder.  Each time you highlight a new folder, Project Mobius will dynamically retrieve the published applications within the folder.

Options
Click to enlarge Click to enlarge

Trivial Information
For those of you still reading and wondering why this piece of software is called Project Mobius, let me explain. Citrix code names Presentation Server after rivers (Hudson = Presentation Server 3.0; Colorado = Presentation Server 4.0; Ohio = Presentation Server 4.5; etc.). I was pondering what to name this project and I decided to name products after wakeboard tricks. One wakeboard trick that has a cool sounding name in my opinion is called a Mobius. A Mobius is a back side roll (flip) with a 360 degree handle pass rotation.  If you want to see what it looks like, check out this video.  So, all in all, this project has no hidden tie in to the wakeboarding Mobius.  I just think it is a cool name (and trick).

Project Mobius Beta 1

Migrating or maintaining multiple Citrix farms? Project Mobius is a Microsoft Windows application that allows you to drag and drop published applications and/or folders from one Citrix Presentation Server farm to one or more separate Citrix Presentation Server farms.

One of the most popular ways to migrate from one Citrix Presentation Server farm to a new Citrix Presentation Server farm is to build the farms in parallel and use Web Interface to aggregate the two separate farms’ published applications. This is a great strategy and I have used parallel farms many times in the past to migrate users to a new farm. One of the challenges of this strategy is duplicating published applications and policies from the old farm to the new farm. Traditionally, you would need to either manually create each published application in the new farm or use scripting to export/import published applications. This is where Project Mobius comes in. Project Mobius is a Microsoft Windows application that allows you to drag and drop published applications and/or folders from one Citrix Presentation Server farm to one or more separate Citrix Presentation Server farms. Project Mobius currently only has capabilities to migrate published applications, but the capability to migrate policies is slated for a future release.

  Download Project Mobius Beta 1

Installation
Project Mobius requires Microsoft .Net Framework version 2.0.

Project Mobius utilizes MFCOM to perform application migration. Thus, Project Mobius must be run from either a Citrix Presentation Server or a workstation that has the Citrix Presentation Server SDK installed and registered for DCOM (utilizing mfreg.exe).

Project Mobius does not require an install. Simply copy Mobius.exe as well as Interop.MetaFrameCOM.dll to a location on your Presentation Server (or workstation).

Tested Platforms
The MFCOM interfaces and methods used in the source code for Project Mobius should be compatible with Citrix MetaFrame XP 1.0 and above. However, Project Mobius has specifically been tested on the following platforms:

  • Citrix MetaFrame XP FR3
  • Citrix Presentation Server 3.0
  • Citrix Presentation Server 4.0
  • Citrix Presentation Server 4.5

Using Project Mobius

Step 1 – Click File -> Connect to Farm. Then, specify any Citrix Presentation/MetaFrame Server in any farm you want to manage.  Project Mobius uses the specified server to enumerate all published applications and folders in a given farm.  Repeat this step for any additional farms you want to manage. (Tip: you may also right click on the Enterprise Farms tree node or click the Connect to Farm icon to connect to a farm.

Connect to Farm
Click to enlarge Click to enlarge


Step 2
– Highlight a folder in the left hand tree view containing the published applications and folders you want to migrate.  Drag and drop the published applications and folders from the right hand side to the appropriate location in any farm on the left hand side. (Tip: you may use Ctrl or Shift to select multiple published applications or folders).

Farm Applications
Click to enlarge Click to enlarge


Optional
– Farms that have a large number of applications may take several minutes to enumerate all published applications.  This is due to the fact that Project Mobius has to use the LoadData() method of the IMetaFrameApplication interface for each published application in order to retrieve the application object and bind the object to the tree view.  This can be time consuming as each call to LoadData retrieves all properties for a published application.  To mitigate this time consuming process, click on Tools -> Options.  Then, select Enable dynamic population.  This option will only load published applications for the selected folder.  Each time you highlight a new folder, Project Mobius will dynamically retrieve the published applications within the folder.

Options
Click to enlarge Click to enlarge

Trivial Information
For those of you still reading and wondering why this piece of software is called Project Mobius, let me explain. Citrix code names Presentation Server after rivers (Hudson = Presentation Server 3.0; Colorado = Presentation Server 4.0; Ohio = Presentation Server 4.5; etc.). I was pondering what to name this project and I decided to name products after wakeboard tricks. One wakeboard trick that has a cool sounding name in my opinion is called a Mobius. A Mobius is a back side roll (flip) with a 360 degree handle pass rotation.  If you want to see what it looks like, check out this video.  So, all in all, this project has no hidden tie in to the wakeboarding Mobius.  I just think it is a cool name (and trick).

MFCOM Script to List Applications Only in Specified Folders

MFCOM Script to List Applications Only in Specified Folders

Here is a quick MFCOM script to list all the published applications and folders in a specified folder or folders. There are two options for using the script. Option one takes any number of command line arguments. Each command line argument represents a folder name. Option two takes no command line arguments and relies on hard-coded folder names within the script.

GetAppsInFolders.zip

Suppose you had the following tree structure for your published applications:

   

Now, say you wanted to run a script that only returned applications in the Testing folder and Microsoft Applications folder. To accomplish this, run the following at a command prompt: 

cscript //Nologo GetAppsInFolders.wsf  “Testing” “Microsoft Applications”

The above command produces the following results:

Note that every folder specified is a child of the “Applications” folder.  To specify a folder that is not a child of the “Applications” folder, you must specify the path relative from “Applications”.  For instance, if you wanted to get only the applications published in the “New Folder” under “Testing”, run the following command:

cscript //Nologo GetAppsInFolders.wsf  “Testing/New Folder”

The above command produces the following results:

To set up the hard-coded folders, open the script in a text editor and look for the following lines (starting around line 31):

    '
    ' If no command line arguments, use hard-coded folders
    '
    if  WScript.Arguments.Count = 0 Then
        ReDim arrFolders(2)
        arrFolders(0) = "Testing"
        arrFolders(1) = "Microsoft Applications"
    Else

Change ReDim arrFolders(2) to ReDim arrFolders(x) where x represents the number of folders you want to hard code.
Next, add arrFolders(n) = “Folder Name” for each folder you want to hard code (where n is a distinct number between 0 and x).

So what is all this good for anyway?  Suppose you wanted to export applications in a few select folders, then import those applications in to a different farm.  This Citrix article demonstrates how to use EXPORT and NEWAPP from the Citrix APSDK.  Using EXPORT and NEWAPP along with GetAppsInFolders.wsf, you can export bulk applications from select specified folders and then import those applications into a different farm.

Visual MFCOM Explorer

Have you ever wanted to delve into the intricacies of MFCOM? Using this web application, you can browse the various MFCOM properties using the Citrix Presentation Server Console as your guide.

If you are like me, you have read the MFCOM documentation and found it pretty thorough. But, I found myself printing out screen shots of the Citrix Presentation Server Console and making notes of the various MFCOM properties that corresponded to the sections of the GUI. So, what I decided to do was share my notes in an electronic format. Thus, the Visual MFCOM Explorer was created. Visual MFCOM Explorer is a web application used to browse the various MFCOM properties using the Citrix Presentation Server Console as your guide.

Go to the Visual MFCOM Explorer website.

Note: this is a work in progress, but I decided to share what I have so far with the community.