C Sharp

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

Creating web references is the first task required when consuming SOAP WSDLs. Follow the steps below to create a Web Reference in Visual Studio.

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 of your new web reference in the Web reference name field
   '''Note: Any references to the API service added to the project will be referenced by the project
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
   
   

This example creates a service reference called "com.softlayer.api", but you may create web services with any name you prefer. Your web references name is a namespace in your project. Utilize the using statement at the beginning of your program so you won't have to type the name of your web reference with every API-related statement you use. For instance, use the statement:

using projectName.com.softlayer.api;

Replace "projectName" with the name of your Visual Studio project, to set your web reference as a default namespace.

Using wsdl.exe

Wsdl.exe is located in C:\Program Files\Microsoft SDKs\Windows\v7.0A\bin. Execute Wsdl.exe with the following switches to convert SoftLayer's API WSDLs into C# code:

• /language:CS - Tells wsdl.exe to export C# 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.cs - Exports generated code to a path within your project hierarchy. In this case we'll save code to the fileSoftLayer_API.cs.

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:CS /out:"C:\Path\to\Project\SoftLayer_API.cs" /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. To add the newly created code file to your project, complete the steps below:

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

Making API Calls

Creating Service Objects

Every API service in your project has an associated service class that's 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_Server service 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. For example:
SoftLayer_AccountService 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.

String username = "set me";
String apiKey = "set me";
 
authenticate 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're 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 then you do not need to bind an initialization parameter value to your service object. The code snippet below outlines this scenario:

int serverId = 1234;
 
SoftLayer_Hardware_ServerInitParameters hardwareServerInitParameters = 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. Utilize the code below complete this action:

String username = "set me";
String apiKey = "set me";
 
authenticate authenticate = new authenticate();
authenticate.username = username;
authenticate.apiKey = apiKey;
 
// Initialize the SoftLayer_Account API service.
SoftLayer_AccountService accountService = new SoftLayer_AccountService();
accountService.authenticateValue = authenticate;
 
SoftLayer_Account account = accountService.getObject();
 
 
// Work directly with the SoftLayer_Hardware_Server record with the 
// hardware id 1234.
int serverId = 1234;
 
SoftLayer_Hardware_ServerService hardwareServerService = new SoftLayer_Hardware_ServerService();
 
SoftLayer_Hardware_ServerInitParameters hardwareServerInitParameters = new SoftLayer_Hardware_ServerInitParameters();
hardwareServerInitParameters.id = serverId;
hardwareServerService.SoftLayer_Hardware_ServerInitParametersValue = hardwareServerInitParameters;
 
SoftLayer_Hardware_Server 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.

String username = "set me";
String apiKey = "set me";
int domainId = 1234;
 
authenticate authenticate = new authenticate();
authenticate.username = username;
authenticate.apiKey = apiKey;
 
SoftLayer_Dns_DomainService domainService = new SoftLayer_Dns_DomainService();
domainService.authenticateValue = authenticate;
 
SoftLayer_Dns_DomainInitParameters domainInitParameters = new SoftLayer_Dns_DomainInitParameters();
domainInitParameters.id = domainId;
domainService.SoftLayer_Dns_DomainInitParametersValue = domainInitParameters;
 
// Create a new A record in a domain.
SoftLayer_Dns_Domain_ResourceRecord_AType newRecord = 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 = null;
 
SoftLayer_Dns_Domain domain = new SoftLayer_Dns_Domain();
SoftLayer_Dns_Domain_ResourceRecord_AType[] domainResourceRecords = new SoftLayer_Dns_Domain_ResourceRecord_AType[1];
domainResourceRecords[0].host = "@";
domainResourceRecords[0].data = "127.0.0.1";
domainResourceRecords[0].type = "a";
domain.name = "example.org";
domain.resourceRecords = domainResourceRecords;
 
SoftLayer_Dns_Domain newDomain = domainService.createObject(domain);
Console.WriteLine("New domain 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 with 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_AccountObjectMaskValue property 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:

String username = "set me";
String apiKey = "set me";
 
authenticate authenticate = new authenticate();
authenticate.username = username;
authenticate.apiKey = apiKey;
 
SoftLayer_AccountService 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.
SoftLayer_AccountObjectMask objectMask = new SoftLayer_AccountObjectMask();
objectMask.mask = new SoftLayer_Account();
 
SoftLayer_Hardware_Server[] objectMaskHardware = new SoftLayer_Hardware_Server[1];
SoftLayer_Network_Component[] objectMaskHardwareNetworkComponents = new SoftLayer_Network_Component[1];
SoftLayer_Software_Component_Password[] objectMaskHardwareOperatingSystemPasswords = new SoftLayer_Software_Component_Password[1];
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 uint();
objectMaskHardware[0].processorCountSpecified = true;
objectMask.mask.hardware = objectMaskHardware;
accountService.SoftLayer_AccountObjectMaskValue = objectMask;
 
SoftLayer_Hardware_Server[] hardware = (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.

String username = "set me";
String apiKey = "set me";
 
authenticate authenticate = new authenticate();
authenticate.username = username;
authenticate.apiKey = apiKey;
 
SoftLayer_AccountService accountService = new SoftLayer_AccountService();
accountService.authenticateValue = authenticate;
 
// Retrieve our first two open support tickets
resultLimit resultLimit = new resultLimit();
resultLimit.limit = 2;
resultLimit.offset = 0;
 
accountService.resultLimitValue = resultLimit;
 
SoftLayer_Ticket[] tickets = 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. For example:

String username = "set me";
String apiKey = "an incorrect key";
 
authenticate authenticate = new authenticate();
authenticate.username = username;
authenticate.apiKey = apiKey;
 
SoftLayer_AccountService accountService = new SoftLayer_AccountService();
accountService.authenticateValue = authenticate;
 
// Exit the script with the message:
// "Unable to retrieve account information: Invalid API key"
try 
{
    SoftLayer_Account account = accountService.getObject();
}
catch (Exception ex)
{
    Console.WriteLine("Unable to retrieve account information: " + ex.Message);
}

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 handing 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, 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. After complete, the latest SoftLayer offerings will be available in your project.

If you used wsdl.exe to generate code files from SoftLayer's API WSDLs, re-run your full wsdl.exe command to re-import SoftLayer's latest API WSDLs into your project.

Referenced API Components

Services

• SoftLayer_Account
• SoftLayer_Dns_Domain
• SoftLayer_Hardware_Server

Data Types

• SoftLayer_Hardware_Server

Methods

• SoftLayer_Account::getObject
• SoftLayer_Account::getHardware
• SoftLayer_Account::getOpenTickets

External Links

• IntelliSense (Visual Studio) MSDN Coding Aid