Using ServerIron ADX XML API with Microsoft Visual Studio 2008
Part 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_123
00_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.
HTTP/XML/SOAP
Web Services
exposed by
XML/SOAP API
Client App
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).
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-service
ServerIron 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 brocade
ServerIron ADX1000(config)#aaa authentication web-server default local
ServerIron 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 1
ServerIron ADX1000(config-if-mgmt-1)#ip address 187.63.136.18 255.255.255.0
ServerIron 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 manually
Private m_HeaderName As String
Private 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 manually
Protected Overrides Function GetWebRequest(ByVal uri As Uri) As Net.WebRequest
'call the base class to get the underlying WebRequest object
Dim 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 caller
Return DirectCast(req, Net.WebRequest)
End Function
'this function was added manually
Public Sub SetRequestHeader(ByVal headerName As String, ByVal headerValue As String)
Me.m_HeaderName = headerName
Me.m_HeaderValue = headerValue
End 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.Text
Public 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 Sub
End 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.