June 20, 2011

Tags article sldn

Visual Basic .NET

Visual Basic .NET

Consuming SOAP WSDLs

There are two ways to import SoftLayer's API WSDLs into your project. Visual Studio can consume a SOAP service into a web reference accessible by your project. Visual Studio also comes with a utility called wsdl.exe that is executed from a command prompt to read one or more WSDL files and directly convert them into source code that you can add to your project. Web services are typically easier to use in Visual Studio, but can become cumbersome if your project uses many SoftLayer API services. Wsdl.exe is useful if your project requires many API services.

The code samples in this article reflect code generated from SoftLayer API services by wsdl.exe.

Creating Web References

  1. Click the Project menu in Visual Studio.
  2. Select Add Service Reference from the Project menu dropdown box.
  3. Click the Advanced button in the Add Service Reference window.
    Note: The Service Reference Settings window will appear.
  4. Click the Add Web Reference button in the Service Reference Settings window.
  5. Enter the URL to the WSDL of the SoftLayer API service you wish to use in the URL field.
  6. Click the green arrow to the right of the URL field.
    Note: Visual Studio will download the WSDL file and analyze the methods and data types it contains.
  7. Enter a name for your new web reference in the Web reference name field.
    Note: Any reference to the API service added to the project will be referenced by this name.
  8. Click the Add Reference button to import your new web service.
    Note: You will now be returned to your project and your new API service will be visible in Visual Studio’s Solution Explorer.

Using Wsdl.exe

Wsdl.exe is located in C:\Program Files\Microsoft SDKs\Windows\v7.0A\bin\ and should be executed with the following switches to convert SoftLayer's API WSDLs into Visual Basic code:

  • /language:VB - Tell wsdl.exe to export Visual Basic .NET code.
  • /sharetypes - SoftLayer's WSDL files share a number of similar data types. The /sharetypes switch compiles these data types into single class files, making for a smaller source footprint and more efficiency when working in Visual Studio.
  • /out:C:\path\to\project\SoftLayer_API.vb - Export generated code to a path within your project hierarchy. In this case we'll save code to the fileSoftLayer_API.vb.

End the command with a space-separated list of the URLs of the API WSDLS you wish to import. You can import as many WSDL files as you like.

wsdl.exe /language:VB /out:"C:\Path\to\Project\SoftLayer_API.vb" /sharetypes 
https://api.softlayer.com/soap/v3/SoftLayer_Account?wsdl 
https://api.softlayer.com/soap/v3/SoftLayer_Hardware_Server?wsdl 
https://api.softlayer.com/soap/v3/SoftLayer_Dns_Domain?wsdl

Note: To make private API calls, replace https://api.softlayer.com
with http://api.service.softlayer.com. Refer to our Getting Started article for more information on making private API calls.

Re-run this command if you wish to import more API services into your project.

Once your code file is created you must add it to your project.

  1. Right click the name of your project in the Visual Studio Solution Explorer.
  2. Scroll over the Add option in the expanded menu.
  3. Click the Existing Item button in the Add menu.
  4. Locate your generated code file in the Add Existing Item dialog window.
  5. Click to highlight your generated code file.
  6. Click the OK button to continue.

Finally, your project must include the System.Web.Services service reference to make SOAP calls from your imported code.

  1. Click to expand the Project menu in Visual Studio.
  2. Select Add Reference.
  3. Click the .NET tab.
  4. Select System.Web.Services
  5. Click the OK button to add the reference to your project.

You may now use SoftLayer's API objects as local objects in your project.

Making API Calls

Creating Service Objects

Every API service in your project has an associated service class that is responsible for making API calls. Service classes are named according the API service you wish to call. For instance, the class name for the SoftLayer_Account API service is SoftLayer_AccountService and the service class name for the SoftLayer_Hardware_Serverservice is SoftLayer_Hardware_ServerService. Service objects have properties corresponding to API features such as authentication, initialization parameters, object masks, and result limits. API method calls are also made directly against these objects.

Dim accountService As SoftLayer_AccountService = New SoftLayer_AccountService()

Binding Authentication

Authenticate your API calls with your API username and key by defining an authenticate object. Set your authentication object's username and apiKey properties to your API username and key. Bind the authenticate object to your API service object by setting its authenticateValue property to your authentication object.

Dim username As String = "set me"
Dim apiKey As String = "set me"
 
Dim authenticate As authenticate = New authenticate()
authenticate.username = username
authenticate.apiKey = apiKey
 
accountService.authenticateValue = authenticate

Setting Initialization Parameters

API call initialization (init) parameters also have classes defined that correspond to the API service you are calling. Init parameter classes are named according to the API service you are calling. For instance, the init parameter class name for the SoftLayer_Account service is SoftLayer_AccountInitParameters and the init parameter class name for the SoftLayer_Hardware_Server service is SoftLayer_Hardware_ServerInitParameters. Init parameter objects each have a single integer type id property corresponding to the id number of the SoftLayer object you wish to query. Bind your init parameter object to your service object by setting it to your service object's InitParameterValue property, where corresponds to the API service you're calling.
If an API call doesn't correspond to a specific SoftLayer object, you do not need to bind an initialization parameter value to your service object.

Dim serverId As Integer = 1234
 
Dim hardwareServerInitParameters As SoftLayer_Hardware_ServerInitParameters = New SoftLayer_Hardware_ServerInitParameters()
hardwareServerInitParameters.id = serverId
hardwareServerService.SoftLayer_Hardware_ServerInitParametersValue = hardwareServerInitParameters

Making the API Call

Once your service object is ready, place your API method call directly against your service object. The example below outlines making the API call.

Dim username As String = "set me"
Dim apiKey As String = "set me"
 
Dim authenticate As authenticate = New authenticate()
authenticate.username = username
authenticate.apiKey = apiKey
 
' Initialize the SoftLayer_Account API service.
Dim accountService As SoftLayer_AccountService = New SoftLayer_AccountService()
accountService.authenticateValue = authenticate
 
Dim account as SoftLayer_Account = accountService.getObject()
 
 
' Work directly with the SoftLayer_Hardware_Server record with the 
' hardware id 1234.
Dim serverId As Integer = 1234
 
Dim hardwareServerService As SoftLayer_Hardware_ServerService = New SoftLayer_Hardware_ServerService()
hardwareServerService.authenticateValue = authenticate
 
Dim hardwareServerInitParameters As SoftLayer_Hardware_ServerInitParameters = New SoftLayer_Hardware_ServerInitParameters()
hardwareServerInitParameters.id = serverId
hardwareServerService.SoftLayer_Hardware_ServerInitParametersValue = hardwareServerInitParameters
 
Dim server as SoftLayer_Hardware_Server = hardwareServerService.getObject()

Code imported into your project defines classes for every data type defined in the SoftLayer API. Instantiate new data type objects as necessary as call parameters or call results.

Dim username As String = "set me"
Dim apiKey As String = "set me"
Dim domainId As Integer = 1234
 
Dim authenticate As authenticate = New authenticate()
authenticate.username = username
authenticate.apiKey = apiKey
 
Dim domainService As SoftLayer_Dns_DomainService = New SoftLayer_Dns_DomainService()
domainService.authenticateValue = authenticate
 
Dim domainInitParameters As SoftLayer_Dns_DomainInitParameters = New SoftLayer_Dns_DomainInitParameters()
domainInitParameters.id = domainId
domainService.SoftLayer_Dns_DomainInitParametersValue = domainInitParameters
 
' Create a new A record in a domain.
Dim newRecord As SoftLayer_Dns_Domain_ResourceRecord_AType = domainService.createARecord("myhost", "127.0.0.1", 86400)
Console.WriteLine("New A record id: " + newRecord.id.toString())
 
 
' Create a new domain record.
'
' This requires a null init parameter and a single SoftLayer_Dns_Domain
' object defined.
domainService.SoftLayer_Dns_DomainInitParametersValue = Nothing
 
Dim domain As SoftLayer_Dns_Domain = New SoftLayer_Dns_Domain()
Dim domainResourceRecords As SoftLayer_Dns_Domain_ResourceRecord_AType() = {New SoftLayer_Dns_Domain_ResourceRecord_AType()}
domainResourceRecords(0).host = "@"
domainResourceRecords(0).data = "127.0.0.1"
domainResourceRecords(0).type = "a"
domain.name = "example.org"
domain.resourceRecords = domainResourceRecords
 
Dim newDomain As SoftLayer_Dns_Domain = domainService.createObject(domain)
Console.WriteLine("New A record id: " + newDomain.id.toString())

Using Object Masks

Bind an Object mask to your API calls by first declaring an object mask object. Object mask class names correspond to the API service you're using, beginning with the name of your API service followed by "ObjectMask". For instance, an object mask for the SoftLayer_Account API service has the class name SoftLayer_AccountObjectMask and the SoftLayer_Hardware_Server service's corresponding object mask class name is SoftLayer_Hardware_ServerObjectMask.

Every object mask class has a mask property that models the relational data you wish to retrieve. The mask property is on object of the data type represented by your API service. For instance, SoftLayer_AccountObjectMask.mask is a SoftLayer_Account object and SoftLayer_Hardware_ServerObjectMask.mask is a SoftLayer_Hardware_Server object. Instantiate the relational properties you wish to retrieve in your object mask's mask property as new objects representing the data type of these properties. If your relational property is an array type then declare a one-item array containing a single objet representing the data type of the relational property you wish to retrieve.

Your API service object has a property corresponding to an optional object mask value. Object mask value property names correspond to the name of the API service you're using, beginning ith the name of your API service followed by "ObjectMaskValue". Bind your new object mask object to your service object by assigning it to your service object's ObjectMaskValue property. For instance, bind an object mask to a SoftLayer_Account service object by assigning its SoftLayer_AccountObjectMaskValueproperty to your object mask object.

This example retrieves an account's physical hardware records along with that hardware's operating system record, operating system passwords, network components, the datacenter the hardware is located in, and the number of processors in each hardware:

Dim username As String = "set me"
Dim apiKey As String = "set me"
 
Dim authenticate As authenticate = New authenticate()
authenticate.username = username
authenticate.apiKey = apiKey
 
Dim accountService As SoftLayer_AccountService = New SoftLayer_AccountService()
accountService.authenticateValue = authenticate
 
' Retrieve items related to hardware.
'
' Operating system, operating system passwords, all network components, the
' datacenter the server is located in, and the number of processors in each 
' server.
Dim objectMask As SoftLayer_AccountObjectMask = New SoftLayer_AccountObjectMask()
objectMask.mask = New SoftLayer_Account
 
Dim objectMaskHardware As SoftLayer_Hardware_Server() = {New SoftLayer_Hardware_Server()}
Dim objectMaskHardwareNetworkComponents As SoftLayer_Network_Component() = {New SoftLayer_Network_Component()}
Dim objectMaskHardwareOperatingSystemPasswords As SoftLayer_Software_Component_Password() = {New SoftLayer_Software_Component_Password()}
objectMaskHardware(0).operatingSystem = New SoftLayer_Software_Component_OperatingSystem()
objectMaskHardware(0).operatingSystem.passwords = objectMaskHardwareOperatingSystemPasswords
objectMaskHardware(0).networkComponents = objectMaskHardwareNetworkComponents
objectMaskHardware(0).datacenter = New SoftLayer_Location_Datacenter()
objectMaskHardware(0).processorCount = New UInteger
objectMaskHardware(0).processorCountSpecified = True
 
objectMask.mask.hardware = objectMaskHardware
accountService.SoftLayer_AccountObjectMaskValue = objectMask
 
Dim hardware As SoftLayer_Hardware_Server() = accountService.getHardware()

Using Result Limits

When calling data, especially queries that involve pulling snippets of information from larger groups, utilizing result limits will greatly decrease your wait time for the return.

Limit the number of results in your API call by creating a new resultLimit object and binding it to your API service object. ResultLimit has two properties:

  • limit: The number of results to limit your call.
  • offset: An optional offset to begin your result set.

Bind your new result limit to your API service object by setting your service object's resultLimitValue property to your result limit object.

Dim username As String = "set me"
Dim apiKey As String = "set me"
 
Dim authenticate As authenticate = New authenticate()
authenticate.username = username
authenticate.apiKey = apiKey
 
Dim accountService As SoftLayer_AccountService = New SoftLayer_AccountService()
accountService.authenticateValue = authenticate
 
' Retrieve our first two open support tickets
Dim resultLimit As resultLimit = New resultLimit()
resultLimit.limit = 2
resultLimit.offset = 0
 
accountService.resultLimitValue = resultLimit
 
Dim tickets As SoftLayer_Ticket() = accountService.getOpenTickets()

Error Handling

SoftLayer API call errors are sent to .NET's SOAP handler as exceptions. Place calls to the SoftLayer in Try/Catch blocks to ensure proper handling.

Dim username As String = "set me"
Dim apiKey As String = "an incorrect key"
 
Dim authenticate As authenticate = New authenticate()
authenticate.username = username
authenticate.apiKey = apiKey
 
Dim accountService As SoftLayer_AccountService = New SoftLayer_AccountService()
accountService.authenticateValue = authenticate
 
' Exit the script with the message:
' "Unable to retrieve account information: Invalid API key"
Try
    Dim account As SoftLayer_Account = accountService.getObject()
Catch ex As Exception
    Console.WriteLine("Unable to retrieve account information: " + ex.Message)
End Try

Caveats

Working with the SoftLayer API's generated code in Visual Studio may require one or two extra steps when creating or using SoftLayer API objects. These steps include setting “specified” properties and handling changes in API services.

Setting "Specified" Properties

Some object types in generated code have a "specified" property along with the object's property. If you're explicitly setting these properties, you must set their corresponding specified property to True. Use Visual Studio's IntelliSense to determine which properties have associated specified properties.

What to do When API Services Change

SoftLayer updates API WSDLs when new products and services are released. Re-consume these WSDLs in order to use these new features.
If the SoftLayer API is imported as a web reference in your project then right click on your web reference's name in Visual Studio's Solution Explorer and select "Update Web Reference". Visual Studio will take a few moments to re-import the web service, then the latest SoftLayer offerings will be available in your project.
If you used wsdl.exe to generate code files from SoftLayer's API WSDLs then re-run your full wsdl.exe command to re-import SoftLayer's latest API WSDLs into your project.

Referenced API Components

Services

Data Types

Methods