Using ServerIron ADX XML API with Microsoft Visual Studio 2008Part 1 – Environment Setup, Proxy-class creation and authentication

This document explains how to setup MS Visual Studio 2008 to consume web services provided by the ServerIron ADX XML API. Although this document was written using screen captures and VB code that was captured from MS Visual Studio 2008, which is paid software, the reader can also use Microsoft Visual Basic 2008 Express Edition, which is free sotfware, to create and run the sample app described in this document. MS Visual Basic 2008 Express Edition can be downloaded at :http://www.microsoft.com/express/Downloads/#2008-Visual-Basic

Only the ServerIron ADX family (ServerIron ADX 1000, ServerIron ADX 4000 and ServerIron ADX 10000) has support for the XML/SOAP API, starting with code 12.3.00. The complete documentation for the XML API can be found at:http://www.brocade.com/downloads/documents/product_manuals/B_ServerIron/ServerIronADX_12300_XML_API_ProgrammersGuide.pdf

XML/SOAP Overview

SOAP (Simple Object Access Protocol) is a simple XML-based protocol to let applications exchange information over HTTP. SOAP provides a way to communicate between applications running on different operating systems, using different technologies and programming languages. One application will run what is called “Web Services”. A client application will “consume” the web services provided by the server. In our case the ServerIron ADX is where the Web Services will run. Using Windows Forms and Visual Basic we will build a sample application that will use HTTP to exchange SOAP/XML messages with the ServerIron.

Figure 1 – HTTP/XML/SOAP message exchange

The API is described in files that follow a standard named Web Service Definition Language (WSDL). There are two WSDL files included with the ServerIron API: sys_service.wsdl: contains methods use to access system information in the ServerIron ADX (chassis type and components, CPU, DRAM and flash memory, temperature, configuration file, DNS server address, etc).

Web Servicesexposed by

XML/SOAP APIClient App

HTTP/XML/SOAP

slb_service.wsdl: contain methods to create real server and virtual servers and to gather traffic statistics.The wsdl files can be downloaded along with the ServerIron ADX code at http://my.brocade.com,or they can be accessed directly from a ServerIron ADX that is already running code 12.3.00. More on this later.Before any application can use the Web Services in the ServerIron ADX, it has to create a proxy-class, client stub or DLL, that represents all the API methods and objects that exist in the ServerIron. The Brocade documentation that comes with the API gives information on how to create that using Perl, Java, C# and C++. This document will show you how to create a proxy-class using the MS Visual Studio environment.

.ServerIron ADX setup

The ServerIron ADX must run code 12.3.00 or later (switch code or router code). The XML/SOAP API is not enabled by default. To enable it use the following commands:

ServerIron ADX1000(config)#web-management soap-serviceServerIron ADX1000(config)#write mem

All messages that are sent to the API must be authenticated. In order to do so, we need to create an user account/password pair in the ServerIron. The same credentials will be used by the client app when sending requests to the ServerIron ADX. We will use the credentials “admin/brocade” throughout this document. To create the credentials in the ServerIron ADX use the following commands:

ServerIron ADX1000(config)#username admin privilege 0 password brocadeServerIron ADX1000(config)#aaa authentication web-server default localServerIron ADX1000(config)#write mem

Obviously we need to configure an ip address in the ServerIron ADX to start with. We will use 187.63.136.18 in our examples. To configure an ip address in the ServerIron ADX use the following commands:

ServerIron ADX1000(config)#int ma 1ServerIron ADX1000(config-if-mgmt-1)#ip address 187.63.136.18 255.255.255.0ServerIron ADX1000(config)#write mem

Creating a Windows Form Project

All examples in this document will use .NET Framework 2.0 or later and Visual Basic as a programming language. The workstation running Visual Studio must be able to access the ip address configured in the ServerIron ADX. Start up MS Visual Studio 2008 and create a new VB project (File, New, Project). Under Project Types select Visual Basic, Windows and then Windows Forms Application.

Figure 2 – Creating a new Windows Form project

Type in the name API Demo and click Enter. The project API Demo will be created and you should be able to see a screen similar to the following:

Figure 3 – API Demo project

Now let´s create the proxy class for the Windows application. At the Solution Explorer pane, right click on API Demo then select Add Web Reference.

Note: If you are running MS Visual Basic 2008 Express Edition, it will default to .NET 3.5 and because of that the Add Web Reference option does not show. In order to use add the Web Reference, right click on the API Demo project, then click on Add Service Reference. In the bottom left of the Add Service Reference window click on Advanced. Then again in the bottom left of the window, click on Add Web Reference.

At the URL field type http://187.63.136.18/wsdl/sys_service.wsdl and click on Go. Visual Studio will now contact the ServerIron, read the wsdl file, and show all methods that are available in the sys_service API. You should see a screen just like Figure 4.

Figure 4 – Adding a Web Reference

Now type in Adcsysinfo at the Web reference name field and click on Add Reference to add the class to the windows form application. You should see the following results at the Solution Explorer pane:

Figure 5 – Solution Explorer show the Adcsysinfo web reference

Now let´s expand to Adcsysinfo container to see what is inside. At the Solution Explorer pane, click on the Show All Files icon, then click on Adcsysinfo, then Reference.map. All the files that you see were automatically created when the Visual Studio added the web reference based on the wsdl file.

Figure 6 – Expanded view of Adcsysinfo

We are done with creating the proxy class.We still need to do one thing before we start working on the actual application: create methods to authenticate the http requests.

New methods to authenticate the HTTP requests

Neither the API nor Visual Studio contain easy to use code to add authentication headers to the http request. So we need to create our own authentication method. At the Solution Explorer pane, if the Adcsysinfo container is not yet expanded, click on Adcsysinfo, then Reference.map. Double click on the Reference.vb file.Under the Partial Public Class Adcsysinfo section add the following code right after the many Private variable declarations that you see:

'added manuallyPrivate m_HeaderName As StringPrivate m_HeaderValue As String

Then, right after the end of the Public Sub New() ….. End Sub method, add the following new methods:

'this function was added manuallyProtected Overrides Function GetWebRequest(ByVal uri As Uri) As Net.WebRequest'call the base class to get the underlying WebRequest objectDim req As Net.HttpWebRequest = DirectCast(MyBase.GetWebRequest(uri), Net.HttpWebRequest) If Me.m_HeaderName IsNot Nothing Then 'set the header req.Headers.Add(Me.m_HeaderName, Me.m_HeaderValue) End If'return the WebRequest to the callerReturn DirectCast(req, Net.WebRequest)End Function

'this function was added manuallyPublic Sub SetRequestHeader(ByVal headerName As String, ByVal headerValue As String) Me.m_HeaderName = headerName Me.m_HeaderValue = headerValueEnd Sub

Click on the Save All icon to save all changes. The results should look like below:

Figure 7 – Reference.vb listing

Building the Application

Let´s start by adding two controls to the Form1 form. Click on the Form1.vb [Design] tab to go back to the Form1 form. Open up the Toolbox pane, and select and drag one Button control and one Textbox control to inside the form. Using the Properties pane, change the Text property of the Button1 control to “Get Version”. You can resize and reposition the controls if you wish. That should result in the following screen:

Figure 8 – Form1 form with controls

Now double-click on the Get Version button you just created. This will take you to the code-behind visual basic window where we will add code to the application. Here is all the code that is required to implement a very simple “Get Version” function. Copy and paste all the code below to the Form1.vb document.

Imports System.TextPublic Class Form1 Dim ADXSYS As New Adcsysinfo.AdcSysInfo

Private Sub Button1_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles Button1.Click Call Authenticate() TextBox1.Text = ADXSYS.getVersion() End Sub

Private Sub Authenticate() 'form the URL to access the ADX. The sys_service API always resides at /WS/SYS ADXSYS.Url = "http://187.63.136.18/WS/SYS" 'add the authentication header ADXSYS.SetRequestHeader("Authorization", "Basic " + Convert.ToBase64String(New ASCIIEncoding().GetBytes("admin" + ":" + "brocade"))) 'cache the credentials for future http requests ADXSYS.PreAuthenticate = True End SubEnd Class

Click the Save All icon to save everything. We are done and the application can now run. Click on the Start icon (should be a green triangle) or press the F5 key to run the application. The app should compile without problems, and the windows form will show presenting the button and textbox control. Click on the “Get Version” button to retrieve the software version that is running in the ServerIron ADX. If all is fine the results should be:

Figure 9 – Running the application

Packet Capture and ServerIron ADX log

The following screen shows the packet capture between the application and the ServerIron.

Figure 10 – Authentication header gets sent along with http request

Figure 11 – getVersion method gets sent as a SOAP envelope

Figure 12 – getVersion response

Figure 13 – show log listing in the ServerIron ADX after running the application just once.

This is the end of Part 1. Part 2 will cover many other methods and objects inside the sys_service API.