Beispiele für Web-API-Datenvorgänge (C#)

Dieses Thema enthält Informationen zu den Web-API-Beispielen in C#. Jedes Beispiel beschäftigt sich mit einem anderen Aspekt der "Common Data Service"-Web-API. Merkmale und Struktur sind ähnlich.

Hinweis

Dieser Implementierungsansatz verwendet eine Objekterstellung auf niedriger Ebene und explizite HTTP-Nachrichtenaufrufe. Diese Ansatz ermöglicht das Steuern von Objekteigenschaften auf unterer Ebene, die das Verhalten der Web-API steuern. Dies unterstützt Sie dabei, die internen Arbeitsweise zu verstehen. Es ist jedoch nicht notwendigerweise ein Ansatz für die beste Entwicklerproduktivitätserfahrung.

Übergeordnete Bibliotheken wie die OData-Bibliothek dagegen abstrahieren einen großen Teil der Low-Level-Clientlogik. Die OData T4-Vorlage kann optional in Verbindung mit der OData-Bibliothek verwendet werden, um Cliententitätsklassen automatisch zu generieren.

Voraussetzungen

Folgendes wird benötigt, um die "Common Data Service"-Web-API-C#-Beispiele auszuführen:

Hinweis

Diese Beispiele erfordern die Version 2.x von Assembly Microsoft.IdentityModel.Client.ActiveDirectory für OAuth-basierte Authentifizierung.

Web-API-Beispiel (C#)

Die folgende Tabelle enthält Beispiele in C#. Jedes Beispiel wird allgemein in einem entsprechenden Beispielgruppenthema beschrieben, das sich auf die HTTP-Anforderung und die Antwortnachrichten im Thema Web-API-Beispiele konzentriert.

Probe Beispielgruppe Beschreibung
Beispiel grundlegender Web-API-Operationen (C#) Beispiel grundlegender Web-API-Operationen Veranschaulicht, wie "Common Data Service"-Entitätsdatensätze erstellt, abgerufen, aktualisiert, gelöscht, zugeordnet und deren Zuordnungen aufgehoben werden.
Web API-Abfragedatenbeispiel (C#) Web API-Abfragedatenbeispiel Veranschaulicht, wie "OData v4"-Abfragesyntax und -Funktionen sowie "Common Data Service"-Abfragefunktionen verwendet werden. Enthält Beispiele zur Arbeit mit vordefinierten Abfragen und die Verwendung von FetchXML, um Abfragen ausführen.
Beispiel bedingter Web-API-Operationen (C#) Beispiel bedingter Web-API-Operationen Veranschaulicht, wie Sie bedingte Operationen ausführen, die mit ETag-Kriterien angegeben werden.
Internet-API-Funktionen- und Aktionen-Beispiel (C#) Web API-Funktionen- und Aktionen-Beispiel Veranschaulicht, wie Sie gebundene/ungebundene Funktionen und Aktionen, einschließlich benutzerdefinierte Aktionen verwenden.

Herunterladen und ausführen der Beispiele

Der Quellcode für jedes Sample ist auf GitHub verfügbar. Sie können das Repository als Zip-Datei herunterladen, die die Lösungsdateien für die Samples enthält. Weitere Informationen finden Sie im Abschnitt Ausführen dieses Beispiels in jedem Beispielthema.

Verwendete Bibliotheken und Frameworks

Diese C#-Implementierung hängt von den folgenden Faktoren ab:

Json.NET-Bibliothek

In C# und die meisten sonstigen verwalteten Sprachen das JSON-Datenformat nicht nativ unterstützen, ist die aktuelle beste Methode, eine Bibliothek für diese Funktionen zu verwenden. Weitere Informationen finden Sie unter Eine Einführung zur JavaScript-Objektnotation (JSON) in JavaScript und in .NET. Json.NET ist eine beliebte Wahl für .NET-Projekte. Es stellt ein robustes, performantes Open-Source-Framework (MIT-Lizenz) für das Serialisieren, Konvertieren, Analysieren, Abfragen sowie zum Formatieren von JSON-Daten bereit. Weitere Informationen finden Sie in der Json.NET-Dokumentation.

In den C#-Beispielen wird dieser Bibliothek vor allem zur Serialisierung von Daten zwischen .NET-Objekten und HTTP-Nachrichtentexten genutzt. Obwohl die Bibliothek mehrere Möglichkeiten bereitstellt, um diese Aufgabe zu erfüllen, nutzen die Beispiele eine Vorgehensweise, bei der individuelle JObject-Instanzen für "Common Data Service"-Entitätsinstanzen (Datensätze) erstellt werden. Beispielsweise erstellt der folgende Code die Variable contact1, die eine "Common Data Service"-contact EntityType-Instanz darstellt, und stellt dann Werte für ausgewählte Eigenschaften für den Typ bereit.

  
JObject contact1 = new JObject();  
contact1.Add("firstname", "Peter");  
contact1.Add("lastname", "Cambel");  
contact1.Add("annualincome", 80000);  
contact1["jobtitle"] = "Junior Developer";  
  

Die Verwendung der Klammernotation in der letzten Anweisung entspricht der Hinzufügen-Methode. Diese Instanziierung kann auch über die statische Methode Parse erfolgen:

  
JObject contact1 = JObject.Parse(@"{firstname: 'Peter', lastname: 'Cambel', "  
+ @"annualincome: 80000, jobtitle: 'Junior Developer'}");  
  

Da JObject ein allgemeiner JSON-Typ ist, arbeitet es mit vielen Typüberprüfungen zur Laufzeit. Beispielsweise ist die folgende Anweisung syntaktisch gültig. Sie führt jedoch möglicherweise zu Laufzeitfehlern, da contact EntityType keine age-Eigenschaft enthält.

contact1.Add("age", 37); //Possible error--no age property exists in contact!

Sobald die Entitätsvariable initialisiert wurde, kann sie mithilfe von System.Net.Http-Klassen in einem Nachrichtentext gesendet werden. Beispielsweise:

  
HttpRequestMessage createrequest1 = new HttpRequestMessage(HttpMethod.Post, client.BaseAddress + "contacts");
createrequest1.Content = new StringContent(contact1.ToString());
createrequest1.Content.Headers.ContentType = MediaTypeHeaderValue.Parse("application/json");
HttpResponseMessage createResponse1 = client.SendAsync(createrequest1, HttpCompletionOption.ResponseHeadersRead).Result; 
  

Sie können auch JObject-Instanzen erstellen, indem Sie bei der Entitätsinstanzen während Abfragevorgängen deserialisieren. Beispielsweise:

  
//contact2Uri contains a reference to an existing CRM contact instance.  
string queryOptions = "?$select=fullname,annualincome,jobtitle,description";
HttpResponseMessage retrieveResponse1 = client.GetAsync(contact1Uri + queryOptions, HttpCompletionOption.ResponseHeadersRead).Result;
if (retrieveResponse1.IsSuccessStatusCode) //200
   {
     retrievedcontact1 = JObject.Parse(retrieveResponse1.Content.ReadAsStringAsync().Result);
     Console.WriteLine("Contact '{0}' retrieved: \n\tAnnual income: {1}" + "\n\tJob title: {2} \n\tDescription: {3}.",

// Can use either indexer or GetValue method (or a mix of two)
retrievedcontact1.GetValue("fullname"),
retrievedcontact1["annualincome"],
retrievedcontact1["jobtitle"],
retrievedcontact1["description"]);   //description is initialized empty.
    }
else
{
Console.WriteLine("Failed to retrieve contact for reason: {0}",retrieveResponse1.ReasonPhrase);
throw new Exception(string.Format("Failed to retrieve contact for reason: {0}", retrieveResponse1.Content));
 } 

Erfolgreiche Antwort und Fehlerbehandlung

Im Allgemeinen nutzen die Beispiele eine einfachen Methode zum Verarbeiten von HTTP-Antworten. Wenn die Anfrage erfolgreich ist, werden Informationen über den Vorgang der Regel per Konsole ausgegeben. Ob die Antwort eine JSON-Nutzlast oder nützliche Header enthält, werden diese Informationen nur bei Erfolg verarbeitet. Wenn letztlich eine "Common Data Service"-Entität erstellt wurde, wird die entityUris-Sammlung mit der URI dieser Ressource aktualisiert. Die DeleteRequiredRecords-Methode nutzt die Sammlung, um optional Daten, die durch das Beispiel erstellt wurden, auf Ihrem "Common Data Service"-Server zu löschen.

Wenn die Anforderung fehlschlägt, gibt das Programm eine kontextbezogene Nachricht über den fehlgeschlagenen Vorgang aus und löst dann eine benutzerdefinierte Ausnahme des Typs Exception aus. Der Ausnahmehandler gibt mehr Informationen zur Ausnahme aus und dann wird die Kontrolle an einen finally-Block übergeben, der eine Bereinigungslogik enthält. Dies ist wieder ein Anruf von DeleteRequiredRecords Der folgende Code zeigt diesen Fehlerbehandlungsansatz einer POST-Anfrage zur Erstellung eines Datensatzes.

  
if (response.StatusCode == HttpStatusCode.NoContent)  //204  
{  
Console.WriteLine("POST succeeded, entity created!");  
//optionally process response message headers or body here, for example:  
entityUri = response.Headers.GetValues("OData-EntityId").FirstOrDefault();  
entityUris.Add(entityUri);  
}  
else  
{  
Console.WriteLine("Operation failed: {0}", response.ReasonPhrase);  
throw new Exception(string.Format(" Operation Failed", response.Content));  
}  
  

HttpStatusCode.NoContent entspricht einem HTTP-Statuscode 204 “No content” (Kein Inhalt). Hier zeigt der Statuscode, dass die POST-Anfrage erfolgreich war. Weitere Informationen finden Sie unter Zusammenstellen von HTTP-Anforderungen und Fehlerbehandlung.

Eigenschaften und Methoden

Die meisten Beispiele nutzen dieselben allgemeinen Architekturmuster mit den folgenden Eigenschaften:

  • Der C#-Beispielcode befindet sich in der entsprechenden primären Quelldatei namens SampleProgram.cs. Diese enthält eine einzelne Klasse mit demselben Namen wie das Beispielprojekt.

  • Die Beispiele sind großzügig kommentiert: Zusammenfassungen werden auf Klassen- und Methodenebenen bereitgestellt, und auch die meisten wichtigen Anweisungen sind kommentiert. Ergänzende Dateien, z. B. die Anwendungskonfigurationsdatei App.config, enthalten häufig wichtige Kommentare.

Siehe auch

Common Data Service-Web-API verwenden
Web API Beispiele
Web API Beispiele (Clientseitiges JavaScript)
Beispiel grundlegender Web-API-Operationen (C#)
Web API-Abfragedatenbeispiel (C#)
Beispiel bedingter Web-API-Operationen (C#)
Internet-API-Funktionen- und Aktionen-Beispiel (C#)