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.
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.
Finally, your project must include the System.Web.Services service reference to make SOAP calls from your imported code.
You may now use SoftLayer's API objects as local objects in your project.
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()
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
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
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
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())
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()
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()
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
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.
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.
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.