Nitro C# APIs for NetScaler – Scripting with PowerShell

Hello again! It’s been a while, I know, but I’m back with some fresh goodness that I hope you will¬†enjoy. I want to give a quick shout out to Thomas Poppelgaard for encouraging me¬†to share some new content, and in return I promised him that I’ll dust off SiteDiag in the near future ūüôā Since my last post I joined a financial services firm where I’ve been working on a global¬†NetScaler deployment, so I’ve got lots of great insights about NetScaler and Command Center that I wanted to share.

During my involvement on the engineering side of a larger NetScaler deployment I came across several situations that warranted scripts for both NetScaler and Command Center. The primary driver behind these scripts was the automation of configuration deployment and management (comparing and setting configurations against lists of NetScalers). This post aims to cover the basics of using the C# Nitro APIs in PowerShell. I also hope to share similar tips on the Command Center APIs in a future post.

So, to get started scripting¬†you’ll need to download and extract the Nitro API SDK for C# to the host where you plan to run the script. The download is hosted on the NetScaler itself under the ‘Downloads’ section (on the far right in 10.5):

NetScaler API SDK Downloads

NetScaler API SDK Downloads

Once you’ve extracted everything out you’ll have two DLLs that will need to be loaded into your PowerShell environment,¬†newtonsoft.json.dll and nitro.dll. To ‘include’ these runtime libraries in your script, simply use the Add-Type cmdlet for each:

Add-Type -Path .\newtonsoft.json.dll
Add-Type -Path .\nitro.dll

Now that the runtime libraries are included you can directly call the Nitro objects using the com.citrix.netscaler.nitro namespace:

com.citrix.netscaler.nitro Namespace


The next step is to connect to the NetScaler by creating com.citrix.netscaler.nitro.service.nitro_service object and calling the login() method, which looks like this in PowerShell:

$Credentials = Get-Credential #prompt for credentials
$nitrosession = New-Object com.citrix.netscaler.nitro.service.nitro_service("netscaler.fqdn",'HTTPS') 
$nitrosession.login($Credentials.GetNetworkCredential().UserName, $Credentials.GetNetworkCredential().Password)

And this is where the ‘fun’ starts. Referencing the Nitro API Documentation, you can explore all of the classes and methods that are now at your disposal, including every imaginable configuration and statistic.

Let’s take an example of checking¬†the¬†status of modes, which is handled by the com.citrix.netscaler.nitro.resource.config.ns.nsmode class:



Say you wanted to get all of the modes that are currently set on a NetScaler, you’d simply call the get() method, passing the $nitrosession object as the only argument:


mode : {FR, L3, MBF, Edge...}
fr : True
l2 : False
usip : False
cka : False
tcpb : False
mbf : True
edge : True
usnip : True
l3 : True
pmtud : True
sradv : False
dradv : False
iradv : False
sradv6 : False
dradv6 : False
bridgebpdus : False

This command uses the nitro_service object as the connection reference for the nsmode.get() method, pretty straightforward.

Now, say you wanted to change one of the modes, L2 in this example, and this is where it can get a little tricky.¬†First, you’ll need to store nsmode in a PowerShell object using the same get() method above:

$nsmode = [com.citrix.netscaler.nitro.resource.config.ns.nsmode]::get($nitrosession)

Then you’ll need to build an array of modes that you want to enable, including any that are already enabled, to pass to the enable() method (there’s probably an easier way to do this than the below snippet, but hey, it works!):

$modes = @(); foreach ($mode in $nsmode.mode){$modes += $mode}; $modes += "L2"

This will¬†give you an array ($modes) that contains all of the modes that you want to enable, plus the modes that were already enabled. You’ll then need to use the nsmode.set_mode() method to set the¬†modes that should be passed to the enable() method:


And the moment of truth, passing the modified $nsmode object to the enable() method:

[com.citrix.netscaler.nitro.resource.config.ns.nsmode]::enable($nitrosession, $nsmode)
errorcode  message sessionid severity 
---------  ------- --------- -------- 
0         Done              NONE

Let’s explore another¬†example that involves a rewrite policy and action set, which¬†can quickly become a web of interconnecting¬†classes¬†and methods.

First, let’s put¬†all of the¬†rewrite policies into an object:

$rewritepolicies = [com.citrix.netscaler.nitro.resource.config.rewrite.rewritepolicy]::get($nitrosession)

Which will give you a collection of rewrite policy objects in the following format:

__count : 
name : ns_cvpn_sp_js_vgp_pol
rule : http.req.url.path.endswith("ViewGroupPermissions.aspx") && http.req.method.eq(POST) && http.res.body(10).contains("0|/")
action : ns_cvpn_sp_ct_rw_act
undefaction : 
comment : 
logaction : 
newname : 
hits : 0
undefhits : 0
description : 
isdefault : True
builtin :

From here, you can call other methods for the rewrite class by referencing the object that you’re interested in. For example, to get a list of bindings for¬†ns_cvpn_default_bypass_url_pol, which is the first policy returned on a NetScaler, you would reference $rewritepolicies[0].name when using the rewritepolicy_binding.get() method:

[com.citrix.netscaler.nitro.resource.config.rewrite.rewritepolicy_binding]::get($nitrosession, $rewritepolicies[0].name)

Similarly, you can get a rewrite action by referencing the rewrite policy’s action property:


I’ll stop here for the sake of time and complexity, as there are so many ways that you can go with this foundation. I highly recommend using a tool like PowerGUI so that you can see the classes as you type, and explore the various objects and methods at your disposal.

Anyways, I hope this all makes enough sense for someone to start scripting for NetScalers in PowerShell, and will try to post a similar article on the Command Center APIs soon.

XenApp PowerShell Scripting with Get-XASession

I was working on a PowerShell script in XenApp today to quickly view active sessions by user, server, application, and session duration. Having focused most of my PoSH time in recent years to the XenDesktop SDK, I was somewhat disappointed with the limited flexibility (and official documentation) of the XenApp SDK, specifically with the Get-XASession cmdlet.

My main complaint is that Get-XASession doesn’t have many ‘Required’ parameters, which means that queries are limited to a subset of session details:


For example, if I want to find all sessions that are ‘Active’, I have to pipe the results of Get-XASession and evaluate each returned object. So, the following pipeline evaluation is required if you wanted to see all active sessions:

Get-XASession | Where-Object { $_.State -match 'Active'}

Using this as a foundation to find Active sessions, I took it a step further by using an input parameter (application name) to list sessions by application, and then formatted the output of the session details to get me what I’m looking for:

param ([String]$app)
foreach ($session in (Get-XASession | Where-Object { 
$_.BrowserName -match $app -and $_.State -match 'Active'} | 
select AccountName, ServerName, LogonTime, ConnectTime, CurrentTime, SessionID | 
Sort-Object LogonTime -Descending))
 $logon = (Get-Date) - $session.LogOnTime
 $connect = (Get-Date) - $session.ConnectTime
 "$($session.AccountName) logged on to $($session.ServerName) {0:00}:{1:00}:{2:00}" 
 -f $logon.Hours,$logon.Minutes,$logon.Seconds + " ago."

This script returns a active sessions by user name, connected to $app, the server on which it’s running, and the elapsed time (in ascending order) since they logged on (just subtract the $_.LogonTime date/time object from Get-Date). Notice how the $session object is compiled of properties of the sorted Get-XASession output by way of piping the output through several filters, which lets you create your own objects that can be easily manipulated and cross-referenced in the script. I also did some date/time formatting with {0:00}:{1:00}:{2:00}” -f $logon.Hours,$logon.Minutes,$logon.Seconds, though you can present this time duration in any way that makes sense.

Well, I hope this was worth a quick read, have a good weekend!

XenDesktop 7 Service Instances – What’s New?

Since XenDesktop 7 was built using the same service framework architecture as XenDesktop 5¬†(aka the ‘FlexCast Management Architecture’), the additional functionality introduced in XD7 was added as services, each with multiple service instances. These services are handled much in the same way as XenDesktop 5, and XenDesktop 7 sites use version 2 of the Citrix.Broker.Admin PowerShell SDK to return information on registered service instances using the cmdlets of the same name as XD5 (Get-ConfigRegisteredServiceInstance, Register-ConfigServiceInstance, etc.).

In XenDesktop 5, each DDC in a site has 5 services, with 12 total service instances that correspond to the various WCF endpoints used by each service. If the DDC is also running the Citrix License Server, there would be a total of 13 instances. For this reason, it’s a fairly straightforward process to find and register missing service instances.

XenDesktop 7 is quite different in this regard. Since it has optional FMA services, such as StoreFront, the number of service instances in any given site depends on which components are installed, and whether or not SSL-is in use.

For example, my single-DDC site running StoreFront 2.0 with SSL encryption has 10 services with 43 total service instances:

XenDesktop 7 Services

If StoreFront wasn’t installed, for example, there would be at least three less services (some of the Broker services would likely not be registered). There are also duplicate service instances for SSL encrypted services, such as the virtual STA service. Here’s a quick PoSH script to tell you what service instances are registered in your site (for XD5 & XD7):

asnp citrix.Broker*
Get-ConfigRegisteredServiceInstance -AdminAddress na-xd-01 | %{ 
"ServiceType: " + $_.ServiceType + " Address: " + $_.Address; $count++}
"Total Instances: " + $count

You could take this a step further to see how many instances are in each of the 10 possible service types:

New-Alias grsi Get-ConfigRegisteredserviceInstance
 $acct = grsi -AdminAddress na-xd-01 -serviceType Acct; "$($acct.Count) ADIdentity service instances"
 $admin = grsi -serviceType Admin ; "$($admin.count) Delegated Admin service instances"
 $broker = grsi -serviceType Broker; "$($broker.count) Broker service instances"
 $config = grsi -serviceType Config; "$($config.count) Configuration service instances"
 $envtest = grsi -serviceType EnvTest; "$($envtest.count) Environment Test service instances"
 $hyp = grsi -serviceType Hyp; "$($hyp.count) Hosting Unit service instances"
 $log = grsi -serviceType Log; "$($log.count) Configuration Logging service instances"
 $monitor = grsi -serviceType Monitor; "$($monitor.count) Monitor service instances"
 $prov = grsi -serviceType Prov; "$($prov.count) Machine Creation service instances"
 $sf = grsi -serviceType Sf; "$($sf.count) StoreFront service instances"
 "$($acct.Count + $admin.Count + $broker.Count + $config.Count + $envtest.Count + $hyp.Count + $log.Count + $monitor.Count + $prov.Count + $sf.Count) Total service instances"
XenDesktop 7 Service Instance Count

XenDesktop 7 Service Instance Count

Because of this nuance, I’m working on a more intelligent way of enumerating and validating service instance registrations in SiteDiag for XD7. Hopefully these scripts are helpful in illustrating the difference between XD5 & XD7. Also, here’s the latest nightly build of SiteDiag that has the beginnings of the additional logic needed to properly count, and fix, registered service instances in a XenDesktop 7 site.

XML Broker Health Check

I saw an interesting question in the Citrix support forum today, and thought I’d share. Scott Curtsinger asked the following:

Does anyone know what the easiest way is to check the health of the XML service on XenDesktop¬†5.6? I’m seeing a lot of information on the web for XenApp but not very much for XenDesktop¬†beyond leveraging¬†devices like a NetScaler.

My first instinct is that this could easily be done via PowerShell, so I did a quick search and found this blog post by Jason Pettys. I also found this great article on working with the Citrix XML service, and quickly put together the following script which I tested against my XenDesktop 5.6 XML broker:

$url = "http://localhost/scripts/wpnbr.dll"
$parameters = '<?xml version="1.0" encoding="utf-8"?><!DOCTYPE NFuseProtocol SYSTEM "NFuse.dtd"><NFuseProtocol version="5.1"><RequestCapabilities></RequestCapabilities></NFuseProtocol>'
$http_request = New-Object -ComObject Msxml2.XMLHTTP
$'POST', $url, $false)
$http_request.setRequestHeader("Content-type", "text/xml")
$http_request.setRequestHeader("Content-length", $parameters.Length)
$http_request.setRequestHeader("Connection", "close")

Running this script in PowerShell on my XML broker returned the following list of capabilities, which is a good indication that the XML broker is up and running:

<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE NFuseProtocol SYSTEM "NFuse.dtd"> <NFuseProtocol version="5.1"> <ResponseCapabilities> <CapabilityId>separate-credentials-validation</CapabilityId> <CapabilityId>multi-image-icons</CapabilityId> <CapabilityId>launch-reference</CapabilityId> <CapabilityId>user-identity</CapabilityId> <CapabilityId>full-icon-data</CapabilityId> <CapabilityId>full-icon-hash</CapabilityId> <CapabilityId>accepts-client-identity-for-power-off</CapabilityId> <CapabilityId>session-sharing</CapabilityId> </ResponseCapabilities> </NFuseProtocol>

This simple script lays a nice foundation to perform XML broker health checks via PoSH. I then took the script a little bit further to test some other XML requests:

param($server, $port)
if ($port){$port = 80}
$creds = Get-Credential
$domainuser= $creds.UserName.Split('\')
$domain = $domainuser[0]
$user = $domainuser[1]
[String]$pw = [Runtime.InteropServices.Marshal]::PtrToStringAuto([Runtime.InteropServices.Marshal]::SecureStringToBSTR($creds.Password))
$nwINFO = Get-WmiObject -ComputerName $env:COMPUTERNAME Win32_NetworkAdapterConfiguration | Where-Object { $_.IPAddress -ne $null }
$ip = $nwINFO.IPAddress
$fqdn = $nwINFO.DNSHostName
$xmlcreds = '<Credentials><UserName>' + $user + '</UserName><Password encoding="cleartext">' + $pw + '</Password><Domain Type="NT">' + $domain + '</Domain></Credentials>'
$envelope = '<?xml version="1.0" encoding="utf-8"?><!DOCTYPE NFuseProtocol SYSTEM "NFuse.dtd"><NFuseProtocol version="5.1">'
$clienttype = '<ClientType>ica30</ClientType>'
$clientdetails = '<ClientName>' + $env:COMPUTERNAME + '</ClientName><ClientAddress addresstype="dot">' + $ip[0] + '</ClientAddress>'
function request ($parameters)
 $http_request = New-Object -ComObject Msxml2.XMLHTTP
 $'POST', $url, $false)
 $http_request.setRequestHeader("Content-type", "text/xml")
 $http_request.setRequestHeader("Content-length", $parameters.Length)
 $http_request.setRequestHeader("Connection", "close")
$url = "http://" + $server + ":" + $port + "/scripts/wpnbr.dll"
$capabilities = request ($envelope + '<RequestCapabilities></RequestCapabilities></NFuseProtocol>')
if (!$capabilities[1].contains('error'))
 $testcreds = request ($envelope + '<RequestValidateCredentials>' + $xmlcreds + '</RequestValidateCredentials></NFuseProtocol>')
 if (!$testcreds[1].contains('bad'))
 $appdatareq = request ($envelope + '<RequestAppData><Scope traverse="subtree"></Scope><DesiredDetails>rade-offline-mode</DesiredDetails><ServerType>all</ServerType>' + $clienttype + '<ClientType>content</ClientType>' + $xmlcreds + $clientdetails + '</RequestAppData></NFuseProtocol>')
 $app = $appdatareq[1] -split "<FName>"
 $app = $app[1] -split "</FName>"
 $launchreq = request ($envelope + '<RequestAddress><Name><AppName>' + $app[0] + '</AppName></Name>' + $clientdetails + '<ServerAddress addresstype="dns-port"></ServerAddress>' + $xmlcreds + $clienttype + '</RequestAddress></NFuseProtocol>')

This script takes the server and port, prompts for the credentials that you’re testing (password is sent in clear text), and sends a RequestCapabilities request, followed by RequestValidateCredentials, RequestAppData, and RequestAddress requests. To avoid dependencies on NFuse.dtd, I used a -split on the XML results of the RequestAppData results to get the ‘friendly name’ of the first application returned by RequestAppData, which I used for the RequestAddress post.

From here I’m going to develop a C# service that can monitor the XML service, though I’d like to figure out how to encode the password into the ‘ctx1’ format so that I’m not sending it in clear text.