C Sharp

Verwendung von SOAP-WSDLs

Es gibt zwei Möglichkeiten, WSDLs der SoftLayer-API in Ihr Projekt zu importieren. Visual Studio kann einen SOAP-Service in eine Webreferenz umwandeln, auf die Ihr Projekt zugreifen kann. Zudem ist Visual Studio mit einem Dienstprogramm mit dem Namen wsdl.exe ausgestattet, das aus einer Eingabeaufforderung ausgeführt wird, um eine oder mehrere WSDL-Dateien zu lesen und direkt in Quellcode umzuwandeln, den Sie in Ihr Projekt aufnehmen können. Web-Services können normalerweise problemlos in Visual Studio verwendet werden. Wenn Ihr Projekt viele SoftLayer-API-Services verwendet, kann dies jedoch sehr umständlich werden. Wsdl.exe ist hilfreich, wenn für Ihr Projekt viele API-Services erforderlich sind.

Die Codebeispiele in diesem Beitrag stellen Code dar, der von SoftLayer-API-Services mit der wsdl.exe erstellt wurde.

Webreferenzen erstellen

Das Erstellen von Webreferenzen ist die erste Aufgabe, die für die Verarbeitung von SOAP-WSDLs durchzuführen ist. Halten Sie sich an die nachstehenden Schritte, um eine Webreferenz in Visual Studio zu erstellen.

  1. Klicken Sie auf das Menü Projekt in Visual Studio.
  2. Wählen Sie aus dem Dropdown-Fenster im Menü Projekt Servicereferenz hinzufügen aus.
  3. Klicken Sie im Fenster Servicereferenz hinzufügen auf die Schaltfläche Erweitert.

    Anmerkung: Das Fenster Servicereferenzeinstellungen wird angezeigt.

  4. Klicken Sie im Fenster Servicereferenzeinstellungen auf die Schaltfläche Webreferenz hinzufügen.
  5. Geben Sie im Feld URL die URL zur WSDL des SoftLayer-API-Service ein, den Sie verwenden möchten.
  6. Klicken Sie auf den grünen Pfeil rechts neben dem URL-Feld.

    Anmerkung: Visual Studio lädt die WSDL-Datei herunter und analysiert die darin enthaltenen Methoden und Datentypen.

  7. Geben Sie im Feld Name der Webreferenz einen Namen für Ihre neue Webreferenz ein.
    Anmerkung: Alle Verweise auf den API-Service, die dem Projekt hinzugefügt werden, werden durch das Projekt referenziert.
  8. Klicken Sie auf die Schaltfläche Referenz hinzufügen, um Ihren neuen Web-Service zu importieren.

    Anmerkung: Sie kehren jetzt zu Ihrem Projekt zurück und Ihr neuer API-Service ist in Visual Studio Solution Explorer sichtbar.

In diesem Beispiel wird eine Servicereferenz mit dem Namen „com.softlayer.api“ erstellt, Sie können jedoch Web-Services mit beliebigem Namen erstellen. Der Name Ihrer Webreferenz ist ein Namensbereich in Ihrem Projekt. Verwenden Sie die Anweisung using zu Beginn Ihres Programms, damit Sie den Namen Ihrer Webreferenz nicht bei jeder API-bezogenen Anweisung, die Sie verwenden, eingeben müssen. Verwenden Sie z. B. folgende Anweisung:

using projectName.com.softlayer.api;

Ersetzen Sie „projectName“ durch den Namen Ihres Visual Studio-Projekts, um Ihre Webreferenz als Standardnamensbereich festzulegen.

wsdl.exe verwenden

Wsdl.exe befindet sich in C:\Program Files\Microsoft SDKs\Windows\v7.0A\bin. Execute Wsdl.exe. Mit den folgenden Switches wandeln Sie SoftLayer-API-WSDLs in C#-Code um:

  • /language:CS – Sagt der wsdl.exe, C#-Code zu exportieren.
  • /sharetypes – Die WSDL-Dateien von SoftLayer haben einige ähnliche Datentypen gemeinsam. Der Switch /sharetypes kompiliert diese Datentypen in einzelnen Klassendateien, wodurch der Speicherbedarf der Quelle reduziert wird und die Effizienz beim Arbeiten in Visual Studio gesteigert wird.
  • /out:C:\path\to\project\SoftLayer_API.cs – Exportiert generierten Code in einen Pfad in Ihrer Projekthierarchie. In diesem Fall wird der Code in der Datei SoftLayer_API.cs gespeichert.

Beenden Sie den Befehl mit einer durch Leerzeichen getrennten Liste der URLs der WSDLs der API, die Sie importieren möchten. Sie können beliebig viele WSDL-Dateien importieren.

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

Anmerkung: Ersetzen Sie für die Durchführung privater API-Aufrufe https://api.softlayer.com durch http://api.service.softlayer.com. Weitere Informationen zur Durchführung privater API-Aufrufe sind im Beitrag Erste Schritte enthalten.

Führen Sie diesen Befehl erneut aus, wenn Sie weitere API-Services in Ihr Projekt importieren möchten.

Sobald Ihre Codedatei erstellt wurde, müssen Sie diese in Ihr Projekt aufnehmen. Halten Sie sich an die folgenden Schritte, um die neu erstellte Codedatei in Ihr Projekt aufzunehmen:

  1. Klicken Sie in Visual Studio Solution Explorer mit der rechten Maustaste auf den Namen Ihres Projekts.
  2. Scrollen Sie im erweiterten Menü über die Option Hinzufügen.
  3. Klicken Sie im Menü Hinzufügen auf die Schaltfläche Bestehendes Element.
  4. Lokalisieren Sie Ihre generierte Codedatei im Dialogfenster Bestehendes Element hinzufügen.
  5. Klicken Sie, um Ihre generierte Codedatei hervorzuheben.
  6. Klicken Sie auf die Schaltfläche OK, um fortzufahren.

Ihr Projekt muss schließlich die Servicereferenz System.Web.Services enthalten, damit SOAP-Aufrufe von Ihrem importierten Code möglich sind.

  1. Klicken Sie, um das Menü Projekt in Visual Studio zu erweitern.
  2. Wählen Sie Referenz hinzufügen aus.
  3. Klicken Sie auf die Registerkarte .NET.
  4. Wählen Sie System.Web.Services aus.
  5. Klicken Sie auf die Schaltfläche OK, um Ihrem Projekt die Referenz hinzuzufügen.

Durchführung von API-Aufrufen

Serviceobjekte erstellen

Jedem API-Service in Ihrem Projekt ist eine Serviceklasse zugeordnet, die für die Durchführung von API-Aufrufen verantwortlich ist. Serviceklassen werden nach dem API-Service benannt, den Sie aufrufen möchten. Zum Beispiel ist der Klassenname für den API-Service SoftLayer_Account SoftLayer_AccountService und der Serviceklassenname für den SoftLayer_Hardware_Server-Service SoftLayer_Hardware_ServerService. Serviceobjekte haben Eigenschaften, die den API-Features entsprechen, wie z. B. Authentifizierung, Initialisierungsparameter, Objektmasken und Ergebnisbegrenzungen. API-Methodenaufrufe erfolgen auch direkt für diese Objekte. Beispiel:
SoftLayer_AccountService accountService = new SoftLayer_AccountService();

Authentifizierung binden

Authentifizieren Sie Ihre API-Aufrufe mit Ihrem API-Benutzernamen und -Schlüssel, indem Sie ein authenticate-Objekt definieren. Legen Sie die Eigenschaften username und apiKey Ihres Authentifizierungsobjekts auf Ihren API-Benutzernamen und -Schlüssel fest. Binden Sie das Authentifizierungsobjekt an Ihr API-Serviceobjekt, indem Sie die Eigenschaft authenticateValue auf Ihr Authentifizierungsobjekt festlegen.

String username = "set me";
String apiKey = "set me";
 
authenticate authenticate = new authenticate();
authenticate.username = username;
authenticate.apiKey = apiKey;
 
accountService.authenticateValue = authenticate;

Initialisierungsparameter festlegen

Parameter für die Initialisierung von API-Aufrufen (init-Parameter) verfügen ebenfalls über definierte Klassen, die dem API-Service entsprechen, den Sie aufrufen. Init-Parameterklassen werden nach dem API-Service benannt, den Sie aufrufen. Zum Beispiel ist der init-Parameterklassenname für den SoftLayer_Account-Service SoftLayer_AccountInitParameters und der init-Parameterklassenname für den SoftLayer_Hardware_Server-Service SoftLayer_Hardware_ServerInitParameters. Init-Parameterobjekte haben jeweils eine id-Eigenschaft (ganzzahliger Typ), die der ID des SoftLayer-Objekts entspricht, das Sie abfragen möchten. Binden Sie Ihr init-Parameterobjekt an Ihr Serviceobjekt, indem Sie es auf die Eigenschaft InitParameterValue Ihres Serviceobjeks festlegen, wobei dem API-Service entspricht, den Sie aufrufen.

Wenn ein API-Aufruf keinem bestimmten SoftLayer-Objekt entspricht, müssen Sie keinen Initialisierungsparameterwert an Ihr Serviceobjekt binden. Das nachstehende Code-Snippet zeigt dieses Szenario:

int serverId = 1234;
 
SoftLayer_Hardware_ServerInitParameters hardwareServerInitParameters = new SoftLayer_Hardware_ServerInitParameters();
hardwareServerInitParameters.id = serverId;
hardwareServerService.SoftLayer_Hardware_ServerInitParametersValue = hardwareServerInitParameters;

Den API-Aufruf durchführen
Sobald Ihr Serviceobjekt bereit ist, führen Sie den API-Methodenaufruf direkt für Ihr Serviceobjekt durch. Verwenden Sie den nachstehenden Code, um diese Aktion durchzuführen:

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();

Der in Ihr Projekt importierte Code definiert Klassen für alle in der SoftLayer-API definierten Datentypen. Erstellen Sie Instanzen von neuen Datentypobjekten ggf. als Aufrufparameter oder Aufrufergebnisse.

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());

Verwendung von Objektmasken

Binden Sie eine Objektmaske an Ihre API-Aufrufe, indem Sie zuerst ein Objektmaskenobjekt deklarieren. Die Klassennamen von Objektmasken entsprechen dem API-Service, den Sie verwenden, und beginnen mit dem Namen Ihres API-Service gefolgt von ObjectMask. Zum Beispiel hat eine Objektmaske für den API-Service SoftLayer_Account den Klassennamen SoftLayer_AccountObjectMask und der Klassenname der entsprechenden Objektmaske des SoftLayer_Hardware_Server-Service lautet SoftLayer_Hardware_ServerObjectMask.

Jede Objektmaskenklasse hat eine Eigenschaft mask, die die relationalen Daten modelliert, die Sie abrufen möchten. Die Eigenschaft mask ist ein Objekt des Datentyps Ihres API-Service. Beispielsweise ist SoftLayer_AccountObjectMask.mask ein SoftLayer_Account-Objekt und SoftLayer_Hardware_ServerObjectMask.mask ein SoftLayer_Hardware_Server-Objekt. Erstellen Sie Instanzen der relationalen Eigenschaften, die Sie in der mask-Eigenschaft Ihrer Objektmaske abrufen möchten, als neue Objekte, die den Datentyp dieser Eigenschaften darstellen. Wenn es sich bei der relationalen Eigenschaft um einen Arraytyp handelt, deklarieren Sie einen Array mit einem Element, das ein einzelnes Objekt enthält, das den Datentyp der relationalen Eigenschaft darstellt, die Sie abrufen möchten.

Ihr API-Serviceobjekt hat eine Eigenschaft, die einem optionalen Objektmaskenwert entspricht. Die Eigenschaftsnamen von Objektmaskenwerten entsprechen dem Namen des API-Service, den Sie verwenden, und beginnen mit dem Namen Ihres API-Service gefolgt von ObjectMaskValue. Binden Sie Ihr neues Objektmaskenobjekt an Ihr Serviceobjekt, indem Sie es der Eigenschaft ObjectMaskValue Ihres Serviceobjekts zuordnen. Binden Sie z. B. eine Objektmaske an ein SoftLayer_Account-Serviceobjekt, indem Sie die Eigenschaft SoftLayer_AccountObjectMaskValue Ihrem Objektmaskenobjekt zuordnen.

In diesem Beispiel werden die physischen Hardwaredatensätze eines Accounts sowie der Betriebssystemdatensatz der Hardware, die Betriebssystemkennwörter, die Netzwerkkomponenten, das Rechenzentrum, in dem sich die Hardware befindet, und die Anzahl Prozessoren in der jeweiligen Hardware abgerufen:

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();

Verwendung von Ergebnisbegrenzungen

Beim Abrufen von Daten, insbesondere bei Abfragen, die das Extrahieren von Informationssnippets aus größeren Gruppen beinhalten, können Sie durch Verwendung von Ergebnisbegrenzungen Ihre Wartezeit auf die Rückgabe erheblich verkürzen.

Begrenzen Sie die Anzahl Ergebnisse in Ihrem API-Aufruf, indem Sie ein neues resultLimit-Objekt erstellen und es an Ihr API-Serviceobjekt binden. ResultLimit hat zwei Eigenschaften:

  • limit: Die Anzahl Ergebnisse, um den Aufruf zu begrenzen.
  • offset: Ein optionaler Offset, um die Ergebnisliste zu beginnen.

Binden Sie Ihre neue Ergebnisbegrenzung an Ihr API-Serviceobjekt, indem Sie die Eigenschaft resultLimitValue Ihres Serviceobjekts auf Ihr Ergebnisbegrenzungsobjekt festlegen.

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();

Fehlerbehandlung

Fehler beim Aufruf der SoftLayer-API werden als Ausnahmebedingungen an den .NET SOAP-Handler gesendet. Führen Sie Aufrufe der SoftLayer-API in Try/Catch-Blocks durch, um eine ordnungsgemäße Abwicklung sicherzustellen. Beispiel:

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);
}

Ausschlüsse

Für die Arbeit mit dem generierten Code der SoftLayer-API in Visual Studio können bei der Erstellung oder Verwendung von SoftLayer-API-Objekten ein oder zwei zusätzliche Schritte erforderlich sein. Diese Schritte umfassen das Festlegen „angegebener“ Eigenschaften und den Umgang mit Änderungen in API-Services.

„Angegebene“ Eigenschaften festlegen

Einige Objekttypen im generierten Code verfügen neben der Objekteigenschaft über eine „angegebene“ Eigenschaft. Wenn Sie diese Eigenschaften explizit festlegen, muss die entsprechende angegebene Eigenschaft auf „True“ gesetzt werden. Verwenden Sie Visual Studio IntelliSense, um zu bestimmen, welchen Eigenschaften angegebene Eigenschaften zugeordnet sind.

Was tun, wenn API-Services geändert werden

SoftLayer aktualisiert WSDLs der API, wenn neue Produkte und Services freigegeben werden. Wandeln Sie diese WSDLs erneut um, um die neuen Features verwenden zu können.

Wenn die SoftLayer-API als Webreferenz in Ihr Projekt importiert wird, klicken Sie in Visual Studio Solution Explorer mit der rechten Maustaste auf den Namen Ihrer Webreferenz und wählen Sie „Webreferenz aktualisieren“ aus. Visual Studio braucht eine Weile, um den Web-Service erneut zu importieren. Danach stehen Ihrem Projekt die neusten SoftLayer-Angebote zur Verfügung.

Sollten Sie wsdl.exe verwendet haben, um Codedateien aus WSDLs der SoftLayer-API zu generieren, führen Sie erneut den vollständigen Befehl wsdl.exe aus, um die neuesten WSDLs der SoftLayer-API in Ihr Projekt zu importieren.

Referenzierte API-Komponenten

Services

Datentypen

Methoden