The script will not work for sending emails if you are using PowerShell version 2 so the first line in the script is now:

#Requires -Version 3

The two new parameters are SmtpPort and UseSSL. SmtpPort sets the SMTP port and UseSSL tells whether to use SSL for making the connection to the SmtpServer.

In order to send authenticated SMTP emails, a username and password are required.

$emailCredentials = Get-Credential -Message "Enter the email account and password to send emails"

The credentials are the same used when configuring an email client.  i.e. SomeUser@emaildomain.com and the account’s password. I tested this using my Office365 account and it worked with no issues.

The email body is read in from a file.  I use the -BodyAsHtml parameter for Send-MailMessage.  To get line breaks just use <br /> at the end of each line and for spacing lines.  The file I used for my testing looks like this:

<br />
<br />
Your Personal vDisk space has reached over 90% of its capacity.   <br />
You should resolve this as soon as possible before your Personal <br />
vDisk fills up and needs to be reset.  When that happens, you <br />
will need to reinstall your applications.<br />
<br />
You should move your 'User Data' from your C and or PvD drive <br />
and it should be kept on your home drive.  The free space on your <br />
workstation is to be used for application installs, temp files, <br />
and other general system and application configurations.<br />
<br />
Let us know if you need any help.<br />
<br />
Thanks<br />
<br />
<br />
The XenDesktop Help Desk Team at CarlWebster.com<br />

Which looks like this in Outlook 2010.

Example of running the script:

.\get-pvdstatsexcel.ps1 -AdminAddress xd71studio1 -XDVersion 7 -SmtpServer smtp.office365.com -SmtpPort 587 -UseSSL -From Webster@CarlWebster.com -InputFile c:\webster\emailbody.txt -verbose

Example screen output:

PS C:\webster> .\get-pvdstatsexcel.ps1 -AdminAddress xd71studio1 -XDVersion 7 -SmtpServer smtp.office365.com -SmtpPort 5
87 -UseSSL -From Webster@CarlWebster.com -InputFile c:\webster\emailbody.txt -verbose
VERBOSE: 02/01/2014 09:45:00: Retrieving all XenDesktop Catalog names
VERBOSE: 02/01/2014 09:45:00:
VERBOSE: 02/01/2014 09:45:00:
VERBOSE: 02/01/2014 09:45:00: Using Controller   : xd71studio1
VERBOSE: 02/01/2014 09:45:00: XenDesktop version : 7
VERBOSE: 02/01/2014 09:45:00: Smtp Server        : smtp.office365.com
VERBOSE: 02/01/2014 09:45:00: Smtp Port          : 587
VERBOSE: 02/01/2014 09:45:00: Use SSL            : True
VERBOSE: 02/01/2014 09:45:00: From               : Webster@CarlWebster.com
VERBOSE: 02/01/2014 09:45:00: Input File         : c:\webster\emailbody.txt
VERBOSE: 02/01/2014 09:45:00: PoSH version       : 3.0
VERBOSE: 02/01/2014 09:45:00:
VERBOSE: 02/01/2014 09:45:00: Script start       : 02/01/2014 09:45:00
VERBOSE: 02/01/2014 09:45:00:
VERBOSE: 02/01/2014 09:45:00:
VERBOSE: 02/01/2014 09:45:00: Get VMs for Catalog Win7 WC PvD Test
VERBOSE: 02/01/2014 09:45:00:  Processing VM Win7-PvD-01
VERBOSE: 02/01/2014 09:45:01:  Processing VM Win7-PvD-02
VERBOSE: 02/01/2014 09:45:01:  Processing VM Win7-PvD-03
VERBOSE: 02/01/2014 09:45:01: Creating CSV file C:\webster\Win7 WC PvD Test_PvD_Stats.csv
VERBOSE: Performing operation "Export-Csv" on Target "C:\webster\Win7 WC PvD Test_PvD_Stats.csv".
VERBOSE: 02/01/2014 09:45:01: Creating Summary CSV file C:\webster\Summary_PvD_Stats.csv
VERBOSE: Performing operation "Export-Csv" on Target "C:\webster\Summary_PvD_Stats.csv".
VERBOSE: 02/01/2014 09:45:01: Sending emails
VERBOSE: 02/01/2014 09:45:14:  Sending email to webster@carlwebster.com
VERBOSE: 02/01/2014 09:45:19: CSV Processing complete
VERBOSE: 02/01/2014 09:45:19: Start creating Excel file and worksheets
VERBOSE: 02/01/2014 09:45:19: Setup Excel
VERBOSE: The object written to the pipeline is an instance of the type
"Microsoft.Office.Interop.Excel.ApplicationClass" from the component's primary interop assembly. If this type exposes
different members than the IDispatch members, scripts written to work with this object might not work if the primary
interop assembly is not installed.
VERBOSE: 02/01/2014 09:45:19: Get Summary CSV file
VERBOSE: 02/01/2014 09:45:21:  Adding summary row for Win7-PvD-02
VERBOSE: 02/01/2014 09:45:22: Deleting C:\webster\Summary_PvD_Stats.csv
VERBOSE: Performing operation "Remove file" on Target "C:\webster\Summary_PvD_Stats.csv".
VERBOSE: 02/01/2014 09:45:22: Summary sheet completed
VERBOSE: 02/01/2014 09:45:22: Start processing catalogs
VERBOSE: 02/01/2014 09:45:23: Get CSV file for Catalog Win7 WC PvD Test
VERBOSE: 02/01/2014 09:45:24:  Adding row for Win7-PvD-01
VERBOSE: 02/01/2014 09:45:25:  Adding row for Win7-PvD-02
VERBOSE: 02/01/2014 09:45:25:  Adding row for Win7-PvD-03
VERBOSE: 02/01/2014 09:45:26: Deleting C:\webster\Win7 WC PvD Test_PvD_Stats.csv
VERBOSE: Performing operation "Remove file" on Target "C:\webster\Win7 WC PvD Test_PvD_Stats.csv".
VERBOSE: 02/01/2014 09:45:26: Processing worksheets is complete
VERBOSE: 02/01/2014 09:45:26: Saving Excel file
VERBOSE: Performing operation "Remove variable" on Target "Name: Excel".
VERBOSE: 02/01/2014 09:45:26: Excel file C:\webster\PvDStats_2014-02-01.xlsx is ready for use
VERBOSE: Performing operation "Stop-Process" on Target "EXCEL (3324)".
VERBOSE: 02/01/2014 09:45:26: Script started: 02/01/2014 09:45:00
VERBOSE: 02/01/2014 09:45:26: Script ended: 02/01/2014 09:45:26
VERBOSE: 02/01/2014 09:45:26: Elapsed time: 0 days, 0 hours, 0 minutes, 26.5 seconds
PS C:\webster>

What happens if you are supposed to use SSL and you don’t?

VERBOSE: 02/01/2014 09:47:43: Sending emails
VERBOSE: 02/01/2014 09:47:52:  Sending email to webster@carlwebster.com
Send-MailMessage : The SMTP server requires a secure connection or the client was not authenticated. The server
response was: 5.7.1 Client was not authenticated
At C:\webster\Get-PvDStatsExcel.ps1:746 char:6
+                     Send-MailMessage -To $emailTo -Subject $emailSubject -Body $emailBody -Smtp ...
+    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ CategoryInfo          : InvalidOperation: (System.Net.Mail.SmtpClient:SmtpClient) [Send-MailMessage], SmtpExcept
ion
+ FullyQualifiedErrorId : SmtpException,Microsoft.PowerShell.Commands.SendMailMessage

The rest of the script will continue to run and the Excel file is created and saved.  Only the emails will not be sent.

I believe I have included lots of great help text.

PS C:\webster> get-help .\get-pvdstatsexcel.ps1 -full
NAME
    C:\webster\Get-PvDStatsExcel.ps1

SYNOPSIS
    Creates an Excel spreadsheet containing Citrix XenDesktop Personal vDisk (PvD) usage statistics.

SYNTAX
    C:\webster\Get-PvDStatsExcel.ps1 [[-XDCatalogName] <String>] [[-AdminAddress] <String>] [[-XDVersion] <Int32>] [<CommonParameters>]

    C:\webster\Get-PvDStatsExcel.ps1 [[-XDCatalogName] <String>] [[-AdminAddress] <String>] [[-XDVersion] <Int32>] [-SmtpServer] <String> [[-SmtpPort] <Int32>] [[-UseSSL]] [-From] <String> [-InputFile] <String> [<CommonParameters>]

DESCRIPTION
    Take a XenDesktop Catalog name (or all Catalogs) and gathers PvD usage stats.
    Creates a Summary worksheet with users who have any PvD with > 90% usage.
    Summary worksheet has the user's Active Directory name and email address.

PARAMETERS
    -XDCatalogName <String>
        XenDesktop Catalog name.  If not entered, process all Catalogs.

        Required?                    false
        Position?                    1
        Default value
        Accept pipeline input?       false
        Accept wildcard characters?  false

    -AdminAddress <String>
        Specifies the address of a XenDesktop controller that the PowerShell script will connect to.  This can be provided as a host name or an IP address.

        Required?                    false
        Position?                    2
        Default value
        Accept pipeline input?       false
        Accept wildcard characters?  false

    -XDVersion <Int32>
        Specifies the XenDesktop version.
        5 is for all versions of XenDesktop 5.
        7 is for all versions of XenDesktop 7.
        Default is XenDesktop 7.

        Required?                    false
        Position?                    3
        Default value                7
        Accept pipeline input?       false
        Accept wildcard characters?  false

    -SmtpServer <String>
        Specifies the optional email server to send emails to users on the Summary worksheet.

        Required?                    true
        Position?                    4
        Default value
        Accept pipeline input?       false
        Accept wildcard characters?  false

    -SmtpPort <Int32>
        Specifies the SMTP port.

        Required?                    false
        Position?                    5
        Default value                25
        Accept pipeline input?       false
        Accept wildcard characters?  false

    -UseSSL [<SwitchParameter>]
        Specifies whether to use SSL for the SmtpServer.
        Default is False.

        Required?                    false
        Position?                    6
        Default value                False
        Accept pipeline input?       false
        Accept wildcard characters?  false

    -From <String>
        Specifies the username for the From email address.
        If SmtpServer is used, this is a required parameter.

        Required?                    true
        Position?                    7
        Default value
        Accept pipeline input?       false
        Accept wildcard characters?  false

    -InputFile <String>
        The file that contains the text for the body of the email.
        If SmtpServer is used, this is a required parameter.
        Text is treated as HTML.

        Required?                    true
        Position?                    8
        Default value
        Accept pipeline input?       false
        Accept wildcard characters?  false

    <CommonParameters>
        This cmdlet supports the common parameters: Verbose, Debug,
        ErrorAction, ErrorVariable, WarningAction, WarningVariable,
        OutBuffer and OutVariable. For more information, see
        about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216).

    INPUTS
        None.  You cannot pipe objects to this script.

    OUTPUTS
        Creates a Microsoft Excel spreadsheet.
        This has only been tested with Microsoft Excel 2010.
        Optional, creates and sends an email for every user on the Summary Worksheet.

    NOTES

        NAME: Get-PvDStatsExcel.ps1
        VERSION: 2.1
        AUTHOR: Carl Webster with help, as usual, from Michael B. Smith
        LASTEDIT: February 1, 2014

    -------------------------- EXAMPLE 1 --------------------------
    PS C:\PSScript >.\Get-PvDStatsExcel.ps1

    Will process all XenDesktop Catalogs.
    AdminAddress is the computer running the script for the AdminAddress.
    Will load Citrix SnapIn for XenDesktop 7.

    -------------------------- EXAMPLE 2 --------------------------
    PS C:\PSScript >.\Get-PvDStatsExcel.ps1 -XDVersion 5

    Will process all XenDesktop Catalogs.
    AdminAddress is the computer running the script for the AdminAddress.
    Will load Citrix SnapIn for XenDesktop 5.

    -------------------------- EXAMPLE 3 --------------------------
    C:\PS>PS C:\PSScript .\Get-PvDStatsExcel.ps1 -XDCatalogName Win7Image1 -AdminAddress DDC01

    Will gather PvD usage stats for the Win7Image1 Catalog
    using a Controller named DDC01 for the AdminAddress.
    Will load Citrix SnapIn for XenDesktop 7.

    -------------------------- EXAMPLE 4 --------------------------
    PS C:\PSScript >.\Get-PvDStatsExcel.ps1 -SmtpServer mail.domain.tld -From XDAdmin@domain.tld -InputFile C:\Scripts\EmailBodyText.txt

    Will process all XenDesktop Catalogs.
    AdminAddress is the computer running the script for the AdminAddress.
    Will load Citrix SnapIn for XenDesktop 7.
    Uses mail.domain.tld as the email server.
    Uses the default SMTP port 25.
    Will not use SSL.
    Uses XDAdmin@domain.tld for the email's Sent From address.
    Reads the contents of C:\Scripts\EmailBodyText.txt and uses the contents as the email body.

    -------------------------- EXAMPLE 5 --------------------------
    PS C:\PSScript >.\Get-PvDStatsExcel.ps1 -SmtpServer smtp.office365.com -SmtpPort 587 -UseSSL -From Webster@CarlWebster.com -InputFile C:\Scripts\EmailBodyText.txt

    Will process all XenDesktop Catalogs.
    AdminAddress is the computer running the script for the AdminAddress.
    Will load Citrix SnapIn for XenDesktop 7.
    Uses smtp.office365.com.
    User SMTP port 587.
    Uses Webster@CarlWebster.com for the email's Sent From address (this must be a valid address on the email system).
    Reads the contents of C:\Scripts\EmailBodyText.txt and uses the contents as the email body.

    -------------------------- EXAMPLE 6 --------------------------
    C:\PS>Sample input file.

    <br />
    <br />
    Your Personal vDisk space has reached over 90% of its capacity.   <br />
    You should resolve this as soon as possible before your Personal <br />
    vDisk fills up and needs to be reset.  When that happens, you <br />
    will need to reinstall your applications.<br />
    <br />
    You should move your 'User Data' from your C and or PvD drive <br />
    and it should be kept on your home drive.  The free space on your <br />
    workstation is to be used for application installs, temp files, <br />
    and other general system and application configurations.<br />
    <br />
    Let us know if you need any help.<br />
    <br />
    Thanks<br />
    <br />
    <br />
    The XenDesktop Help Desk Team at CarlWebster.com<br />

RELATED LINKS

PS C:\webster>

I hope you find the changes useful.

If you find any issues, please let me know and I will do my best to get them fixed.

You can always find the most current script by going to https://www.carlwebster.com/where-to-get-copies-of-the-documentation-scripts/

Thanks

Webster

The Provisioning Services 7.0 PowerShell Programmer Guide is available here.

On page 7, the instructions to install the PowerShell Snap-in are not correct for Windows 8 or Server 2012.

The original instructions work for Server 2003, Server 2008, Server 2008 R2, Windows XP, and Windows 7.

Installation of PowerShell Snap-In

The PowerShell snap-in (McliPSSnapIn.dll) can be installed using the Provisioning Server Console install.

If it later needs to be registered in PowerShell, this can be manually done by running one of the following commands at the DOS command prompt:

For 32-bit

%systemroot%\Microsoft.NET\Framework\v2.0.50727\installutil.exe McliPSSnapIn.dll

For 64-bit

%systemroot%\Microsoft.NET\Framework64\v2.0.50727\installutil.exe McliPSSnapIn.dll

The correct instructions for Windows 8 and Server 2012 are:

For 32-bit

%systemroot%\Microsoft.NET\Framework\v4.0.30319\installutil.exe McliPSSnapIn.dll

For 64-bit

%systemroot%\Microsoft.NET\Framework64\v4.0.30319\installutil.exe McliPSSnapIn.dll

If you attempt to run the original command, you get:

That is because there is nothing in the v2.0.50727 folder.

The InstallUtil.exe utility is in the v4.0.30319 folder.

I am testing with 32-bit Windows 8, so I needed to run:

%systemroot%\Microsoft.NET\Framework\v4.0.30319\installutil.exe McliPSSnapIn.dll

Now I can configure a remote connection to my PVS7 server and run an MCLI PowerShell command.

I hope Citrix will correct the PVS7 PowerShell Programmer Guide.

Thanks

Webster

1. From the computer to run the script, start a PowerShell session as Administrator
2. Add-PSSnapin McliPSSnapin
3. Mcli-Run SetupConnection -p Server=PVSServerName
4. .\PVS_Inventory_V2.ps1 -verbose

The results of my session on my Windows 7 VM against my Windows Server 2008 R2 PVS 6.1 server VM:

PS C:\webster> $env:computername
WIN7
PS C:\webster> Add-PSSnapin McliPSSnapin
PS C:\webster> Mcli-Run SetupConnection -p Server=PVS61
Run succeeded.
PS C:\webster> .\PVS_Inventory_V2.ps1 -verbose
VERBOSE: checking for McliPSSnapin
VERBOSE: Getting PVS version info
VERBOSE: Build PVS farm values
VERBOSE: Setting up Word
VERBOSE: Create Word comObject. If you are not running Word 2007, ignore the next message.
VERBOSE: The object written to the pipeline is an instance of the type "Microsoft.Office.Interop.Word.ApplicationClass"
from the component's primary interop assembly. If this type exposes different members than the IDispatch members,
scripts written to work with this object might not work if the primary interop assembly is not installed.
VERBOSE: Running Microsoft Word 2010
VERBOSE: Validate company name
VERBOSE: Validate cover page
VERBOSE: Company Name: Webster's Lab
VERBOSE: Cover Page : Motion
VERBOSE: User Name : administrator
VERBOSE: Farm Name : PVS61Farm
VERBOSE: Title : Inventory Report for the PVS61Farm Farm
VERBOSE: Filename : C:\webster\PVS61Farm.docx
VERBOSE: Load Word Templates
VERBOSE: Create empty word doc
VERBOSE: disable spell checking
VERBOSE: insert new page, getting ready for table of contents
VERBOSE: table of contents
VERBOSE: set the footer
VERBOSE: get the footer and format font
VERBOSE: Footer text
VERBOSE: add page numbering
VERBOSE: return focus to main document
VERBOSE: move to the end of the current document
VERBOSE: Processing PVS Farm Information
VERBOSE: Processing Security Tab
VERBOSE: Processing Groups Tab
VERBOSE: Processing Licensing Tab
VERBOSE: Processing Options Tab
VERBOSE: Processing vDisk Version Tab
VERBOSE: Processing Status Tab
VERBOSE: Processing Sites
VERBOSE: Processing Site PVS61Site
VERBOSE: Processing Security Tab
VERBOSE: Processing Options Tab
VERBOSE: Processing vDisk Update Tab
VERBOSE: Processing Servers in Site PVS61Site
VERBOSE: Processing Server PVS61
VERBOSE: Processing General Tab
VERBOSE: Processing Network Tab
VERBOSE: Processing Stores Tab
VERBOSE: Processing Stores for server
VERBOSE: Processing Store Store
VERBOSE: Processing Options Tab
VERBOSE: Processing Logging Tab
VERBOSE: Processing Server Tab on Advanced button
VERBOSE: Processing Network Tab on Advanced button
VERBOSE: Processing Pacing Tab on Advanced button
VERBOSE: Processing Device Tab on Advanced button
VERBOSE: Processing Bootstrap files
VERBOSE: Processing Bootstrap files for Server PVS61
VERBOSE: Processing General Tab
VERBOSE: Processing Options Tab
VERBOSE: Processing all vDisks in site
VERBOSE: Processing vDisk Update Management
VERBOSE: Processing all device collections in site
VERBOSE: Processing Collection PVS61Collection
VERBOSE: Processing General Tab
VERBOSE: Processing Security Tab
VERBOSE: Processing Auto-Add Tab
VERBOSE: Processing each collection process for each device
VERBOSE: Processing all site views in site
VERBOSE: Processing all PVS Farm Views
VERBOSE: Processing Stores
VERBOSE: Processing Store Store
VERBOSE: Processing General Tab
VERBOSE: Processing Servers Tab
VERBOSE: Processing Server PVS61
VERBOSE: Processing Paths Tab
VERBOSE: Finishing up Word document
VERBOSE: Set Cover Page Properties
VERBOSE: Update the Table of Contents
VERBOSE: Save and Close document and Shutdown Word
PS C:\webster>

That is it, that is all there is to it.

Hope this help.

Webster

NOTE: This script is continually updated.  You can always find the most current version by going to https://www.carlwebster.com/where-to-get-copies-of-the-documentation-scripts/

As much as Microsoft pushes PowerShell for their products and on their users, I find it surprising there is no native PowerShell support for any of the Office products.  For example there is no New_WordDocument, Get-WordDocument or Save-WordDocument.  In order to use Word with PowerShell you must use the Word COM Object model.  Finding detailed information on that subject was not easy.  Fortunately for me, Jeff Hicks had blogged about a presentation he did in 2012 where he linked to some sample PowerShell script files.  One of his sample files gave me the start I needed.

The prerequisites to follow along with this article are:

• A server, physical or virtual, running Microsoft Windows Server 2008 R2 with or without SP1
• Citrix XenApp 6 installed with or without HRP01 or HRP02
• Word 2007, 2010 or 2013 installed on the computer running the script

I tested the script with Hotfix Rollup Pack 02.

Note: The parts of this script that deal with creating the Word document are derived 100% from the XenApp 6.5 script.  To read the details of the changes to the script that deal with Microsoft Word, please read Documenting a Citrix XenApp 6.5 Farm with Microsoft PowerShell and Word – Version 3.  Several of the bug fixes and issues resolved for Version 3.1 of the XenApp 6.5 script are included in this script.  These include:

• Several typos were fixed to get rid of my southern drawl.  No more “gettin”, “settin” or “runnin”.
• More Write-Verbose statements were added.
• Fixed all the issues reported by running the script with Set-StrictMode –Version 2.0 set.
• For some users, when Microsoft Word is installed, the HKCU:\Software\Microsoft\Office\Common\UserInfo\CompanyName registry key is set and for some, it is not set. For those users, the HKCU:\Software\Microsoft\Office\Common\UserInfo\Company registry key is set. The script will now check both locations.
• Some companies do not install the Microsoft Word Templates. This cause the Cover Page and Table of Contents sections of the script to generate numerous errors. The script now checks to see if the appropriate Word Template file is loaded successfully. If not, then the Cover Page and Table of Contents are skipped. The rest of the report is generated.
• Pat Coughlin showed me how to disable Spell Check and Grammar Check while the document is created. For large XenApp 6 Farms, this can substantially speed up the document creation. For those large farms that can generate 1000+ page documents, Word would crash trying to keep track of all the spelling and grammar errors.
• In the Load Evaluator section, the Load Throttling and Server User load settings were added.
• A user on StackOverflow.com showed me how to indent the Table used for the Citrix Services.
• Now that I know how to indent the Word Tables, I added Tables for the Citrix Installed Hotfixes and the Microsoft Hotfixes.
• The Table for the Microsoft Hotfixes now lists all the Citrix recommended Microsoft hotfixes and whether the hotfix is Installed or Not Installed.
• Before getting information on the Citrix Services and hotfixes, the server is tested to make sure it is reachable.
• I received a question as to whether Microsoft Word needed to be installed to create the Word document. The script now verifies that Word is installed. If not, a warning is given and the script exits.
• I received reports of the script “crashing” if Word was running before the script was run. The script will now check to see if Word is running and if it is, the script will exit. If the script is run from a XenApp server, the script gets the Session ID of the user running the script. Then the script checks if the WinWord process is running in that session. If it is, a warning is given and the script exits.
• Session printers with modified settings are now fully detailed

In trying to find resources to figure out how to use PowerShell to create a complex Word document, I found Jeff Hick’s blog post and sample scripts.

http://jdhitsolutions.com/blog/2012/05/san-diego-2012-powershell-deep-dive-slides-and-demos/

Jeff had a ZIP file with several sample PowerShell scripts.  One of them, Demo-WordReport.ps1, was extremely helpful.

There are three pieces of information the script needs for the Cover Page and Footer:

1. Company Name
2. Cover Page
3. User Name

Since a digitally signed version of the script is provided, these three pieces of information need to be passed to the script as parameters.  A signed PowerShell script cannot be modified or the script is rendered useless.

These parameters give us $CompanyName, $CoverPage and $UserName.  Each has an alias: CN for CompanyName, CP for CoverPage and UN for UserName.

The default for $CompanyName is read from the registry key where Microsoft Office stores user information.  For some users, when Microsoft Word is installed, the HKCU:\Software\Microsoft\Office\Common\UserInfo\CompanyName registry key is set and for some, it is not set.  For those users, the HKCU:\Software\Microsoft\Office\Common\UserInfo\Company registry key is set.  The script checks both locations.

The default for $CoverPage is Motion.  Motion is a Word Cover Page that comes with both versions of Word, looks good but will require a minor tweak of changing the font used by the date field to a smaller font size.  Some companies do not install the Microsoft Word Templates.  The script checks to see if the appropriate Word Template file is loaded successfully.  If not, then the Cover Page and Table of Contents are skipped.  The rest of the report is generated.

The default for $UserName is taken from the USERNAME environment variable.

The parameter names can be spelled out or the aliases can be used or any combination.  All three of these examples are valid:

-CompanyName “XYC, Inc.” –CoverPage “Grid” –UserName “Joe User”

-CN “XYC, Inc.” –CP “Grid” –UN “Joe User”

-CoverPage “Grid” –UN “Joe User”

For the third example, the default Company Name will be used.

For the Word document to be saved a file name is needed and for the Cover Page, a title is needed.

The filename for the document is the XenApp farm name with the extension DOCX.  The document is stored in the folder where the script is run.

Each version of Word comes with Cover Pages and only two are shared across both versions.  The version of Word installed on the computer running the script needs to be determined.  If a wrong cover page is passed as $CoverPage and that Cover Page is not in the installed version of Word, the script will run but a lot of errors will be returned.  The script validates the $CoverPage against the valid Cover Pages specific to each version of Word.

If an invalid Cover Page is used, the script gives an error, closes Word and exits.

In Version 1 of this script, in order to write out a line of output, my friend Michael B. Smith wrote a Line function.  That function is no longer needed.  Ryan took Michael’s function and modified it to write a line to Word.

The next changes in Version 3 come in the Servers section.  I added Word Tables to hold information on the Citrix services and installed Citrix hotfixes.  I know I can get more data on the services by using WMI Queries but in a large farm with XenApp servers spread geographically; those queries can cause excessive network traffic.  I am using the Get-Service cmdlet because it is native.

Since this script has parameters, I created help text for the script.  Running the following command from the PowerShell prompt will display the full help text.

Get-Help .\XA6_Inventory_v3.ps1 -full

You can also use –online to get taken to this article.

Get-Help .\XA6_Inventory_V3.ps1 -online

Running the script with –verbose, gives information of the script’s running.

.\xa6_inventory_v3.ps1 -CompanyName "The Accidental Citrix Admin" -CoverPage "Facet" -UserName "Amalgamated Consulting Group" -verbose

Sample output.

PS C:\webster> .\xa6_inventory_v3.ps1 -CompanyName "The Accidental Citrix Admin" -CoverPage "Facet" -UserName "Amalgamated Consulting Group" -verbose
VERBOSE: Getting Farm data
VERBOSE: Setting up Word
VERBOSE: Create Word comObject.  If you are not running Word 2007, ignore the next message.
VERBOSE: The object written to the pipeline is an instance of the type "Microsoft.Office.Interop.Word.ApplicationClass"
 from the component's primary interop assembly. If this type exposes different members than the IDispatch members,
scripts written to work with this object might not work if the primary interop assembly is not installed.
VERBOSE: Running Microsoft Word 2013
VERBOSE: Validate company name
VERBOSE: Validate cover page
VERBOSE: Company Name: The Accidental Citrix Admin
VERBOSE: Cover Page  : Facet
VERBOSE: User Name   : Amalgamated Consulting Group
VERBOSE: Farm Name   : NewFarm
VERBOSE: Title       : Inventory Report for the NewFarm Farm
VERBOSE: Filename    : C:\webster\NewFarm.docx
VERBOSE: Load Word Templates
VERBOSE: Create empty word doc
VERBOSE: disable spell checking
VERBOSE: insert new page, getting ready for table of contents
VERBOSE: table of contents
VERBOSE: set the footer
VERBOSE: get the footer and format font
VERBOSE: Footer text
VERBOSE: add page numbering
VERBOSE: return focus to main document
VERBOSE: move to the end of the current document
VERBOSE: Processing Administrators
VERBOSE: Processing Applications
WARNING: Application information could not be retrieved
VERBOSE: Processing Configuration Logging/History Report
VERBOSE: Processing Load Balancing Policies
WARNING: Load balancing policy information could not be retrieved
VERBOSE: Processing Load Evaluators
VERBOSE: Processing Servers
VERBOSE: Testing to see if XA60 is online and reachable
VERBOSE: XA60 is online.  Citrix Services and Hotfix areas processed.
VERBOSE: Processing Citrix services for server XA60
VERBOSE: Create Word Table for Citrix services
VERBOSE: add Citrix services table to doc
VERBOSE: format first row with column headings
VERBOSE: Move table of Citrix services to the right
VERBOSE: return focus back to document
VERBOSE: move to the end of the current document
VERBOSE: Get list of Citrix hotfixes installed
VERBOSE: Processing server XA60
VERBOSE: number of hotfixes is 1
VERBOSE: Create Word Table for Citrix Hotfixes
VERBOSE: add Citrix installed hotfix table to doc
VERBOSE: format first row with column headings
VERBOSE: Move table of Citrix installed hotfixes to the right
VERBOSE: return focus back to document
VERBOSE: move to the end of the current document
VERBOSE: compare Citrix hotfixes to recommended Citrix hotfixes from CTX129229
VERBOSE: Processing Microsoft hotfixes for server XA60
VERBOSE: Create Word Table for Microsoft Hotfixes
VERBOSE: add Microsoft hotfix table to doc
VERBOSE: format first row with column headings
VERBOSE: Move table of Microsoft hotfixes to the right
VERBOSE: return focus back to document
VERBOSE: move to the end of the current document
VERBOSE: Processing Worker Groups
VERBOSE: Processing Zones
VERBOSE: Processing Citrix IMA Policies
VERBOSE: Finishing up Word document
VERBOSE: Set Cover Page Properties
VERBOSE: Update the Table of Contents
VERBOSE: Save and Close document and Shutdown Word
PS C:\webster>

How to use this script?

I saved the script as XA6_Inventory_V3.ps1 in the C:\PSScripts folder.  From the PowerShell prompt, change to the C:\PSScripts folder, or the folder where you saved the script.  From the PowerShell prompt, type in:

.\XA6_Inventory_V3.ps1 and press Enter.

A word about Word

1. Word must be installed
2. After installation, Word should be opened, at least once, before you run the script
3. It is better to do File, Options, OK before running the script

The script does very strange things if the last two items are not done.  All kinds of errors are generated by the script if Word has not been opened at least once.  The second time the script is run (without Word haven been opened), fewer errors are generated.  The third time the script is run, it runs without errors.

I am assuming there are registry keys and values that need to be set for the Word comObject to operate properly.

Bottom Line: If you just installed Word, open Word and close Word before running the script.

If you have any suggestions for the script, please let me know.  Send an e-mail to webster@carlwebster.com.

NOTE: This script is continually updated.  You can always find the most current version by going to https://www.carlwebster.com/where-to-get-copies-of-the-documentation-scripts/

Copies of all the Cover Pages can be found here:

Word 2007

Word 2010

Word 2013

NOTE: This script is continually updated.  You can always find the most current version by going to https://www.carlwebster.com/where-to-get-copies-of-the-documentation-scripts/

As much as Microsoft pushes PowerShell for their products and on their users, I find it surprising there is no native PowerShell support for any of the Office products.  For example there is no New_WordDocument, Get-WordDocument or Save-WordDocument.  In order to use Word with PowerShell you must use the Word COM Object model.  Finding detailed information on that subject was not easy.  Fortunately for me, Jeff Hicks had blogged about a presentation he did in 2012 where he linked to some sample PowerShell script files.  One of his sample files gave me the start I needed.

The prerequisites to follow along with this article are:

• Word 2007, 2010 or 2013 installed on the computer running the script
• PVS 5.6, PVS 6.0 or PVS 6.1
• PVS Console PowerShell snap-in registered

Note: The parts of this script that deal with creating the Word document are derived 100% from the XenApp 6.5 script.  To read the details of the changes to the script that deal with Microsoft Word, please read Documenting a Citrix XenApp 6.5 Farm with Microsoft PowerShell and Word – Version 3.  Several of the bug fixes and issues resolved for Version 3.1 of the XenApp 6.5 script are included in this script.  These include:

• Several typos were fixed to get rid of my southern drawl. No more “gettin”, “settin” or “runnin”.
• Write-Verbose statements were added.
• Fixed all the issues reported by running the script with Set-StrictMode –Version 2.0 set.
• For some users, when Microsoft Word is installed, the HKCU:\Software\Microsoft\Office\Common\UserInfo\CompanyName registry key is set and for some, it is not set. For those users, the HKCU:\Software\Microsoft\Office\Common\UserInfo\Company registry key is set. The script will now check both locations.
• Some companies do not install the Microsoft Word Templates. This cause the Cover Page and Table of Contents sections of the script to generate numerous errors. The script now checks to see if the appropriate Word Template file is loaded successfully. If not, then the Cover Page and Table of Contents are skipped. The rest of the report is generated.
• Pat Coughlin showed me how to disable Spell Check and Grammar Check while the document is created. For large PVS Farms, this can substantially speed up the document creation. For those large farms that can generate 1000+ page documents, Word would crash trying to keep track of all the spelling and grammar errors.
• I received a question as to whether Microsoft Word needed to be installed to create the Word document. The script now verifies that Word is installed. If not, a warning is given and the script exits.
• I received reports of the script “crashing” if Word was running before the script was run. The script will now check to see if Word is running and if it is, the script will exit. If the script is run from a XenApp server, the script gets the Session ID of the user running the script. Then the script checks if the WinWord process is running in that session. If it is, a warning is given and the script exits.

In trying to find resources to figure out how to use PowerShell to create a complex Word document, I found Jeff Hick’s blog post and sample scripts.

http://jdhitsolutions.com/blog/2012/05/san-diego-2012-powershell-deep-dive-slides-and-demos/

Jeff had a ZIP file with several sample PowerShell scripts.  One of them, Demo-WordReport.ps1, was extremely helpful.

Pat Coughlin showed me how to disable Spell Check and Grammar Check while the document is created.  For large PVS Farms, this can substantially speed up the document creation.  For those large farms that can generate 1000+ page documents, Word would crash trying to keep track of all the spelling and grammar errors.

There are three pieces of information the script needs for the Cover Page and Footer:

1. Company Name
2. Cover Page
3. User Name

Since a digitally signed version of the script is provided, these three pieces of information need to be passed to the script as parameters.  A signed PowerShell script cannot be modified or the script is rendered useless.

These parameters give us $CompanyName, $CoverPage and $UserName.  Each has an alias: CN for CompanyName, CP for CoverPage and UN for UserName.

The default for $CompanyName is read from the registry key where Microsoft Office stores user information.  For some users, when Microsoft Word is installed, the HKCU:\Software\Microsoft\Office\Common\UserInfo\CompanyName registry key is set and for some, it is not set.  For those users, the HKCU:\Software\Microsoft\Office\Common\UserInfo\Company registry key is set.  The script checks both locations.

The default for $CoverPage is Motion.  Motion is a Word Cover Page that comes with all versions of Word, looks good but will require a minor tweak of changing the font used by the date field to a smaller font size.  Some companies do not install the Microsoft Word Templates.  The script checks to see if the appropriate Word Template file is loaded successfully.  If not, then the Cover Page and Table of Contents are skipped.  The rest of the report is generated.

The default for $UserName is taken from the USERNAME environment variable.

The parameter names can be spelled out or the aliases can be used or any combination.  All three of these examples are valid:

-CompanyName “XYC, Inc.” –CoverPage “Grid” –UserName “Joe User”

-CN “XYC, Inc.” –CP “Grid” –UN “Joe User”

-CoverPage “Grid” –UN “Joe User”

For the third example, the default Company Name will be used.

For the Word document to be saved a file name is needed and for the Cover Page, a title is needed.

The filename for the document is the PVS farm name with the extension DOCX.  The document is stored in the folder where the script is run.

Each version of Word comes with Cover Pages and only two are shared across all versions.  The version of Word installed on the computer running the script needs to be determined.  If a wrong cover page is passed as $CoverPage and that Cover Page is not in the installed version of Word, the script will run but a lot of errors will be returned.  The script validates the $CoverPage against the valid Cover Pages specific to each version of Word.

If an invalid Cover Page is used, the script gives an error, closes Word and exits.

In Version 1 of this script, in order to write out a line of output, my friend Michael B. Smith wrote a Line function.  That function is no longer needed.  Ryan took Michael’s function and modified it to write a line to Word.

In updating this script, I fixed several bugs and logic issues.  For example, the time of “12:00 AM” for various update schedules was incorrectly printed as “012:00 PM”.  An example of a logic fix is For PVS 6.x vDisk Update Management.  I was only processing the Virtualization Hosts and vDisks only if at least one Task had been defined.  The Virtualization Hosts and vDisks are now processed independently of the Tasks.

Since this script has parameters, I created help text for the script.  Running the following command from the PowerShell prompt will display the full help text.

Get-Help .\PVS_Inventory_v2.ps1 -full

You can also use –online to get taken to this article.

Get-Help .\PVS_Inventory_V2.ps1 -online

Running the script with –verbose, gives information of the script’s running.

.\PVS_inventory_v2.ps1 -CompanyName "The Accidental Citrix Admin" -CoverPage "Motion" -UserName "Amalgamated Consulting Group" -verbose

Sample output.

PS C:\webster> .\pvs_inventory_v2.ps1 -CompanyName "The Accidental Citrix Admin" -CoverPage "Contrast" -UserName "Amalgamated Consulting Group" -verbose
VERBOSE: checking for McliPSSnapin
VERBOSE: Getting PVS version info
VERBOSE: Build PVS farm values
VERBOSE: Setting up Word
VERBOSE: Create Word comObject.  If you are not running Word 2007, ignore the next message.
VERBOSE: The object written to the pipeline is an instance of the type “Microsoft.Office.Interop.Word.ApplicationClass"  from the component's primary interop assembly. If this type exposes different members than the IDispatch members, scripts written to work with this object might not work if the primary interop assembly is not installed.
VERBOSE: Running Microsoft Word 2010
VERBOSE: Validate company name
VERBOSE: Validate cover page
VERBOSE: Company Name: The Accidental Citrix Admin
VERBOSE: Cover Page  : Contrast
VERBOSE: User Name   : Amalgamated Consulting Group
VERBOSE: Farm Name   : PVS61Farm
VERBOSE: Title       : Inventory Report for the PVS61Farm Farm
VERBOSE: Filename    : C:\webster\PVS61Farm.docx
VERBOSE: Load Word Templates
VERBOSE: Create empty word doc
VERBOSE: disable spell checking
VERBOSE: insert new page, getting ready for table of contents
VERBOSE: table of contents
VERBOSE: set the footer
VERBOSE: get the footer and format font
VERBOSE: Footer text
VERBOSE: add page numbering
VERBOSE: return focus to main document
VERBOSE: move to the end of the current document
VERBOSE: Processing PVS Farm Information
VERBOSE: Processing Security Tab
VERBOSE: Processing Groups Tab
VERBOSE: Processing Licensing Tab
VERBOSE: Processing Options Tab
VERBOSE: Processing vDisk Version Tab
VERBOSE: Processing Status Tab
VERBOSE: Processing Sites
VERBOSE: Processing Site PVS61Site
VERBOSE: Processing Security Tab
VERBOSE: Processing Options Tab
VERBOSE: Processing vDisk Update Tab
VERBOSE: Processing Servers in Site PVS61Site
VERBOSE: Processing Server PVS61
VERBOSE: Processing General Tab
VERBOSE: Processing Network Tab
VERBOSE: Processing Stores Tab
VERBOSE: Processing Stores for server
VERBOSE: Processing Store PVS61Store
VERBOSE: Processing Options Tab
VERBOSE: Processing Logging Tab
VERBOSE: Processing Server Tab on Advanced button
VERBOSE: Processing Network Tab on Advanced button
VERBOSE: Processing Pacing Tab on Advanced button
VERBOSE: Processing Device Tab on Advanced button
VERBOSE: Processing Bootstrap files
VERBOSE: Processing Bootstrap files for Server PVS61
VERBOSE: Processing General Tab
VERBOSE: Processing Options Tab
VERBOSE: Processing all vDisks in site
VERBOSE: Processing vDisk PVS61vDisk
VERBOSE: Processing Properties General Tab
VERBOSE: Processing Identification Tab
VERBOSE: Processing Auto Update Tab
VERBOSE: Processing vDisk Update Management
VERBOSE: Processing virtual hosts
VERBOSE: Processing virtual host XenServer5
VERBOSE: Processing General Tab
VERBOSE: Processing Advanced Tab
VERBOSE: Processing all Update Managed vDisks for this site
VERBOSE: Processing Managed vDisk PVS61Store\PVS61vDisk
VERBOSE: Processing General Tab
VERBOSE: Processing Personality Tab
VERBOSE: Processing Status Tab
VERBOSE: Processing Logging Tab
VERBOSE: Processing Task Task2
VERBOSE: Processing General Tab
VERBOSE: Processing Schedule Tab
VERBOSE: Processing vDisks Tab
VERBOSE: Processing ESD Tab
VERBOSE: Processing Scripts Tab
VERBOSE: Processing Access Tab
VERBOSE: Processing Task Task3
VERBOSE: Processing General Tab
VERBOSE: Processing Schedule Tab
VERBOSE: Processing vDisks Tab
VERBOSE: Processing ESD Tab
VERBOSE: Processing Scripts Tab
VERBOSE: Processing Access Tab
VERBOSE: Processing all device collections in site
VERBOSE: Processing Collection PVS61Collection
VERBOSE: Processing General Tab
VERBOSE: Processing Security Tab
VERBOSE: Processing Auto-Add Tab
VERBOSE: Processing each collection process for each device
VERBOSE: Processing Device TestVM3
VERBOSE: Processing General Tab
VERBOSE: Processing vDisks Tab
VERBOSE: Processing all bootstrap files for this device
VERBOSE: Processing Authentication Tab
VERBOSE: Processing Personality Tab
VERBOSE: Processing all site views in site
VERBOSE: Processing all PVS Farm Views
VERBOSE: Processing Stores
VERBOSE: Processing Store PVS61Store
VERBOSE: Processing General Tab
VERBOSE: Processing Servers Tab
VERBOSE: Processing Server PVS61
VERBOSE: Processing Paths Tab
VERBOSE: Finishing up Word document
VERBOSE: Set Cover Page Properties
VERBOSE: Update the Table of Contents
VERBOSE: Save and Close document and Shutdown Word
PS C:\webster>

How to use this script?

I saved the script as PVS_Inventory_V2.ps1 in the C:\PSScripts folder.  From the PowerShell prompt, change to the C:\PSScripts folder, or the folder where you saved the script.  From the PowerShell prompt, type in:

.\PVS_Inventory_V2.ps1 and press Enter.

A word about Word

1. Word must be installed
2. After installation, Word should be opened, at least once, before you run the script
3. It is better to do File, Options, OK before running the script

The script does very strange things if the last two items are not done.  All kinds of errors are generated by the script if Word has not been opened at least once.  The second time the script is run (without Word haven been opened), fewer errors are generated.  The third time the script is run, it runs without errors.

Word 2013 is the worst.  If Word 2013 is installed and never opened before running the script, a popup box is shown asking to set file extension defaults.  It does not matter if Never ask me again is selected and Yes or No is clicked, the popup box will return until Word 2013 is opened and closed.

I am assuming there are registry keys and values that need to be set for the Word comObject to operate properly.

Bottom Line: If you just installed Word, open Word and close Word before running the script.

If you have any suggestions for the script, please let me know.  Send an e-mail to webster@carlwebster.com.

NOTE: This script is continually updated.  You can always find the most current version by going to https://www.carlwebster.com/where-to-get-copies-of-the-documentation-scripts/

Copies of all the Cover Pages, from the XenApp scripts, can be found here:

Word 2007

Word 2010

Word 2013

Note: This article was updated on November 20, 2015. Go to the bottom of this article to see the updated information.

I installed the Citrix XenApp 6.5 PowerShell SDK and Group Policy modules on my lab domain controller.  All my lab servers have the Windows Firewall enabled and Server Manager Remote Management enabled.

I found this information in the SDK help file on Remoting Cmdlets:

This section explains how to invoke the XenApp Commands remotely. In XenApp 6.5 the cmdlets can be remoted using
the -ComputerName parameter.  In order to facilitate running existing scripts remotely without having to make
significant changes, a default computer name can be set in the client machine. To do this a new set of cmdlets
was introduced. When the default computer name is set, all the cmdlets will automatically remote to the server
specified without having to explicitly use the -ComputerName parameter every time.

To set the default computer name:

Set-XADefaultComputerName server1

My lab XenApp 6.5 server is named XA65, so I entered on my domain controller.

Set-XADefaultComputerName XA65 

When I ran my documentation script, I received:

I then ran Microsoft’s Sysinternals ProcMon to get a network trace. I found that TCP Port 2513 needed to be opened (Figure 2).

My wife tells me I couldn’t find a 10 gallon (37.8541 Liter) jug of milk on the fridge’s top shelf!  What does this have to do with anything?  DOH! At the top of the help file, I now see (Figure 3):

The help text says TCP Port 2513 must be opened on both computers, but I found I only needed it opened on the XenApp server.  To me, that is one less port open on my network.

I created a Windows Firewall Rule on my XenApp server to open TCP Port 2513 between the domain controller and my XenApp server (Figure 4).  The “remoteip” will need to be the computer’s IP address used to run the script.

 netsh advfirewall firewall add rule name="Citrix PoSH TCP Port 2513" dir=in action=allow description="Allow communication between XenApp and remote computer running PoSH scripts" enable=yes profile=any remoteip=192.168.1.100 protocol=tcp localport=2513  

The Windows Firewall GUI shows my new rule created and enabled (Figure 5).

Now my script runs (Figure 6).

Now you can use my XenApp 6.5 PowerShell Documentation Script with absolutely no modifications and have it work with remoting.  Thanks, Citrix, for making this so easy.

Update November 20, 2015:

If you are having an issue connecting, make sure the Citrix XenApp Commands Remoting service is started. I have seen this service in three states at various locations: Manual, Automatic but not Started, and Automatic and Started.  Make sure this service is Started, and then your remote connection should succeed.

Thanks to my Aussie friend Jeremy Saunders for reminding me to update this article with this information.

netsh advfirewall monitor show firewall rule name=all dir=in

command so I turned to using PowerShell.

I found the following article by James O’Neill that helped me get started.

http://blogs.technet.com/b/jamesone/archive/2009/02/18/how-to-manage-the-windows-firewall-settings-with-powershell.aspx

What I needed for a headstart was the following code from James’ article:

Function Get-FireWallRule
{Param ($Name, $Direction, $Enabled, $Protocol, $profile, $action, $grouping)
$Rules=(New-object –comObject HNetCfg.FwPolicy2).rules
If ($name)      {$rules= $rules | where-object {$_.name     -like $name}}
If ($direction) {$rules= $rules | where-object {$_.direction  -eq $direction}}
If ($Enabled)   {$rules= $rules | where-object {$_.Enabled    -eq $Enabled}}
If ($protocol)  {$rules= $rules | where-object {$_.protocol   -eq $protocol}}
If ($profile)   {$rules= $rules | where-object {$_.Profiles -bAND $profile}}
If ($Action)    {$rules= $rules | where-object {$_.Action     -eq $Action}}
If ($Grouping)  {$rules= $rules | where-object {$_.Grouping -like $Grouping}}
$rules}

Get-firewallRule -enabled $true | sort direction,applicationName,name |
format-table -wrap -autosize -property Name, @{Label=”Action”; expression={$Fwaction[$_.action]}},
@{label="Direction";expression={ $fwdirection[$_.direction]}},
@{Label="Protocol"; expression={$FwProtocols[$_.protocol]}} , localPorts,applicationname

I created a script named listfw.ps1 and when I ran the script, I received the output shown in Figure 1.

The last column wasn’t formatted properly for me so I thought maybe the “–wrap” parameter of  Format-Table was causing the issue.  So I removed the “-wrap” and reran the script.  I received the output shown in Figure 2.

OK, still not what I need.  So I thought maybe the “-autosize” was the culprit.  I removed the “-autosize” and reran the script.  I received the output shown in Figure 3.

OK, I am getting further away from what I really.  What I want is a way for the Name column and the ApplicationName column to be full width.

Using get-help format-table –full gave me a clue.  The “-property” parameter has some options available:

-- Name (or Label) <string>
-- Expression <string> or <script block>
-- FormatString <string>
-- Width <int32>
-- Alignment  (value can be "Left", "Center", or "Right")

I can see in Jame’s original code he is using the “Label” and “Expression” options.  I just need to figure out how to use the “Width” option.  After much trial and error, I came up with the following code:

$spaces1 = " " * 71
$spaces2 = " " * 64
Get-firewallRule -enabled $true | sort name | `
format-table -property `
@{label="Name" + $spaces1             ; expression={$_.name}                    ; width=75}, `
@{label="Action"                      ; expression={$Fwaction[$_.action]}       ; width=6 }, `
@{label="Direction"                   ; expression={$fwdirection[$_.direction]} ; width=9 }, `
@{label="Protocol"                    ; expression={$FwProtocols[$_.protocol]}  ; width=8 }, `
@{label="Local Ports"                 ; expression={$_.localPorts}              ; width=11}, `
@{label="Application Name" + $spaces2 ; expression={$_.applicationname}         ; width=80}

Running the script gives me the output shown in Figure 4.

DOH! So close.  It seems the output is now limited by the width of the screen.  Looking at the help for Get-Table, I cannot see any option that allows me to make the table wider.  That led me to find this article.

http://poshoholic.com/2010/11/11/powershell-quick-tip-creating-wide-tables-with-powershell/

It appears the solution is very simple.  Use out-string –width nnn.  Using a width of 200 and running the following command, I get what is shown below.

.\listfw.ps1 | out-string –width 200 | out-file .\fw.txt

Name                                                                        Action Direction Protocol Local Ports Application Name
--------------------------------------------------------------------------- ------ --------- -------- ----------- --------------------------------------------------------------------------------
Citrix ICA (TCP-In)                                                                                   1494
Citrix IMA (TCP-In)                                                                                   2512
Citrix MFCOM (RPC)                                                                                    RPC         C:\Program Files (x86)\Citrix\system32\mfcom.exe
Citrix Print Service (RPC)                                                                            RPC         C:\Program Files (x86)\Citrix\system32\CpSvc.exe
Citrix Remote MFCOM DLLs (RPC)                                                                        RPC         C:\Windows\SysWOW64\dllhost.exe
Citrix Session Reliability (TCP-In)                                                                   2598        C:\Program Files (x86)\Citrix\XTE\bin\xte.exe
Citrix SSL Relay (TCP-In)                                                                             443         C:\Program Files (x86)\Citrix\XTE\bin\xte.exe
Citrix WI Configuration Manager (RPC)                                                                 RPC         C:\Program Files (x86)\Citrix\System32\ConfigMgrSvr.exe
Citrix XML Relay (TCP-In)                                                                             81          C:\Program Files (x86)\Citrix\System32\ctxxmlss.exe
Core Networking - Destination Unreachable (ICMPv6-In)                                                             System
Core Networking - Destination Unreachable Fragmentation Needed (ICMPv4-In)                                        System
Core Networking - DNS (UDP-Out)                                                                       *           C:\Windows\system32\svchost.exe
Core Networking - Dynamic Host Configuration Protocol (DHCP-In)                                       68          C:\Windows\system32\svchost.exe
Core Networking - Dynamic Host Configuration Protocol (DHCP-Out)                                      68          C:\Windows\system32\svchost.exe
Core Networking - Dynamic Host Configuration Protocol for IPv6(DHCPV6-In)                             546         C:\Windows\system32\svchost.exe
Core Networking - Dynamic Host Configuration Protocol for IPv6(DHCPV6-Out)                            546         C:\Windows\system32\svchost.exe
Core Networking - Group Policy (LSASS-Out)                                                            *           C:\Windows\system32\lsass.exe
Core Networking - Group Policy (NP-Out)                                                               *           System
Core Networking - Group Policy (TCP-Out)                                                              *           C:\Windows\system32\svchost.exe
Core Networking - Internet Group Management Protocol (IGMP-In)                                                    System
Core Networking - Internet Group Management Protocol (IGMP-Out)                                                   System
Core Networking - IPHTTPS (TCP-In)                                                                    IPHTTPS     System
Core Networking - IPHTTPS (TCP-Out)                                                                   *           C:\Windows\system32\svchost.exe
Core Networking - IPv6 (IPv6-In)                                                                                  System
Core Networking - IPv6 (IPv6-Out)                                                                                 System
Core Networking - Multicast Listener Done (ICMPv6-In)                                                             System
Core Networking - Multicast Listener Done (ICMPv6-Out)
Core Networking - Multicast Listener Query (ICMPv6-In)                                                            System
Core Networking - Multicast Listener Query (ICMPv6-Out)
Core Networking - Multicast Listener Report (ICMPv6-In)                                                           System
Core Networking - Multicast Listener Report (ICMPv6-Out)
Core Networking - Multicast Listener Report v2 (ICMPv6-In)                                                        System
Core Networking - Multicast Listener Report v2 (ICMPv6-Out)
Core Networking - Neighbor Discovery Advertisement (ICMPv6-In)                                                    System
Core Networking - Neighbor Discovery Advertisement (ICMPv6-Out)
Core Networking - Neighbor Discovery Solicitation (ICMPv6-In)                                                     System
Core Networking - Neighbor Discovery Solicitation (ICMPv6-Out)
Core Networking - Packet Too Big (ICMPv6-In)                                                                      System
Core Networking - Packet Too Big (ICMPv6-Out)
Core Networking - Parameter Problem (ICMPv6-In)                                                                   System
Core Networking - Parameter Problem (ICMPv6-Out)
Core Networking - Router Advertisement (ICMPv6-In)                                                                System
Core Networking - Router Advertisement (ICMPv6-Out)
Core Networking - Router Solicitation (ICMPv6-In)                                                                 System
Core Networking - Router Solicitation (ICMPv6-Out)
Core Networking - Teredo (UDP-In)                                                                     Teredo      C:\Windows\system32\svchost.exe
Core Networking - Teredo (UDP-Out)                                                                    *           C:\Windows\system32\svchost.exe
Core Networking - Time Exceeded (ICMPv6-In)                                                                       System
Core Networking - Time Exceeded (ICMPv6-Out)
DFS Management (DCOM-In)                                                                              135         C:\Windows\system32\svchost.exe
DFS Management (SMB-In)                                                                               445         System
DFS Management (TCP-In)                                                                               RPC         C:\Windows\system32\dfsfrsHost.exe
DFS Management (WMI-In)                                                                               RPC         C:\Windows\system32\svchost.exe
Remote Desktop - RemoteFX (TCP-In)                                                                    3389        C:\Windows\system32\svchost.exe
Remote Desktop (TCP-In)                                                                               3389        System
SQL Server (Citrix IMA)                                                                               *           C:\Program Files (x86)\Microsoft SQL Server\MSSQL10.CITRIX_METAFRAME\MSSQL\Bi...
SQL Server Browser (Citrix IMA)                                                                       *           C:\Program Files (x86)\Microsoft SQL Server\90\Shared\sqlbrowser.exe
Terminal Services - WMI (DCOM-In)                                                                     135         C:\Windows\system32\svchost.exe
Terminal Services - WMI (TCP-In)                                                                      RPC         C:\Windows\system32\svchost.exe
Terminal Services - WMI (WMI-Out)                                                                     *           C:\Windows\system32\svchost.exe
Terminal Services (NP-In)                                                                             445         System
Terminal Services (RPC)                                                                               RPC         C:\Windows\system32\svchost.exe
Terminal Services (RPC-EPMAP)                                                                         RPC-EPMap   C:\Windows\system32\svchost.exe

Now I have a report I can use. I can run this script before and after installing XenApp 6.5 and see what changes were made to the Windows Firewall rules.

This article will focus only on XenDesktop 4.  I am planning on writing articles and scripts for XenDesktop 5.x.

The prerequisites to follow along with this article are:

• A computer, physical or virtual, running Microsoft Windows Server 2003, Server 2008, Server 2008 R2, or Microsoft Windows XP, Vista, or 7 for running the XenDesktop Desktop Delivery Controller SDK.
• Citrix XenDesktop 4 Desktop Delivery Controller (DDC) installed with at least one Desktop Group created.

In this article, we will be installing the Citrix Delivery Controller SDK.  You can install the SDK from either the XenDesktop 4 installation media or download it from citrix.com.  Since I am at a customer site creating this script on a production network, I do not have access to the installation media.  Therefore, I will be downloading the SDK.

My initial goal was to see if I could walk down the nodes in the Delivery Services Console (DSC) (Figure 1) and see if I could document every nook and cranny.

Note:  For instructions on how to install the SDK from the XenDesktop 4 installation media, please see http://blogs.citrix.com/2010/08/11/xendesktop-4-powershell-sdk-primer-part-1-getting-started/.

Update 7-July-2021: Citrix, obviously, killed these old XD4 links.

For the SDK install, go to https://carlwebster.sharefile.com/d-s6239e1f90eb043d7a2642fbc61db997a

For the SDK Welcome, go to https://carlwebster.sharefile.com/d-s559804f9b3244ff58669263ab1e7dc06

Click Start, Run, type in C:\XD4SDK\XenDesktopControllerSDK.msi and press Enter.

Click Run (Figure 3).

Select I accept the terms in the License Agreement and click Next (Figure 5).

Click Install (Figure 7).

You now have new Start Menu items under All Programs, Citrix.  Windows 7 is shown in Figure 9.

Everything is now set up for us to get started.  The download page for the SDK says to get a listing of the available XenDesktop commands to enter the following command:

Get-Command -psSnapin XdCommands

Typing that line into the PowerShell session returns a list of Citrix XenDesktop PowerShell commands.  A sample is shown in Figure 10.

To get a list of the Get commands, showing just the Name, where the noun starts with “Xd”, type the following in the PowerShell session (results are shown in Figure 11):

Get-Command –Noun Xd* -Verb Get | Select-Object Name

Of the eight Get-Xd* commands listed, only three are usable for documenting the Farm:

• Get-XdFarm
• Get-XdController
• Get-XdDesktopGroup

One feature I like about the XenDesktop PowerShell commands is that you are not required to run them directly on a Controller.  You can use the –AdminAddress parameter to give the name or IP address of a Controller to run the command against.  Since I am developing this script on a production Farm, I am being safe and staying off the customer’s production Controllers.

Typing each of the commands into the PowerShell session gave me the results shown in Figure 12, Figure 13, and Figure 14.

Note:  I am using a Formatted List (| fl) to see all the properties returned by each command.

My goal is to use the same wording as what is seen in the DSC for headings, captions, and text.  In order to do that, I needed a way to format the output text.  Michael B. Smith (MBS) developed a function for me to use called Line.

Function line
#function created by Michael B. Smith, Exchange MVP
#@essentialexchange on Twitter
#http://TheEssentialExchange.com

{
	Param( [int]$tabs = 0, [string]$name = ’’, [string]$value = ’’, [string]$newline = “`n”, [switch]$nonewline )

	While( $tabs –gt 0 ) { $global:output += “`t”; $tabs--; }

	If( $nonewline )
	{
		$global:output += $name + $value
	}
	Else
	{
		$global:output += $name + $value + $newline
	}
}

Another lesson MBS taught me is to check to see if each cmdlet used returned an error and how to tell the cmdlet how I wanted to proceed if there was an error.  This is done by using –ErrorAction, or –EA.  ErrorAction has four values (Table 1):

Table 1

For this documentation script, I always use 0.  If an error occurs, I want the rest of the script to continue.

Next, I needed to know how to test to see if an action, like Get-XdFarm, succeeded or had an error.  MBS said to use $? to test if the most recent action succeeded (True) or had an error (False).  For example:

$farm = Get-XdFarm -EA 0
If( $? )
{
	#success
}
Else
{
	#error
}

Because this script does not have to run on a Controller, a parameter is created to allow a Controller name or IP address to be used.

Let’s get started.  We will build the script node by node.  Some of the lines may wrap.

The beginning of the script:

#Carl Webster, CTP and independent consultant
#webster@carlwebster.com
#@carlwebster on Twitter
#https://www.carlwebster.com
#This script written for "SR", March 9, 2012
#Thanks to Michael B. Smith, Joe Shock, Jarian Gibson and James Rankin
#for testing and fine-tuning tips

Param(
[string]$DDCAddress = ""
)

Function line
#function created by Michael B. Smith, Exchange MVP
#@essentialexchange on Twitter
#http://TheEssentialExchange.com

{
	Param( [int]$tabs = 0, [string]$name = ’’, [string]$value = ’’, [string]$newline = “`n”, [switch]$nonewline )

	While( $tabs –gt 0 ) { $global:output += “`t”; $tabs--; }

	If( $nonewline )
	{
		$global:output += $name + $value
	}
	Else
	{
		$global:output += $name + $value + $newline
	}
}

#script begins

The first node in the DSC is the Farm itself.

#get farm information
$global:output = ""

If($DDCAddress)
{
	$farm = Get-XdFarm -adminaddress $DDCAddress -EA 0
}
Else
{
	$farm = Get-XdFarm -EA 0
}

If( $? )
{
	line 0 "XenDesktop Farm Name: " $farm.Name
	line 1 "XenDesktop Edition: " -nonewline
	switch ($farm.edition)
	{
		"PLT"   {line 0 "Platinum"  }
		"STD"   {line 0 "VDI"       }
		"ADV"   {line 0 "Advanced"  }
		"ENT"   {line 0 "Enterprise"}
		default {line 0 "Farm Edition could not be determined: $($farm.edition)"}
	}

	line 1 "Base OU: " $farm.BaseOU
	line 1 "License server"
	line 2 "Name: " $farm.LicenseServerName
	line 2 "Port number: " $farm.LicenseServerPort
	line 1 "Session reliability"
	line 2 "Allow users to view sessions during broken connections: " $farm.EnableSessionReliability

	If($farm.EnableSessionReliability)
	{
		line 3 "Port number: " $farm.SessionReliabilityPort
		line 3 "Seconds to keep sessions active: " $farm.SessionReliabilityDurationSeconds
	}
} 
Else 
{
	line 0 "XenDesktop Farm information could not be retrieved"
}
write-output $global:output
$farm = $null
$global:output = $null

$global:output = ""

Sample script output:

XenDesktop Farm Name: SAMPLEXD4
        XenDesktop Edition: Platinum
        Base OU: XD4BaseOU
        License server
                Name: CTXLICENSE
                Port number: 0
        Session reliability
                Allow users to view sessions during broken connections: True
                        Port number: 2598
                        Seconds to keep sessions active: 60

Even though the license server port number is displayed as 27000 in the console, the Citrix cmdlet returns  0.

The next node in the DSC is Administrators, but Citrix does not provide a way to retrieve any information about the Administrators.

The next node is the Controllers.  Even though Controllers can be in folders, Citrix does not provide a way to retrieve Folder information.

#get controller information
If($DDCAddress)
{
	$XDControllers = Get-XdController -adminaddress $DDCAddress -EA 0
}
Else
{
	$XDControllers = Get-XdController -EA 0
}

If( $? )
{
	line 0 "Desktop Delivery Controllers:"
	ForEach($XDController in $XDControllers)
	{
		line 1 "Controller: " $XDController.Name
		line 1 "Version: " $XDController.Version
		line 1 "Zone Election Preference: " $XDController.ZoneElectionPreference
		line 1 "License Server"
		If($XDController.UseFarmLicenseServerSettings)
		{
			line 2 "Using Farm Setting"
		}
		Else
		{
			Line 2 "License server"
			line 3 "Name: " $XDController.LicenseServerName
			line 3 "Port number: " $XDController.LicenseServerPort
		}
		line 1 ""
	}
} 
Else 
{
	line 0 "Desktop Delivery Controller information could not be retrieved"
}
write-output $global:output
$XDControllers = $null
$global:output = $null

Sample script output:

Desktop Delivery Controllers:
        Controller: DDC1
        Version: 4.0
        Zone Election Preference: Member
        License Server
                Using Farm Setting

        Controller: DDC2
        Version: 4.0
        Zone Election Preference: Member
        License Server
                Using Farm Setting

The last node is Desktop Groups. There are different options available depending on if the Desktop Group is Pooled or Assigned.  Instead, I returned the AD Computer Account name as shown in the console, and the cmdlet returns the Machine SID.  Also, not every user account returned a name, but the User SID was always returned.  MBS showed me how to convert a Machine or User Account SID to the Machine or User Name.

$objSID = New-Object System.Security.Principal.SecurityIdentifier ($Desktop.MachineSid.Value)
$objComputer = $objSID.Translate([System.Security.Principal.NTAccount])
"AD Computer Account: " $objComputer.Value

And

$objSID = New-Object System.Security.Principal.SecurityIdentifier($Desktop.AssignedUserSid.Value)
$objUser = $objSID.Translate([System.Security.Principal.NTAccount])
“Assigned User: “ $objUser.Value

#get desktop group information
$global:output = ""

If($DDCAddress)
{
	$XDGroups = Get-XdDesktopGroup -adminaddress $DDCAddress -EA 0
}
Else
{
	$XDGroups = Get-XdDesktopGroup -EA 0
}

If( $? )
{
	line 0 "Desktop Groups:"
	ForEach($XDGroup in $XDGroups)
	{
		line 1 "Basic"
		line 2 "Desktop Group Name"
		line 3 "Display name: " $XDGroup.Name
		line 3 "Description: " $XDGroup.Description
		line 3 "Desktop Group name: " $XDGroup.InternalName
		line 3 "Disable desktop group: " -nonewline
		If($XDGroup.Enabled)
		{
			line 0 "group is enabled"
		}
		Else
		{
			line 0 "group is disabled"
		}

		line 2 "Assignment Type"
		line 3 "Assignment Behavior: " $XDGroup.AssignmentBehavior

		If($XDGroup.IsHosted)
		{
			line 2 "Hosting infrastructure: " $XDGroup.HostingSettings.HostingServer
		}


		line 2 "Users"
		line 3 "Configured users:"
		ForEach($User in $XDGroup.Users)
		{
			line 4 $User
			#line 4 "SID: " $User.Sid
			line 4 "Group or User: " -nonewline
			If($User.IsSecurityGroup)
			{
				line 0 "Group"
			}
			Else
			{
				line 0 "User"
			}
		}
		line 2 "Virtual Desktops"
		line 3 "Virtual desktops:"
		ForEach($Desktop in $XDGroup.Desktops)
		{
			line 4 "Folder: " $XDGroup.Folder
			line 4 "Virtual Machine: " $Desktop
			$objSID = New-Object System.Security.Principal.SecurityIdentifier ($Desktop.MachineSid.Value)
			$objComputer = $objSID.Translate([System.Security.Principal.NTAccount])
			line 4 "AD Computer Account: " $objComputer.Value
			line 4 "Desktop State: " $Desktop.State
			line 4 "Assigned User: " -nonewline
			If($Desktop.AssignUserName)
			{
				line 0 $Desktop.AssignUserName
			}
			ElseIf($Desktop.AssignedUserSid)
			{
				$objSID = New-Object System.Security.Principal.SecurityIdentifier ($Desktop.AssignedUserSid.Value)
				$objUser = $objSID.Translate([System.Security.Principal.NTAccount])
				line 0 $objUser.Value
			}
			Else
			{
				line 0 ""
			}
			line 4 "Maintenance Mode: " $Desktop.MaintenanceMode
			line 4 "Machine State: " $Desktop.PowerState
			line 4 "Controller: " $Desktop.Controller
			line 4 "Agent Version: " $Desktop.AgentVersion
			line 1 ""
		}
		line 1 "Advanced"
		line 2 "Access Control"

		$test = $XDGroup.AccessGatewayControl.ToString()
		$test1 = $test.replace(", ","`n`t`t")

		line 3 $test1
		line 2 "Access Gateway Conditions: "
		ForEach($Condition in $XDGroup.AccessGatewayConditions)
		{
			line 3 $Condition
		}
		line 2 "Client Options"
		line 3 "Appearance"
		line 4 "Colors: " -nonewline
		switch ($XDGroup.DefaultColorDepth)
		{
			"FourBit"       {line 0 "16 colors"          }
			"EightBit"      {line 0 "256 colors"         }
			"SixteenBit"    {line 0 "High color (16-bit)"}
			"TwentyFourBit" {line 0 "True color (24-bit)"}
			default         {line 0 "Color depth could not be determined: $($XDGroup.DefaultColorDepth)"}

		}
		line 3 "Connection"
		line 4 "Encryption: " -nonewline
		switch ($XDGroup.DefaultEncryptionLevel)
		{
			"Basic"               {line 0 "Basic"                    }
			"LogOnRC5Using128Bit" {line 0 "128-Bit Login Only (RC-5)"}
			"RC5Using40Bit"       {line 0 "40-Bit (RC-5)"            }
			"RC5Using56Bit"       {line 0 "56-Bit (RC-5)"            }
			"RC5Using128Bit"      {line 0 "128-Bit (RC-5)"           }
			default               {line 0 "Encryption level could not be determined: $($XDGroup.DefaultEncryptionLevel)"}

		}
		line 3 "Connection Protocols: "
		ForEach($Protocol in $XDGroup.Protocols)
		{
			line 4 "Name: " $Protocol.Protocol
			line 4 "Enabled: " $Protocol.Enabled
		}

		#only show the next section if the Desktop Group is Pooled
		If($XDGroup.AssignmentBehavior -eq "Pooled")
		{
			line 2 "Idle Pool Settings"
			line 3 "Business Hours"
			line 4 "Business days "
			ForEach($Day in $XDGroup.HostingSettings.BusinessDays)
			{
				line 5 $Day
			}
			line 4 "Time zone "  $XDGroup.HostingSettings.IdleTimesTimeZone
			IF($XDGroup.HostingSettings.PeakHoursStart)
			{
				line 4 "Day start "  $XDGroup.HostingSettings.PeakHoursStart.ToString()
			}
			If($XDGroup.HostingSettings.PeakHoursEnd)
			{
				line 4 "Peak end "  $XDGroup.HostingSettings.PeakHoursEnd.ToString()
			}
			If($XDGroup.HostingSettings.BusinessHoursEnd)
			{
				line 4 "Day end " $XDGroup.HostingSettings.BusinessHoursEnd.ToString()
			}
			line 3 "Idle Desktop Count"
			line 2 "Business hours " $XDGroup.HostingSettings.BusinessHoursIdleCount
			line 2 "Peak time " $XDGroup.HostingSettings.PeakHoursIdleCount
			line 2 "Out of hours " $XDGroup.HostingSettings.OutOfHoursIdleCount
		}
		
		# I can't find these settings in the console
		line 1 "Other settings"
		line 2 "Allow User Desktop Restart: " $XDGroup.AllowUserDesktopRestart
		line 2 "Tainted Machine Action: " $XDGroup.HostingSettings.TaintedMachineAction
		line 3 "Actions: "
		ForEach($Action in  $XDGroup.HostingSettings.Actions)
		{
			line 4 "Action point: " $Action.ActionPoint
			line 4 "Action: " $Action.Action
			line 4 "Delay: " $Action.Delay
			line 4 ""
		}


		line 1 ""
	}
} 
Else 
{
	line 0 "Desktop Group information could not be retrieved"
}
write-output $global:output
$XDGroups = $null
$test = $null
$test1 = $null
$global:output = $null

Sample script output:

Desktop Groups:
Basic
		Desktop Group Name
			Display name: WebstersLab
			Description: Used in Webster’s Lab for writing purposes
			Desktop Group name: WebstersLab
			Disable desktop group: group is enabled
		Assignment Type
			Assignment Behavior: Pooled
		Hosting infrastructure: http://msvirtualcenter.carls.com/sdk
		Users
			Configured users:
				CARLS\TS_XD_Lab
				Group or User: Group
				CARLS\TS_XD_Lab_Admin
				Group or User: Group
		Virtual Desktops
			Virtual desktops:
				Folder: \
				Virtual Machine: CARLS\COMPUTER01$
				AD Computer Account: CARLS\COMPUTER01$
				Desktop State: Available
				Assigned User: 
				Maintenance Mode: False
				Machine State: On
				Controller: DDC1
				Agent Version: 4.0.4522
	
				Folder: \
				Virtual Machine: CARLS\COMPUTER06$
				AD Computer Account: CARLS\COMPUTER06$
				Desktop State: NotRegistered
				Assigned User: 
				Maintenance Mode: False
				Machine State: On
				Controller: 
				Agent Version: 

	Advanced
		Access Control
			AllowGatewayNoConditionsDefined
		AllowGatewayAnyCondition
		Access Gateway Conditions: 
		Client Options
			Appearance
				Colors: High color (16-bit)
			Connection
				Encryption: Basic
			Connection Protocols: 
				Name: ICA30
				Enabled: True
		Idle Pool Settings
			Business Hours
				Business days 
					Sunday
					Monday
					Tuesday
					Wednesday
					Thursday
					Friday
					Saturday
				Time zone (UTC-05:00) Eastern Time (US & Canada)
				Day start 01:00:00
				Peak end 20:30:00
				Day end 23:30:00
			Idle Desktop Count
		Business hours 7
		Peak time 7
		Out of hours 7
	Other settings
		Allow User Desktop Restart: False
		Tainted Machine Action: Restart
			Actions: 
				Action point: Disconnect
				Action: DoNothing
				Delay: 300
				
				Action point: LogOff
				Action: Shutdown
				Delay: 420
		

How to use this script?

I saved the script as XD4_Inventory.ps1 in the Z:\ folder.  From the PowerShell prompt, change to the Z:\ folder or the folder where you saved the script.  From the PowerShell prompt, type in:

.\XD4_Inventory.ps1 |out-file Z:\XD4Farm.txt and press Enter, or

.\XD4_Inventory.ps1 DDCName|out-file Z:\XD4Farm.txt and press Enter, or

.\XD4_Inventory.ps1 DDCIPAddress|out-file Z:\XD4Farm.txt and press Enter.

Open XD4Farm.txt in either WordPad or Microsoft Word (Figure 15).

You can always find the most current script by going to https://www.carlwebster.com/where-to-get-copies-of-the-documentation-scripts/

Thanks

Webster

Update: I now use the Digicert Certificate Utility for Windows to sign all my scripts.

Code Signing with the DigiCert® Certificate Utility for Windows

The first thing needed is to request a code signing certificate.  At DigiCert, I clicked on Code Signing Certificates (Figure 1).

I then selected Buy Now (Figure 2).

I then selected Code Signing Cert, a Validity Period, and clicked Continue (Figure 3).

Next, I selected Microsoft Authenticode and clicked Continue (Figure 4).

Next, I filled in my Organization Details and clicked Continue (Figure 5).

I then filled in my Contact Details and clicked Continue (Figure 6).

I removed the Payment step information.  I selected I agree to the Terms of Service above and clicked Complete Order (Figure 7).

I then received an e-mail from DigiCert Support asking me to verify that I did request a Code Signing Certificate.  After I replied to the e-mail in the affirmative, I received another e-mail with a link to create the code-signing certificate (Figure 8).

Clicking the link in the e-mail opens my Internet browser with the following popup (Figure 9).  I clicked Yes.

Which then took me to the web site shown in Figure 10.  I then clicked Generate Certificate.

Which then took me to the web page shown in Figure 11.

I verified in Internet Explorer that the certificate is installed (Figure 12 and Figure 13).

On the computer where the Code Signing Certificate was installed, I started a PowerShell session running as Administrator.  Using the information from Don Jones’ Windows PowerShell 2.0 TFM book on page 149, I entered the following PowerShell command (should be one long line):

Set-AuthenticodeSignature `
"C:\Users\cwebster\Documents\carlwebster.com\Documenting a Citrix XenApp 6 Farm with Microsoft PowerShell\XA6_Inventory_Signed.ps1" `
-TimestampServer "http://timestamp.digicert.com/" @(Get-Childitem cert:\CurrentUser\My -codesigning)[0]

Which then returns a successful signing (Figure 14).

Opening my script shows the added signature block (Figure 15).

To verify the newly signed script, I went to my XenApp 6 server, copied the signed script to the C:\PSScripts folder, started a PowerShell session as Administrator, and changed to the C:\PSScripts folder.  I then set the PowerShell script execution policy to AllSigned (Figure 16).

I then tried to run the original unsigned script (Figure 17).  The script would not run because it is not digitally signed.

I then tried to run the signed script (Figure 18).

I answered A to Always run scripts signed by me (Figure 19) and the script runs successfully.

By answering Always run my code signing certificate was installed on the server in the Trusted Publishers store (Figure 20).

The next time I run the signed script, the script automatically runs (Figure 21).

What I learned is that digitally signing PowerShell scripts is simple to do.  It is not cheap, but it is simple.

All current documentation scripts create a Microsoft Word 2010,  2013, or 2016/2019/O365 document.

Word 2016, Word 2019 and the Office 365 version of Word have the same version number of 16. All documentation scripts will work with Word 2019 and Word Office 365 with no changes.

*****All the scripts run best on PowerShell Version 5*****

Many people have asked me where they can get copies of the various PowerShell documentation scripts. To make it easier to find, I have linked to all of them in this one article.

All scripts have been moved to the new Downloads page.

I am leaving this landing page here so I don’t break all the existing links people have to this page.

Thanks

Webster

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