Visual Basic .NET

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

  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 diesen Namen 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.

Wsdl.exe verwenden

Wsdl.exe befindet sich in C:\Program Files\Microsoft SDKs\Windows\v7.0A\bin\ und sollte mit den folgenden Switches ausgeführt werden, um die WSDLs der SoftLayer-API in Visual Basic-Code umzuwandeln:

  • /language:VB – Sagt der wsdl.exe, Visual Basic .NET-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.vb – Exportiert generierten Code in einen Pfad in Ihrer Projekthierarchie. In diesem Fall wird der Code in der Datei SoftLayer_API.vb 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: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

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.

  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.

Sie können die Objekte der SoftLayer-API jetzt als lokale Objekte in Ihrem Projekt verwenden.

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.

Dim accountService As SoftLayer_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.

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

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 Serviceobjekts 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.

Dim serverId As Integer = 1234
 
Dim hardwareServerInitParameters As SoftLayer_Hardware_ServerInitParameters = 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. Das nachstehende Beispiel zeigt, wie der API-Aufruf erfolgt.

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

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.

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

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_AccountObjectMaskValueproperty 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:

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

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.

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

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.

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

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, dann 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