PowerShell programmer interface with objects to manage Citrix Provisioning 2003 implementation

PowerShell programmer interface with objects is one of the four programming interfaces used for Citrix Provisioning implementation from a command line or scripts.

The four different programming interfaces that exist are:

• Management Command Line Interface (MCLI SOAP server). For more information on MCLI, see the Citrix Provisioning 1906 MCLI Programmer’s Guide.
• Simple Object Access Protocol (SOAP) Server Programmer Interface
• PowerShell Programmer Interface with Objects
• PowerShell Programmer Interface (Deprecated)

This document provides the information needed to use this interface.

You can install, register, uninstall, and unregister PowerShell snap-in (Citrix.PVS.SnapIn.dll). Use different commands and examples to set up the SOAP server communication.

Short command list, commands categorized by object type, status codes for each command, and cmdlets with description are provided as reference for using the SOAP APIs.

Note:

You must have correct administrative privileges to use the programming commands. If you attempt to use the commands without having elevated privileges, the system displays an ‘Invalid access’ message.

Using the PowerShell Programmer Interface withObjects

Use the information that follows to manage a ProvisioningService’s implementation from the PowerShell Interface with Objects.

Installation of PowerShell Snap-In

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

Registration of McliPSSnapIn.dll usingImport-Module

If the snap-in later needs to be registered in PowerShell,this can be manually done by running one of the following command inPowerShell. The path where the Citrix.PVS.SnapIn.dll is installed needs to be used.

Import-Module “path\Citrix.PVS.SnapIn.dll”

Registration of Citrix.PVS.SnapIn.dll usingAdd-PSSnapin

If the snap-in later needs to be registered in PowerShell,this can be manually done by running one of the following commands at the DOS command prompt. After the command is run and PowerShell is started, the snap-in needs to be added using the command “Add-PSSnapin -Name Citrix.PVS.SnapIn”.

64-bit Registration

%systemroot%\Microsoft.NET\Framework64\v4.0.30319\installutil.exeCitrix.PVS.SnapIn.dll

32-bit Registration

%systemroot%\Microsoft.NET\Framework\v4.0.30319\installutil.exeCitrix.PVS.SnapIn.dll

Alternative Registration of Citrix.PVS.SnapIn.dllin PowerShell

Another way to register is by running one of the following commands at the PowerShell command prompt:

64-bit Registration in PowerShell

$installutil= $env:systemroot + '\Microsoft.NET\Framework64\v4.0.30319\installutil.exe'

;$installutilCitrix.PVS.SnapIn.dll

Add-PSSnapin-Name Citrix.PVS.SnapIn

32-bit Registration in PowerShell

$installutil= $env:systemroot + '\Microsoft.NET\Framework32\v4.0.30319\installutil.exe'

;$installutilCitrix.PVS.SnapIn.dll

Add-PSSnapin-Name Citrix.PVS.SnapIn

Uninstall of PowerShell Snap-In

The PowerShell snap-in (Citrix.PVS.SnapIn.dll) can beuninstalled using the Provisioning Server Console install.

Unregister of Citrix.PVS.SnapIn.dll

The snap-in needs to be unregistered from PowerShell, thiscan be manually done by running one of the following commands at the DOScommand prompt:

64-bit Unregister

%systemroot%\Microsoft.NET\Framework64\v4.0.30319\installutil.exe-u Citrix.PVS.SnapIn.dll

32-bit Unregister

%systemroot%\Microsoft.NET\Framework\v4.0.30319\installutil.exe-u Citrix.PVS.SnapIn.dll

Alternative Unregister of Citrix.PVS.SnapIn.dll inPowerShell

Another way to unregister is by running one of the followingcommands at the PowerShell command prompt:

64-bit Unregister in PowerShell

$installutil= $env:systemroot + '\Microsoft.NET\Framework64\v4.0.30319\installutil.exe'

;$installutil-u Citrix.PVS.SnapIn.dll

32-bit Unregister in PowerShell

$installutil= $env:systemroot + '\Microsoft.NET\Framework32\v4.0.30319\installutil.exe'

;$installutil-u Citrix.PVS.SnapIn.dll

Setup of the SOAP Server Communication

Unless the defaults are fine, use this command to set thevalues for the SOAP Server connection:

Set-PvsConnection

Set the SoapServer connection, and if -Persist isspecified the connection settings are saved in the registry. A PvsConnectionobject can be used as the parameter.

Required

PvsConnection Connection: PvsConnection object withchanged property value(s) to be set. The object can come from a pileline.

These values are in the PvsConnection object, andonly will be set if the value has changed.

string Name or Server: Name or IP of the Server toconnect to. Default=localhost

string Port: The Port to use to connect.Default=54321

string User: User name to use for Authentication. Ifit has a value, it will be *****. Default=""

string Domain: Domain name to use forAuthentication. If it has a value, it will be *****. Default=""

string Password: Password to use for Authentication.If it has a value, it will be *****. Default=""

string Persist: True when the connection settingsshould be, for Set, or have been, for Get, saved to the registry.

PvsConnection can be created or modified usingmethods below:

New-Object Citrix.PVS.SnapIn.PvsConnection: Createsdefault Server=localhost, Port=54321, and no authentication.

New-ObjectCitrix.PVS.SnapIn.PvsConnection(Citrix.PVS.SnapIn copyFrom): Creates withsettings of the copyFrom Citrix.PVS.SnapIn.

SetServerToLocalHostDefaultSettings:Server=localhost, Port=54321, and no authentication.

Copy(Citrix.PVS.SnapIn copyFrom): Modifies thesettings to match the copyFrom Citrix.PVS.SnapIn.

Equals(Citrix.PVS.SnapIn compareTo): Returns truewhen the settings match what is in the compareTo.

When Connection is not passed, the parameters beloware used:

Optional field values to set:

string Name or Server: Name or IP of the Server toconnect to. Default=localhost

string Port: The Port to use to connect.Default=54321

string User: User name to use for Authentication. Ifit has a value, it will be *****. Default=""

string Domain: Domain name to use forAuthentication. If it has a value, it will be *****. Default=""

string Password: Password to use for Authentication.If it has a value, it will be *****. Default=""

string Persist: True when the connection settingsshould be, for Set, or have been, for Get, saved to the registry.

Optional

SwitchParameter PassThru: If -PassThru is specified,the resulting PvsConnection object is returned.

SwitchParameter Confirm: The impact of thisoperation is "low". If -Confirm is specified, the operation will beconfirmed. $ConfirmPreference can be set to "low" to haveconfirmation without the Confirm parameter.

EXAMPLE 1: Set PvsConnection for Individual Fields

Get the PvsConnection into a $o variable. Change the$o field values and then Set the PvsConnection with the result.

$o = Get-PvsConnection -Fields Port

$o.Port = 54322

Set-PvsConnection $o

The -Fields parameter with only the needed fieldsspecified makes the Get work faster because only those fields are retrieved.

EXAMPLE 2: Set PvsConnection for a Field Using Pipe

Get the PvsConnection into a $o variable for thefield that has the wrong value. Change the $o field to the correct value and thenSet the PvsConnection with the result.

The -Fields parameter with only the needed fieldsspecified makes the Get work faster because only those fields are retrieved.

The "foreach { $o = $_; $o.X = Y; $o }"sets the field X to value Y and returns the object again so it can be piped tothe Set command for update.

EXAMPLE 3: Set PvsConnection Port with Parameter

Set the PvsConnection Port using the Port parameterinstead of a PvsConnection object.

Set-PvsConnection -Port 54322

This is the only Set command that has fieldparameters.

Command Specific Help

All of the documentation for specific commands is includedin the command-line help by calling Get-Help and the name of the command, forexample “Get-Help Get-PvsDevice”. The documentation for the specific commandincludes information about the object that is may get or set. The documentationof all of the objects is included in the “Objects, in the Citrix.PVS.SnapInNamespace” section.

Error Handling

For the Citrix.PVS.SnapIn, if an error occurs, aPvsException will be in the Exception member of the $error. The “Error codes”information is included in this document.

The members of a PvsException are:

InnerException:The exception that occured. This exception maybe an EAException or otherstandard Exception.

ToString():Has the formatted full Message of the InnerException.

If theInnerException GetType().Name equals "EAException", then The membersof it are:

returnCode: The number, as shown below in the Error codes. The name of theerror, for example "NotImplemented", is not included in theEAException.

Message: The message, as shown below in the Error codes. The [v1], [v2], [v3],[v4], and [v5] will be replaced with values as required.

Details: Has the Details for the EAException if there are any. OtherException,ManagementInterfaceError and PvsStatusException will have Details.

ToString(): Has the Message as shown below in the Error codes. If there isDetails, it will be returned or included, and if partialReturn, they will beincluded.

partialReturn: Might have a list of EAException objects if any of the itemsprocessed during the command had any issues.

Severity: Can have the values Critical, Error, Warning or Duplicate.

Source: Has the value that is displayed in the Console as a Title or Type forthe error.