Being fairly new to PowerShell, but having a software development background, I knew this should be a very simple script to produce.  The client simply wanted a list of XenApp servers so they could look at the license server name and product edition.  The basics of the script are shown here (lines may wrap):

$Farm = Get-XAFarmConfiguration
$Servers = Get-XAServer
ForEach($Server in $Servers)
{
        $ServerConfig = Get-XAServerConfiguration -ServerName $Server.Servername
        Echo "Zone: " $server.ZoneName
        Echo "Server Name: " $server.ServerName
        Echo “Product Edition: “  $server.CitrixEdition
        If( $ServerConfig.LicenseServerUseFarmSettings )
        {
               Echo "License server: " $Farm.LicenseServerName
        }
        Else
        {
               Echo "License server: " $ServerConfig.LicenseServerName
        }
        Echo “”
}

Note: This script is only valid for XenApp 5 for both Server 2003 and Server 2008.  In XenApp 5, it is possible to edit each XenApp server and set a specific Citrix license server.  You could, in fact, have every XenApp server in a XenApp farm configured to use its own Citrix license server.  In XenApp 6, you can do the same thing but that would require the use of Citrix Computer polices, one for each server.

While the above script worked, it was almost useless.  With an extremely large number of servers, the output produced was unwieldy.  The customer gave me the product edition and license server name they wanted to validate against.  I updated the script with that new information and needed a way to filter the data.  PowerShell uses the traditional programming “If” statement to allow filtering the data as it is processed.  I added a variable for the license server name and an “If” statement to the script as shown below (PowerShell uses the character for line continuation. ):
<pre>$LicenseServerName = NEWLICCTX01.WEBSTERSLAB.COM
$Farm = Get-XAFarmConfiguration
$Servers = Get-XAServer
ForEach($Server in $Servers)
{
$ServerConfig = Get-XAServerConfiguration -ServerName $Server.Servername
If(($Server.CitrixEdition -ne "Platinum") -or
($ServerConfig.LicenseServerUseFarmSettings -eq $False `
–and $ServerConfig.LicenseServerName -ne $LicenseServerName))
{
<snip>
}
}
The “If” statement says:

• If the server’s product edition is not equal to “Platinum”
• Or, the server is not configured to use the farm settings for the license server and the server’s license server name is not equal to NEWLICCTX01.WEBSTERSLAB.COM
• Output the server’s information
• If neither condition is met, skip to the next entry in the list of servers

The new script allowed me to output just the XenApp servers matching the client’s criteria.

Sample output:

Zone: ZONE1
Server Name: Z1DCCTXSSO01A
Product Edition: Platinum
License server: oldlicctx01
Zone:  ZONE7
Server Name: Z7DCTRMCTX03J
Product edition: Enterprise
License server: NEWLICCTX01.WEBSTERSLAB.COM

Note:  The license server names shown in the sample output reflect the entry in the License Server name field for each XenApp server.  XenApp allows as valid entries the NetBIOS name, Fully Qualified Domain Name or IP Address.

Sweet, I have what the client needs, now let me just output this to HTML and I am done.

M:\PSScripts\Get-ServerInfo.ps1 | ConvertTo-Html | Out-File M:\PSScripts\MismatchedServers.html

This produced the following:

What the…?

I needed to find out what was going on here.  I typed in Get-ServerInfo.ps1 | Get-Member

TypeName: System.String

Name       MemberType            Definition
----             ----------            ----------
Clone            Method                System.Object Clone()
CompareTo        Method                int CompareTo(System.Object value), int CompareTo(string strB)
Contains         Method                bool Contains(string value)

<snip>

Next, I typed in Get-Help ConvertTo-HTML:

PS Z:\> Get-Help ConvertTo-HTML

NAME
ConvertTo-Html

SYNOPSIS
Converts Microsoft .NET Framework objects into HTML that can be displayed in a Web browser.

<snip>

What I see from these two pieces of information is that my script is outputting String (or text) and ConvertTo-Html is expecting an Object as input.

Oh, now I get it.  The light-bulb finally went off:  PowerShell wants OBJECTS, not Text.  DOH!!!

OK, so how do I change this script to output objects instead of text?  I found what I needed in Chapter 19 of Don Jones’ book Learn Windows PowerShell in a Month of Lunches.  This is going to be a lot easier than I thought because I am only working with four pieces of data.

All I had to do was change:

Echo "Zone: " $server.ZoneName
Echo "Server Name: " $server.ServerName
Echo “Product Edition: “  $server.CitrixEdition
If( $ServerConfig.LicenseServerUseFarmSettings )
{
       Echo "License server: " $Farm.LicenseServerName
}
Else
{
       Echo "License server: " $ServerConfig.LicenseServerName  
}
Echo “”

To:

$obj = New-Object -TypeName PSObject
$obj | Add-Member -MemberType NoteProperty `
-Name ZoneName -Value $server.ZoneName
$obj | Add-Member -MemberType NoteProperty `
-Name ServerName -Value $server.ServerName
$obj | Add-Member -MemberType NoteProperty `
-Name ProductEdition -Value $server.CitrixEdition
If($ServerConfig.LicenseServerUseFarmSettings)
{
       $obj | Add-Member -MemberType NoteProperty `
    -Name LicenseServer -Value $Farm.LicenseServerName
}
Else
{
       $obj | Add-Member -MemberType NoteProperty `
    -Name LicenseServer -Value $ServerConfig.LicenseServerName                    
}
Write-Output $obj

Running the command M:\PSScripts\Get-ServerInfo.ps1 | ConvertTo-Html | Out-File M:\PSScripts\MismatchedServers.html, now gives me the following results (Figure 1).

Perfect.  Now that the script is using objects for output, any of the ConvertTo-* or Export-To* cmdlets can be used.  But I wanted to take this adventure one step further.  The script uses a hard-coded license server name and product edition.  I want to turn the script into one that can be used by anyone and also make it an advanced function.

The first thing needed is a name for the function.  The purpose of the function is to Get XenApp Mismatched Servers.  Following the naming convention used by Citrix, Get-XANoun, the name could be Get-XAMismatchedServer.  Why XAMismatchedServer and not XAMismatchedServers?  PowerShell convention is to use singular and not plural.

Function Get-XAMismatchedServer
{
#PowerShell statements
}

There is more functionality that needs to be added to make this a more useful function.  Additionally, I want to learn how to turn this function into a proper PowerShell advanced function.  Some of the additions needed are:

1. Prevent the function from running on XenApp 6+
2. Allow the use of a single XenApp Zone to restrict the output
3. Validate the Zone name entered
4. Change the function to use parameters instead of hardcoded values
5. Add debug and verbose statements
6. Add full help text to explain the function

For the basis of turning this simple function into an advanced function, I am using Chapter 48 of Windows PowerShell 2.0 TFM by Don Jones and Jeffery Hicks.

The first thing I need to add to the function is the statement that tells PowerShell this is an advanced function.

Function Get-XAMismatchedServer
{
    [CmdletBinding( SupportsShouldProcess = $False, `
    ConfirmImpact = "None", DefaultParameterSetName = "" ) ]
}

Even though all parameters in CmdletBinding() are the defaults, I am including them solely for the learning exercise.

I will also need two “helper” functions.  One to verify the version of XenApp the script is being run under and the other for validating the Zone name entered (if one was entered).  These two functions need to be declared before they are used.  This means they need to be at the top of the script.

The function to verify if the script is running under XenApp 5:

Function IsRunningXenApp5
{
   Param( [string]$FarmVersion )
   Write-Debug "Starting IsRunningXenApp5 function"
   $XenApp5 = $false
   If($Farm.ServerVersion.ToString().SubString(0,1) -ne "6")
   {
     #this is a XenApp 5 farm, script can proceed
     $XenApp5 = $true
   }
   Else
   {
     #this is a not XenApp 5 farm, script cannot proceed
     $XenApp5 = $false
   }
   Write-Debug "Farm is running XenApp5 is $XenApp5"
   Return $XenApp5
}

Result of function under XenApp 5 (Figure 2).

Result of function under XenApp 6 (Figure 3).

The function to verify that if a zone name is entered, it is valid:

Function IsValidZoneName
{
   Param( [string]$ZoneName )
   Write-Debug "Starting IsValidZoneName function"
   $ValidZone = $false
   $Zones = Get-XAZone -ErrorAction SilentlyContinue
   If( -not $? )
   {
     Write-Error "Zone information could not be retrieved"
     Return $ValidZone
   }
   ForEach($Zone in $Zones)
   {
     Write-Debug "Checking zone $Zone against $ZoneName"
     Write-Verbose "Checking zone $Zone against $ZoneName"
     If($Zone.ZoneName -eq $ZoneName)
     {
        Write-Debug "Zone $ZoneName is valid $ValidZone"
        $Zones = $null
        $ValidZone = $true
     }
   }
   $Zones = $null
   Return $ValidZone
}

Result of the function (Figure 4).

Adding parameters to the main function:

Function Get-XAMismatchedServer
{
   [CmdletBinding( SupportsShouldProcess = $False,
   ConfirmImpact = "None", DefaultParameterSetName = "" ) ]

   Param( 
   [parameter(Position = 0,Mandatory=$true,
   HelpMessage = "Citrix license server name to match" )]
   [Alias("LS")]
   [string]$LicenseServerName,
   [parameter(Position = 1, Mandatory=$true,
   HelpMessage = "Citrix product edition to match: `
   Platinum, Enterprise or Advanced" )]
   [Alias("PE")]
   [ValidateSet("Platinum", "Enterprise", "Advanced")]
   [string]$ProductEdition,
   [parameter(Position = 2,Mandatory=$false, `
   HelpMessage = "XenApp zone to restrict search.  `
   Blank is all zones in farm." )]
   [Alias("ZN")]
   [string]$ZoneName = '' )
}

Three parameters have been added: $LicenseServerName, $ProductEdition and $ZoneName.  These parameter names were chosen because they are what the Citrix cmdlets use.

All three parameters are positional.  This means the parameter name is not required.  The function could be called as either:

Get-XAMismatchedServer -LicenseServerName CtxLic01 -ProductEdition Platinum -ZoneName EMEA

Or

Get-XAMismatchedServer CtxLic01 Platinum EMEA

The LicenseServerName and ProductEdition parameters are mandatory (Figure 5).

A help message has been entered so that if a parameter is missing, help text can be requested to tell what needs to be entered (Figure 6).

Complete function (lines may wrap):

Function IsRunningXenApp5
{
   Param( [string]$FarmVersion )
   Write-Debug "Starting IsRunningXenApp5 function"
   $XenApp5 = $false
   If($Farm.ServerVersion.ToString().SubString(0,1) -ne "6")
   {
     #this is a XenApp 5 farm, script can proceed
     $XenApp5 = $true
   }
   Else
   {
     #this is not a XenApp 5 farm, script cannot proceed
     $XenApp5 = $false
   }
   Write-Debug "Farm is running XenApp5 is $XenApp5"
   Return $XenApp5
}

Function IsValidZoneName
{
   Param( [string]$ZoneName )
   Write-Debug "Starting IsValidZoneName function"
   $ValidZone = $false
   $Zones = Get-XAZone -ErrorAction SilentlyContinue
   If( -not $? )
   {
     Write-Error "Zone information could not be retrieved"
     Return $ValidZone
   }
   ForEach($Zone in $Zones)
   {
     Write-Debug "Checking zone $Zone against $ZoneName"
     Write-Verbose "Checking zone $Zone against $ZoneName"
     If($Zone.ZoneName -eq $ZoneName)
     {
        Write-Debug "Zone $ZoneName is valid $ValidZone"
        $Zones = $null
        $ValidZone = $true
     }
   }
   $Zones = $null
   Return $ValidZone
}

Function Get-XAMismatchedServer
{
   <#
   .Synopsis
   Find servers not using the correct license server or
   product edition.
   .Description
   Find Citrix XenApp 5 servers that are not using the Citrix license
   server or product edition specified.  Can be restricted to a
   specific XenApp Zone.
   .Parameter LicenseServerName
   What is the name of the Citrix license server to validate servers
   against.  This parameter has an alias of LS.
   .Parameter ProductEdition
   What XenApp product edition should servers be configured to use.
   Valid input is Platinum, Enterprise or Advanced.
   This parameter has an alias of PE.
   .Parameter ZoneName
   Optional parameter.  If no XenApp zone name is specified, all zones
   in the farm are searched.
   This parameter has an alias of ZN.
   .Example
   PS C:\ Get-XAMismatchedServerInfo
   Will prompt for the Citrix license server name and product edition.
   .Example
   PS C:\ Get-XAMismatchedServerInfo -LicenseServerName CtxLic01 -ProductEdition Platinum
   Will search all XenApp zones in the XenApp 5 farm that the current XenApp 5 server
   is a member.  Any XenApp 5 server that is manually configured to use a different license
   server OR product edition will be returned.
   .Example
   PS C:\ Get-XAMismatchedServerInfo -LicenseServerName CtxLic01 -ProductEdition Platinum -ZoneName EMEA
   Will search the EMEA zone in the XenApp 5 farm that the current XenApp 5 server
   is a member.  Any XenApp 5 server that is manually configured to use a different license
   server OR product edition will be returned.
   .Example
   PS C:\ Get-XAMismatchedServerInfo -LS CtxLic01 -PE Enterprise -ZN Russia
   Will search the Russia zone in the XenApp 5 farm that the current XenApp 5 server
   is a member.  Any XenApp 5 server that is manually configured to use a different license
   server OR product edition will be returned.
   .Example
   PS C:\ Get-XAMismatchedServerInfo CtxNCC1701J Enterprise Cardassian
   Will search the dangerous Cardassian zone in the XenApp 5 farm that the current XenApp 5
   server is a member.  Any XenApp 5 server that is manually configured to use an inferior
   license server OR unworthy product edition will be returned (hopefully in one piece).
   .ReturnValue
   [OBJECT]
   .Notes
   NAME:         Get-XAMismatchedServerInfo
   VERSION:      .9
   AUTHOR:       Carl Webster (with a lot of help from Michael B. Smith)
   LASTEDIT:   May 16, 2011
   #Requires -version 2.0
   #Requires -pssnapin Citrix.XenApp.Commands
   #>
   [CmdletBinding( SupportsShouldProcess = $False, ConfirmImpact = "None", DefaultParameterSetName = "" ) ]
   Param(       [parameter(
   Position = 0,
   Mandatory=$true,
   HelpMessage = "Citrix license server name to match" )]
   [Alias("LS")]
   [string]$LicenseServerName,
   [parameter(
   Position = 1,
   Mandatory=$true,
   HelpMessage = "Citrix product edition to match: Platinum, Enterprise or Advanced" )]
   [Alias("PE")]
   [ValidateSet("Platinum", "Enterprise", "Advanced")]
   [string]$ProductEdition,
   [parameter(
   Position = 2,
   Mandatory=$false,
   HelpMessage = "XenApp zone to restrict search.  Blank is all zones in farm." )]
   [Alias("ZN")]
   [string]$ZoneName = '' )
   Begin
   {
     Write-Debug "In the BEGIN block"
     Write-Debug "Retrieving farm information"
     Write-Verbose "Retrieving farm information"
     $Farm = Get-XAFarm -ErrorAction SilentlyContinue
     If( -not $? )
     {
        Write-Error "Farm information could not be retrieved"
        Return
     }
     Write-Debug "Validating the version of XenApp"
     $IsXenApp5 = IsRunningXenApp5 $Farm.ServerVersion
     If( -not $IsXenApp5 )
     {
        Write-Error "This script is designed for XenApp 5 and cannot be run on XenApp 6"
        Return
     }
     If($ZoneName -ne '')
     {
        Write-Debug "Is zone name valid"
        Write-Verbose "Validating zone $ZoneName"
        $ValidZone = IsValidZoneName $ZoneName
        If(-not $ValidZone)
        {
          Write-Error "Invalid zone name $ZoneName entered"
          Return
        }
     }
   }
   Process
   {
     Write-Debug "In the PROCESS block"
     If($ZoneName -eq '')
     {
        Write-Debug "Retrieving server information for all zones"
        Write-Verbose "Retrieving server information for all zones"
        $Servers = Get-XAServer -ErrorAction SilentlyContinue | `
        sort-object ZoneName, ServerName
     }
     Else
     {
        Write-Debug "Retrieving server information for zone $ZoneName"
        Write-Verbose "Retrieving server information for zone $ZoneName"
        $Servers = Get-XAServer -ZoneName $ZoneName -ErrorAction SilentlyContinue | `
        sort-object ZoneName, ServerName
     }
     If( $? )
     {
        ForEach($Server in $Servers)
        {
          Write-Debug "Retrieving server configuration data for server $Server"
          Write-Verbose "Retrieving server configuration data for server $Server"
          $ServerConfig = Get-XAServerConfiguration -ServerName $Server.Servername `
          -ErrorAction SilentlyContinue
          If( $? )
          {
             If($Server.CitrixEdition -ne $ProductEdition -or `
              ($ServerConfig.LicenseServerUseFarmSettings -eq $False -and `
              $ServerConfig.LicenseServerName -ne $LicenseServerName))
             {
               Write-Debug "Mismatched server $server"
               Write-Verbose "Mismatched server $server"
               $obj = New-Object -TypeName PSObject
               $obj | Add-Member -MemberType NoteProperty `
                  -Name ZoneName -Value $server.ZoneName
               $obj | Add-Member -MemberType NoteProperty `
                  -Name ServerName -Value $server.ServerName
               $obj | Add-Member -MemberType NoteProperty `
                  -Name ProductEdition -Value $server.CitrixEdition
               If($ServerConfig.LicenseServerUseFarmSettings)
               {
                  $obj | Add-Member -MemberType NoteProperty `
                    -Name LicenseServer -Value $Farm.LicenseServerName
               }
               Else
               {
                  $obj | Add-Member -MemberType `
                    NoteProperty -Name LicenseServer `
                    -Value $ServerConfig.LicenseServerName
               }
               Write-Debug "Creating object $obj"
               write-output $obj
            }
          }
          Else
          {
             Write-Error "Configuration information for server `
                   $($Server.Servername) could not be retrieved"
          }
        }
     }
     Else
     {
        Write-Error "Information on XenApp servers could not be retrieved"
     }
   }
   End
   {
     Write-Debug "In the END block"
     $servers = $null
     $serverconfig = $null
     $farm = $null
     $obj = $null
   }
}

Here are the users in the Citrix License Administration Console (Figure 1).

Click Delete for the user account and click OK for the confirmation popup (Figure 2).

The license user account still exists (Figure 3).

To manually remove the license user account, an XML document must be edited.  Exit the Citrix License Administration Console.

The Citrix license user accounts are located in d:\Program Files\Citrix\Licensing\LS\conf\server.xml (where d: is the drive where Citrix Licensing is installed).  This XML document is in UTF-8 format and must be edited with an editor that can properly handle a UTF-8 file.  Open server.xml in your editor of choice (Figure 4).

Scroll down to the accessControl Tag (Figure 5).

Highlight the entire line which contains the desired license user account and delete the line (Figure 6).

Exit the editor saving your changes.  From the Services management console restart the Citrix Licensing service (Figure 7).

Note:   You can also click Start -> Run and type in net stop “citrix licensing” && net start “citrix licensing”

Start the Citrix License Administration Console, go to User Configuration and you will see that the license user account has been deleted (Figure 8).

Will a stand-alone Citrix License Server running in a Workgroup service the licensing requests for XenApp Servers running in multiple farms in multiple directory service systems?  Someone asked me this question and my first thought was yes it would.  But would it?

NOTE:  Most people believe that XenApp can only be installed on a network that uses either Active Directory or eDirectory.  That is not true.  XenApp can be installed on a stand-alone workgroup computer, as well as UNIX versions for Solaris, AIX, and HP-UX.

This test will need five servers running Windows Server 2003 R2 x86 with all Windows Updates.  The License Server will be a stand-alone server in a Workgroup.  Microsoft Active Directory will be used for the Directory Service.  Two Forests, each with one domain, will be built.  One XenApp Server will be in each Domain as domain members.

Two server Virtual Machines (VM) were built for the first Forest/Domain.  The Forest/Domain is called DomainA.com, with a Domain Admin account named AdminA with a password of P@$$w0rdA.

Two server VMs were built for the second Forest/Domain.  The Forest/Domain is called DomainB.net, with a Domain Admin account named AdminB with a password of P@$$w0rdB.

The License Server was built as a stand-alone server in a Workgroup named Citrix with a local administrator account named AdminC with a password of P@$$w0rdC.  The License Server is version 11.5.

Different user names and passwords were used to verify that the license server does no authentication of user credentials when checking out licenses.

The XenApp Server in DomainA is named CitrixA and the server in DomainB is named CitrixB.

A DNS “A” record was created in each domain for the name of the Citrix License Server, CitrixONE.

When XenApp is installed, one of the questions asked is the hostname of the license server.

The installer needs to be able to resolve the name to an IP address.  If there is no DNS record for the license server, name resolution fails and you receive an error message that the license server cannot be contacted.

The Citrix Farm in DomainA is named FarmA, the Farm in DomainB is named FarmB.  Both XenApp servers are running XenApp 5 for Server 2003 – Platinum Edition with Hotfix Rollup Pack #3.

On CitrixA the Notepad text editor was published and on CitrixB, Microsoft Paint was published.

To begin the test both CitrixA and CitrixB were powered off.

This screen shows no Server Start-up licenses or Citrix XenApp Platinum licenses checked out.

CitrixA in DomainA.com was then powered on.

This shows that one Citrix Start-up License has been checked out.

CitrixB in DomainB.net was then powered on.

This shows that two Citrix Start-up licenses have now been checked out.  Click the box next to the number 2 in the In Use column to get a detailed usage report on the checked out licenses.

Here you see the Fully Qualified Domain Names of the two XenApp servers.

Program Neighborhood was used to run the Notepad published application on CitrixA.

This shows that one Citrix XenApp Platinum Concurrent User license has been checked out.

Program Neighborhood was used to run the Paint published application on CitrixB.

This shows that two Citrix XenApp Platinum Concurrent User licenses have been checked out.

Will a stand-alone Citrix License Server running in a Workgroup service the licensing requests for XenApp Servers running in multiple farms in multiple directory service systems?  Yes.

It does not matter what user accounts were used in installing the Citrix License Server or XenApp 5.  It does not matter what user accounts are set up on the license server or used to run the published applications.  The Citrix License Server simply listens, by default, on TCP Port 27000 for license requests.  If the license server has the licenses for the Citrix product being requested and has available user licenses, a license is checked out.

• XenApp (2008)
• Presentation Server (2005)
• MetaFrame XP Presentation Server (2003)
• MetaFrame XP (2001)
• MetaFrame (1998)
• MultiWin (1997)
• WinFrame (1995)
• WinView (1993)
• Citrix Multi-User (1991)
• Citrix MULTIUSER OS/2 (1990)

Citrix, the company, was founded in 1989 and I started working with MULTIUSER OS/2 in late 1989 or early 1990.  There were still vertical market application vendors using that product as late as the summer of 2003.  Citrix has primarily been known for their Application Virtualization product Citrix Virtual Apps but there are 15 distinct product families listed on the Citrix.com web page:

• Citrix Workspace
• Citrix Virtual Apps and Desktops
• Citrix Content Collaboration
• Citrix Endpoint Management
• Citrix Managed Desktops
• Citrix Hypervisor
• ShareFile
• Citrix ADC
• Citrix Application Delivery Management
• Citrix Gateway
• Citrix Intelligent Traffic Management
• Citrix SD-WAN
• Citrix Web App Firewall
• Citrix Analytics for Security
• Citrix Analytics for Performance

What is Citrix?  Citrix is a company that offers a wide range of products to serve almost any application delivery needs a business may have.  From the smallest business to the largest global spanning corporations, Citrix has products to help deliver your applications to your users in the most cost-efficient manner possible.