Share via

Web API Beispiele (C#)

  • Artikel

 

Veröffentlicht: Januar 2017

Gilt für: Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online

Dieses Thema enthält Informationen zu den Web-API-Beispielen in C#. Jedes Beispiel beschäftigt sich mit einem anderen Aspekt der Microsoft Dynamics 365-Web-API.

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 abstrahieren einen großen Teil der Low-Level-Clientlogik. Die ODatas T4-Vorlage kann optional in Verbindung mit der OData-Bibliothek verwendet werden, um Cliententitätsklassen automatisch zu generieren.

In diesem Thema

Voraussetzungen

Web-API-Beispiel (C#)

Herunterladen und ausführen der Beispiele

Allgemeine Elemente in jedem Beispiel

Voraussetzungen

Das Folgende wird benötigt, um Dynamics 365-Web-API C#-Beispiele zu erstellen und auszuführen:

  • Eine Version von Microsoft Visual Studio 2015 oder höher. Eine kostenlose Visual Studio-Community-Version steht zum hier zum Download bereit.

  • Eine Internetverbindung, um die referenzierten NuGet-Pakete herunterzuladen und zu aktualisieren.

  • Zugriff auf Microsoft Dynamics 365 Online oder lokale (oder höher). Für alle Dynamics 365-Installationstypen ist ein Benutzerkonto mit Berechtigungen zur Durchführung von CRUD-Vorgängen erforderlich.

  • Um die Beispiele gegen Dynamics 365 (online) ausführen, müssen Sie die Anwendung mit Azure Active Directory registrieren, um eine Client-ID und eine Umleitungs-URL zu erhalten. Weitere Informationen finden Sie unter Exemplarische Vorgehensweise: Registrieren einer Dynamics 365-App bei Azure Active Directory.

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 Dynamics 365-Entitätsdatensätze erstellt, abgerufen, aktualisiert, gelöscht zugeordent und aufgehoben werden.

Web API-Abfragedatenbeispiel (C#)

Web API-Abfragedatenbeispiel

Veranschaulicht, wie OData v4 Abfragensyntax und -Funktionen und Microsoft Dynamics 365 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 Beispiel ist in der MSDN-Codegalerie verfügbar. Der Link, um jedes Beispiels herunterzuladen ist in dem Beispielthema enthalten. Der Beispieldownload ist eine komprimierten ZIP-Datei, die die Visual Studio 2015-Lösungsdateien zum Beispiel beinhaltet. Weitere Informationen Sie im Abschnitt Dieses Beispiel ausführen im jeweiligen Beispielthema.

Allgemeine Elemente in jedem Beispiel

Die meisten Beispiele haben eine vergleichbare Struktur und umfassen häufige Methoden und Ressourcen, um die grundlegenden Infrastruktur für ein Web-API C#-Programm bereitzustellen.

Viele der allgemeinen Elemente sind auch vorhanden, wenn Sie eine neue Lösung erstellen, die auf die Dynamics 365-Web-API zugreift. Weitere Informationen finden Sie unter Starten eines Dynamics 365-Web-API-Projekts in Visual Studio (C#).

Verwendete Bibliotheken und Frameworks

Diese C#-Implementierung hängt vom folgenden Hilfecode für die HTTP-Kommunikation, Anwendungskonfiguration, Authentifizierung, Fehlerbehandlung und JSON-Serialisierung 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 der Bibliothek mehrere Möglichkeiten bereitstellt, um diese Aufgabe zu erfüllen, nutzen die Beispiele eine Vorgehensweise, bei der individuelle JObject-Instanzen für Dynamics 365-Entitätsinstanzen (Datensätze) erstellt werden. Beispielsweise erstellt der folgende Code die Variable contact1, die eine Instanz von Dynamics 365 contact EntityType 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 können auch über die statische Methode Parse erreicht werden:

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

Da JObject einen 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 request = new HttpRequestMessage(HttpMethod.Post, "contacts");
request.Content = new StringContent(contact1.ToString(), Encoding.UTF8, "application/json");
HttpResponseMessage response = await httpClient.SendAsync(request1);

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 response = await httpClient.GetAsync(contact2Uri + queryOptions);
JObject contact2 = JsonConvert.DeserializeObject<JObject>(await response.Content.ReadAsStringAsync());

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 einer Dynamics 365-Entität erstellt wurde, wird die entityUris-Sammlung mit der URI dieser Ressource aktualisiert. Die DeleteRequiredRecords-Methode-Methode nutzt die Sammlung, um optional vom Beispiel auf dem Dynamics 365-Server erstellten Daten 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 CrmHttpResponseException 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 CrmHttpResponseException(response.Content);
}

HttpStatusCode.NoContent entspricht einem HTTP-Statuscode 204 "No content". 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 Program.cs. Diese enthält eine einzelne Klasse mit demselben Namen wie das Beispielprojekt.

  • Die Beispielklassen und die Verwenden Sie die Microsoft Dynamics 365 WEB API Hilfe-Bibliothek (C#) befinden sich im Namespace Microsoft.Crm.Sdk.Samples.

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

  • Die primäre Beispielklasse ist normalerweise für die folgenden Methoden strukturiert: Main-Methode, ConnectToCRM-Methode, CreateRequiredRecords-Methode, RunAsync-Methode, DisplayExceptions-Methode und DeleteRequiredRecords-Methode.

Main-Methode

Definitionsgemäß beginnt mit dieser Methode die Ausführung des Beispiels. Sie enthält ausschließlich Ablaufsteuerungs- und Ausnahmebehandlungslogik auf hoher Ebene, häufig den folgenden Code:

static void Main(string[] args)
{
FunctionsAndActions app = new FunctionsAndActions();
try
{
//Read configuration file and connect to specified CRM server.
app.ConnectToCRM(args);
app.CreateRequiredRecords();
Task.WaitAll(Task.Run(async () => await app.RunAsync()));
}
catch (System.Exception ex) { DisplayException(ex);
}
finally
{
if (app.httpClient != null)
{
app.DeleteRequiredRecords(true);
app.httpClient.Dispose();
}
Console.WriteLine("Press <Enter> to exit the program.");
Console.ReadLine();
}
}

ConnectToCRM-Methode

Diese Methode ruft die Hilfebibliotheken auf, um die Anwendungskonfigurationsdatei zu lesen und etabliert dann eine Verbindung zum angegebenen Dynamics 365-Server. Das Ergebnis dieser Schritte ist die Initialisierung einer HttpClient-Klasseneigenschaft, die während des Programms verwendet wird, um Web-Anforderungen zu senden und Antworten zu empfangen. Beachten Sie, dass die folgenden Eigenschaften für dieses Objekt festgelegt werden:

//Define the Web API address, the max period of execute time, the Odata
// version, and the expected response payload format.
httpClient.BaseAddress = new Uri(config.ServiceUrl + "api/data/v8.1/");
httpClient.Timeout = new TimeSpan(0, 2, 0);  // 2 minute timeout
httpClient.DefaultRequestHeaders.Add("OData-MaxVersion", "4.0");
httpClient.DefaultRequestHeaders.Add("OData-Version", "4.0");
httpClient.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));

Weitere Informationen zur Beispiel-Anwendungskonfiguration und -Authentifizierung finden Sie in Verwenden Sie die Microsoft Dynamics 365 WEB API Hilfe-Bibliothek (C#).

CreateRequiredRecords-Methode

Diese Methode erstellt und initialisiert die Entitätsdatensätze, die das Beispiel benötigt. Jedoch nur, wenn die entsprechenden Vorgänge nicht zum primären Thema des Beispiels gehören. Die Beispiel grundlegender Web-API-Operationen (C#) enthält beispielsweise diese Methode nicht, da es im Beispiel primär um die Datensatzerstellung geht.

RunAsync-Methode

Diese asynchrone Methode enthält entweder den entsprechenden Quellcode, oder, für längere Programme, ruft die Methoden auf, die den Beispielcode gruppieren. In enthaltene Code wird über eingebettete Kommentare und Kommentar im Abschnitt Anmerkungen des entsprechenden Beispielthemas erläutert.

DisplayExceptions-Methode

Diese Hilfsmethode zeigt die Ausnahmeinformationen (inkl. der internen Ausnahmen) über die Standardkonsole an.

DeleteRequiredRecords-Methode

Diese Begleitermethode löscht optional die Beispieldatensätze und andere Dynamics 365-Serverressourcen, die im Programm und über die CreateRequiredRecords-Methode-Methode erstellt werden. Sie holte eine Überprüfung des Vorgangs über den Benutzer ein, durchläuft dann die entityUris-Sammlung, und versucht, jedes Element mit einer HTTPS- DELETE-Nachricht zu löschen.

Siehe auch

Verwenden der Microsoft Dynamics 365-Web-API
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#)

Microsoft Dynamics 365

© 2017 Microsoft. Alle Rechte vorbehalten. Copyright