Citrix has offered Nitro API support for Citrix ADC for many years, and you can find a lot of great resources online that cover how to use Nitro APIs to control Citrix ADCs the REST API way.
But what about the average IT guy without much web development experience (like me)? It can be tough. I spent a little bit of time playing with it and wanted to share this blog post to provide some easy-to-follow steps that will help any infrastructure admin (with some experience in C#) automate the configuration of Citrix ADC and implement customized tools with complex logic flows.
Part 1: Set Up Your Environment
First, read the online documentation before you get started. Then, go to the web console of your Citrix ADC, where you’ll find the download link to the C# SDK on the Downloads page, as shown below.
You can also download the SDK from your Citrix ADC from the following folder, via a tool such as WinSCP:
./var/netscaler/gui/nitro-csharp.tgz
Download the file and extract it. Guess what’s in the nitro-csharp.tgz file? Another ns_nitro-csharp_<codename>_XX_XX.tar file! Extract that file again. You will get the C# SDK folder, as shown below.
Start your adventure with the readme_start.txt file, which will explain the folder structure. In the doc folder, you will find a help file that contains the API reference. You need to have (at least) .NET 3.5 installed on your machine to use Csharp SDK.
Please note, you will need to reference two DLLs in the lib folder (Nitro.dll and Newtonsoft.Json.dll) to build the sample code. A build command will look something like this:
csc /r:../lib/nitro.dll;../lib/Newtonsoft.Json.dll MyFirstNitroApplication.cs
If you have access to and are familiar with Microsoft Visual Studio, you can also reference those two DLLs from menu Project → Add Reference → Browse.
If you can successfully build the sample code into an .exe file, your are good to move forward.
Part 2: Your First Nitro Application in C#
Open MyFirstNitroApplication.cs to go through the very first sample code. At the start of the program, it creates a new instance of itself and tries to read three parameters.
MyFirstNitroApplication config = new MyFirstNitroApplication();
config.ip = args[0];
config.username = args[1];
config.password = args[2];After the build, the usage will look as follows:
MyFirstNitroApplication.exe <NS_IP> <username> <password>
Then, followed by a big try catch from line 45 to 88, it begins the configuration. Let’s take a segment out and have a closer look:
//Create an instance of the virtual server class
lbvserver new_lbvserver_obj = new lbvserver();
//Create a new virtual server
new_lbvserver_obj.name = "MyFirstLbVServer";
new_lbvserver_obj.ipv46 = "10.102.29.88";
new_lbvserver_obj.servicetype = "HTTP";
new_lbvserver_obj.port = 80;
new_lbvserver_obj.lbmethod = "ROUNDROBIN";
lbvserver.add(ns_session,new_lbvserver_obj);The code will typically start with a new object based on a certain object class. In this case, it is an lbvserver type of object. You might need to initialize some of the properties before you call the add method to create the real vServer. As shown in the example above, it will initialize the attributes needed for a load balancing vServer object and then call the lbvserver.add() method to create the object in the session we created using the NSIP and login credential. Proper error handling is always recommended.
You can find examples of how to create objects and change configurations in the Sample folder. Use the structure of the very first program and rewrite everything between line 53 and 75 with your own code.
Here, I’ve created a real-world example of how to use Nitro API in C# to find out unbound/orphan objects in a production Citrix ADC instance. Enjoy coding!
Wrapping Up
Thanks for reading, and I hope this help you get ready to use Nitro APIs in C# for Citrix ADC automations. Automation using a language you know, like C# in my case, is really useful when managing a Citrix ADC! As always, if you’re looking for assistance implementing any of the code in this blog, contact our Citrix Consulting team.
DISCLAIMER:
This sample code is provided to you “as is” with no representations, warranties or conditions of any kind. You may use and distribute it at your own risk. CITRIX DISCLAIMS ALL WARRANTIES WHATSOEVER, EXPRESS, IMPLIED, WRITTEN, ORAL OR STATUTORY, INCLUDING WITHOUT LIMITATION WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, TITLE AND NONINFRINGEMENT. Without limiting the generality of the foregoing, you acknowledge and agree that (a) the software application may exhibit errors, design flaws or other problems, possibly resulting in loss of data or damage to property; (b) it may not be possible to make the software application fully functional; and (c) Citrix may, without notice or liability to you, cease to make available the current version and/or any future versions of the software application. In no event should the code be used to support of ultra-hazardous activities, including but not limited to life support or blasting activities. NEITHER CITRIX NOR ITS AFFILIATES OR AGENTS WILL BE LIABLE, UNDER BREACH OF CONTRACT OR ANY OTHER THEORY OF LIABILITY, FOR ANY DAMAGES WHATSOEVER ARISING FROM USE OF THE SOFTWARE APPLICATION, INCLUDING WITHOUT LIMITATION DIRECT, SPECIAL, INCIDENTAL, PUNITIVE, CONSEQUENTIAL OR OTHER DAMAGES, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. You agree to indemnify and defend Citrix against any and all claims arising from your use, modification or distribution of the code.
