Freigeben über

WebAPIService-Klassenbibliothek (C#)

  • Artikel

WebAPIService ist ein Beispielprojekt für eine .NET 6.0-Klassenbibliothek, das mehrere wichtige Funktionen vorführt, die Sie bei der Verwendung der Dataverse-Web-API einbeziehen sollten.

Diese Bibliothek veranschaulicht Folgendes:

  • Verwaltung von Dataverse Serviceschutzgrenzen mit der .NET-Bibliothek für Resilienz und Behandlung von vorübergehenden Fehlern Polly.
  • Verwalten eines HttpClient in .NET mit IHttpClientFactory.
  • Verwenden von Konfigurationsdaten zum Verwalten des Verhaltens des Clients.
  • Verwalten von Fehlern, die von der Dataverse Web-API zurückgegeben werden.
  • Ein Muster der Wiederverwendung von Code durch:
    • Erstellen von Klassen, die von HttpRequestMessage und HttpResponseMessage erben.
    • Methoden, die diese Klassen verwenden.
    • Ein modulares Muster zum Hinzufügen neuer Funktionen nach Bedarf.

Hinweis

Diese Beispielbibliothek ist ein Helfer, der von allen Dataverse C#-Web-API-Beispielen verwendet wird, aber es ist kein SDK. Es wird nur getestet, um zu bestätigen, dass die Beispiele, die es verwenden, erfolgreich ausgeführt werden. Dieser Beispielcode wird „wie besehen“ ohne Gewährleistung für die Wiederverwendung bereitgestellt.

Diese Bibliothek führt Folgendes nicht aus:

  • Authentifizierung verwalten. Sie hängt von einer Funktion ab, die von einer Anwendung übergeben wird, die das zu verwendende Zugriffstoken bereitstellt. Alle Web-API-Beispiele hängen von einer gemeinsam genutzten App-Klasse ab, die die Authentifizierung mit der Microsoft-Authentifizierungsbibliothek (MSAL) verwaltet. MSAL unterstützt mehrere verschiedene Typen von Authentifizierungsabläufen. Diese Beispiele verwenden der Einfachheit halber den Flow Benutzername/Kennwort (ROPC). Dieser Flow wird jedoch nicht empfohlen. Für Ihre Apps sollten Sie einen der anderen Flows verwenden. Mehr Informationen: Authentifizierungs-Flow-Unterstützung in der Microsoft-Authentifizierungsbibliothek.
  • Stellen Sie Funktionen zur Codegenerierung bereit. Alle in den Beispielen verwendeten Klassen wurden von Hand geschrieben. Alle Geschäftsdaten verwenden die bekannte Json.NET JObject-Klasse anstelle einer Klasse, die den Entitätstyp darstellt.
  • Stellen Sie ein Objektmodell zum Erstellen von OData-Abfragen bereit. Alle Abfragen zeigen die OData-Abfragesyntax als Abfrageparameter.

Code

Sie finden den Quellcode der WebApiService-Klassenbibliothek und die Visual Studio-Lösung unter PowerApps-Samples/dataverse/webapi/C#-NETx/WebAPIService

Klassenliste

Die folgenden Klassen sind im WebAPIService enthalten.

Service-Klasse

Die Service-Klasse stellt Methoden bereit, an die durch ein HttpClient verwaltet mit IHttpClientFactory Anfragen an Dataverse gesendet werden können.

Der Service ist die Kernkomponente für alle Beispiele und Sie können ihn verwenden, um alle mit Beispielcode demonstrierten Vorgänge auszuführen. Alles andere, was im WebAPIService enthalten ist, bzw. alle Beispiele, die ihn verwenden, ermöglichen die Wiederverwendung von Code sowie die Demonstration der Funktionen des Dataverse-Web-API auf allgemeinerer Ebene.

Der Service-Konstruktor akzeptiert eine Config-Klasseninstanz, die zwei erforderliche Eigenschaften enthält: GetAccessToken und Url. Alle anderen Eigenschaften stellen Optionen dar, die Standardwerte haben.

Der Konstruktor verwendet Abhängigkeitsinjektion, um ein IHttpClientFactory-Element zu erstellen, das einen benanntes HttpClient-Element mit den in der ConfigureHttpClient-Funktion angegebenen Eigenschaften zurückgeben kann. Ob dieser Client Cookies verwendet oder nicht, hängt davon ab, ob der Config.DisableCookies-Parameter eingestellt ist. Im Konstruktor die durch die statische GetRetryPolicy-Methode festgelegte Richtlinie, die steuert, wie vorübergehende Fehler und Dataverse-Dienstschutzgrenzen verwaltet werden.

Servicemethoden

Die Service-Klasse hat die folgenden Methoden:

SendAsync-Methode

Diese Methode ist letztendlich für alle Vorgänge verantwortlich.

Diese Methode:

SendAsync<T> Methode

Diese Methode erleichtert die Rückgabe einer Klasse, die Eigenschaften enthält, die in ComplexTypes gefunden wurden, die von OData-Aktionen und -Funktionen in der Dataverse Web-API zurückgegeben wurden.

  • Hat einen HttpRequestMessage-Parameter. Bei die Verwendung dieser Methode erwartet wird , aber nicht erforderlich ist, dass der Anforderungsparameter einer der *Reaktionsklassen ist, die von HttpResponseMessage abstammen.
  • Gibt Task<T> zurück, wobei T eine von HttpResponseMessage abgeleitete Klasse ist. Weitere Informationen finden Sie unter *Reaktionsklassen.
  • Ruft die SendAsync-Methode auf.
  • Verwendet die HttpResponseMessage As<T>-Erweiterungsmethode, um den angeforderten Typ zurückzugeben.

Im folgenden Beispiel wird gezeigt die Verwendung mit der WhoAmI function:

static async Task WhoAmI(Service service)
{
   var response = await service.SendAsync<WhoAmIResponse>(new WhoAmIRequest());

   Console.WriteLine($"Your user ID is {response.UserId}");
}
ParseError-Methode

Diese Methode analysiert den Inhalt einer HttpResponseMessage für eine erfolglose HttpRequestMessage, damit eine ServiceException ausgegeben wird. Die SendAsync-Methode verwendet diese Methode, wenn die HttpResponseMessage.IsSuccessStatusCode-Eigenschaft falsch ist. Sie können es auch verwenden, um Fehlerinformationen aus HttpResponseMessage-Instanzen zu extrahieren, die von BatchResponse.HttpResponseMessages zurückgegeben werden, wenn die BatchRequest.ContinueOnError-Eigenschaft auf wahr gesetzt ist. Weitere Informationen: Batch

Service-Eigenschaften

Service hat eine einzige Eigenschaft: BaseAddress.

BaseAddress-Eigenschaft

Diese Eigenschaft gibt die in Config.Url festgelegte Basis-URL zurück. Sie benötigen diese URL bei der Instanziierung der BatchRequest-Klasse und zum Anhängen an eine relative URL, wann immer eine absolute URL benötigt wird.

Config-Klasse

Die Config-Klasse enthält Eigenschaften, die das Verhalten der Anwendung steuern, wie in der folgenden Tabelle dargestellt:

Eigenschaften typ Beschreibung
GetAccessToken Func<Task<string>> Eine Funktion, die von der Clientanwendung bereitgestellt wird, um ein Zugriffstoken zurückzugeben.
Url string? Der Basis Url der Umgebung. Beispiel: https://org.api.crm.dynamics.com
CallerObjectId Guid Der SystemUser.ActiveDirectoryGuid-Wert für den Antrag auf Identitätswechsel. Standard ist Guid.Empty
Weitere Informationen: Sich für mit Web-API ein anderes Benutzerkonto ausgeben
TimeoutInSeconds ushort Wie lange auf eine Zeitüberschreitung gewartet werden soll. Standard ist 120 Sekunden.
MaxRetries byte Maximale Anzahl von Wiederholungsversuchen, wenn Dienstschutzgrenzen erreicht werden. Die Standardeinstellung ist 3.
Version string Der zu verwendende Service. Der Standardwert ist v9.2
DisableCookies bool Ob Cookies deaktiviert werden sollen, um die Leistung in Szenarien zu steigern, in denen Daten massenweise geladen werden. Weitere Informationen: Server-Affinität

EntityReference-Klasse

Die EntityReference-Klasse steht für einen Verweis auf eine Dataverse-Tabelle. OData identifiziert Ressourcen mit einer URL. EntityReference stellt Methoden bereit, die das Erstellen und Zugreifen auf Eigenschaften von URLs erleichtern.

EntityReference-Konstruktoren

Verwenden Sie die folgenden Konstruktoren, um eine EntityReference zu instanziieren.

EntityReference(string entitySetName, Guid? ID)

Erstellt eine Entitätsreferenz mit EntitySetName und einer Guid.

EntityReference(string uri)

Analysiert eine absolute oder relative URL, um eine Entitätsreferenz zu erstellen, einschließlich URLs, die alternative Schlüssel verwenden.

EntityReference(string setName, Dictionary<string, string>? keyAttributes)

Verwenden Sie diesen Konstruktor, um eine Entitätsreferenz mit einem Alternativschlüssel zu instanziieren.

Hinweis

Die Schlüsselwerte müssen Zeichenfolgenwerte sein. Dadurch werden andere Typen nicht in entsprechende Zeichenfolgen konvertiert.

EntityReference-Eigenschaften

EntityReference verfügt über die folgenden öffentlichen Eigenschaften:

Eigenschaften typ Beschreibung
Id Guid? Der Primärschlüsselwert des Datensatzes, wenn kein Alternativschlüssel verwendet wird.
KeyAttributes Dictionary<string, string> Die Zeichenfolgenwerte, die Alternativschlüssel-Werte darstellen, die in einer URL verwendet werden.
SetName string EntitySetName des Entitätstyps.
Path string Eine relative Url zum Datensatz.

EntityReference-Methoden

EntityReference verfügt über die folgenden öffentlichen Methoden: Beide benötigen keine Parameter.

Methodenname Rückgabetyp Beschreibung des Dataflows
AsODataId string Gibt eine Zeichenfolge zurück, die zur Verwendung als Parameterverweis auf einen Datensatz in der URL für eine OData-Funktion formatiert ist.
AsJObject JObject Gibt ein JObject zurück, das als Parameterreferenz auf einen Datensatz in einer OData-Aktion verwendet werden kann.

Fehlerklassen

ODataError, Error, und ODataException sind Klassen, die zum Deserialisieren von Fehlern verwendet werden, die vom Service zurückgegeben werden. Sie müssen nicht direkt mit ihnen zusammenarbeiten.

ServiceException

ServiceException ist eine Ausnahmeklasse die Eigenschaften des vom Service zurückgegebenen Fehlers enthält. Verwenden Sie die ParseError-Methode um eine Instanz dieser Ausnahme zu erhalten.

Erweiterungen

WebApiService verfügt über eine Erweiterungsmethode eines .NET-Typs.

HttpResponseMessage As<T>

Diese Erweiterung instanziiert eine Instanz von T wobei T von HttpResponseMessage abgeleitet ist und die Eigenschaften der HttpResponseMessage zur abgeleiteten Klasse kopiert. Der Service SendAsync<T>-Methode nutzt diese Methode, kann aber auch separat verwendet werden. Bei der Verwendung der BatchRequest-Klasse haben die Elemente in den BatchResponse.HttpResponseMessages zum Beispiel den Typ HttpResponseMessage. Sie können diese Erweiterung verwenden, um sie in die entsprechende abgeleitete Klasse zu konvertieren, um den Zugriff auf alle Eigenschaften zu erleichtern.

Meldungen

Der Messages-Ordner umfasst Klassen, die von HttpRequestMessage oder HttpResponseMessage erben.

Diese Klassen stellen wiederverwendbare Definitionen von Anforderungen und Antworten bereit, die OData-Vorgängen entsprechen, die Sie in einer beliebigen Dataverse-Umgebung verwenden können.

Diese Klassen bieten auch Beispiele für bestimmte Operationen, die mit HttpRequestMessage und HttpResponseMessage angewendet werden können, ohne von diesen Typen abzustammen.

Innerhalb einer Anwendung können Sie nach demselben Muster auch angepasste Nachrichten erstellen, die z. B. eine benutzerdefinierte API in Ihrer Umgebung repräsentieren. Dies sind modulare Klassen und müssen nicht in den WebAPIService.Messages-Ordner aufgenommen werden.

Das Beispiel für Web-API-Funktionen und -Aktionen (C#) verwendet z.B. eine Custom-API, die erst dann in Dataverse enthalten ist, wenn eine Lösung mit der Custom-API installiert ist. Die Definition für die entsprechenden Klassen zur Verwendung dieser Nachricht befindet sich in der Beispielanwendung, die sie verwendet:

*Anforderungsklassen

Diese Klassen verfügen im Allgemeinen über einen Konstruktor mit Parametern, der eine HttpRequestMessage mit den für die Durchführung des Vorgangs erforderlichen Daten instanziiert. Sie können ganz nach Bedarf separate Eigenschaften haben.

Das einfachste Beispiel für dieses Muster ist die WhoAmIRequest-Klasse.

namespace PowerApps.Samples.Messages
{
    /// <summary>
    /// Contains the data to perform the WhoAmI function
    /// </summary>
    public sealed class WhoAmIRequest : HttpRequestMessage
    {
        /// <summary>
        /// Initializes the WhoAmIRequest
        /// </summary>
        public WhoAmIRequest()
        {
            Method = HttpMethod.Get;
            RequestUri = new Uri(
                uriString: "WhoAmI", 
                uriKind: UriKind.Relative);
        }
    }
}

Die Namen dieser Klassen stimmen im Allgemeinen mit den Klassen im Dataverse-SDK Microsoft.Xrm.Sdk.Messages Namespace überein, sind aber nicht auf diese Vorgänge beschränkt. Die Web-API ermöglicht beispielsweise die Ausführung einiger Vorgänge, die mit dem SDK nicht möglich sind. CreateRetrieveRequest ist zum Beispiel eine Nachricht, die einen Datensatz erstellt und abruft. Das Dataverse-SDK bietet diese Funktion nicht in einer einzigen Anfrage.

*Antwortklassen

Wann die *Anforderungsklassen einen Wert zurückgeben, gibt eine entsprechende *Antwortklasse für den Zugriff auf die zurückgegebenen Eigenschaften. Wenn die *Anforderung 204 No Content zurückgibt, gibt der Vorgang eine HttpResponseMessage zurück, aber es gibt keine abgeleitete Klasse. Verwenden Sie die SendAsync-Methode, um diese Anfragen zu senden.

*Response-Klassen stellen typisierte Eigenschaften bereit, die auf die HttpResponseMessage, Headers- oder Content -Eigenschaften zugreifen und analysieren, um Zugriff auf den von der Operation zurückgegebenen komplexen Typ bereitzustellen.

Die WhoAmIResponse-Klasse ist ein Beispiel. In dieser Klasse finden Sie den gesamten Code, der zum Extrahieren der Eigenschaften von WhoAmIResponse ComplexType benötigt wird.

using Newtonsoft.Json.Linq;

namespace PowerApps.Samples.Messages
{
    // This class must be instantiated by either:
    // - The Service.SendAsync<T> method
    // - The HttpResponseMessage.As<T> extension in Extensions.cs

    /// <summary>
    /// Contains the response from the WhoAmIRequest
    /// </summary>
    public sealed class WhoAmIResponse : HttpResponseMessage
    {

        // Cache the async content
        private string? _content;

        //Provides JObject for property getters
        private JObject _jObject
        {
            get
            {
                _content ??= Content.ReadAsStringAsync().GetAwaiter().GetResult();

                return JObject.Parse(_content);
            }
        }

        /// <summary>
        /// Gets the ID of the business to which the logged on user belongs.
        /// </summary>
        public Guid BusinessUnitId => (Guid)_jObject.GetValue(nameof(BusinessUnitId));

        /// <summary>
        /// Gets ID of the user who is logged on.
        /// </summary>
        public Guid UserId => (Guid)_jObject.GetValue(nameof(UserId));

        /// <summary>
        /// Gets ID of the organization that the user belongs to.
        /// </summary>
        public Guid OrganizationId => (Guid)_jObject.GetValue(nameof(OrganizationId));
    }
}

Diese Klassen können nur dann ordnungsgemäß instanziiert werden, wenn sie von der SendAsync<T>-Methode oder unter Verwendung der HttpResponseMessage As<T>-Erweiterung auf einer HttpResponseMessage in der BatchResponse.HttpResponseMessages-Eigenschaft zurückgegeben werden.

Batch

Der Batch-Ordner enthält drei Klassen, um das Sendens von OData $batch-Anfragen zu verwalten. Weitere Informationen: Ausführen von Batchvorgängen mit der Web-API.

BatchRequest

Der BatchRequest-Konstruktor initialisiert ein HttpRequestMessage-Element, das man mit der SendAsync<T>-Methode verwenden kann, um Anfragen stapelweise zu senden. Der Konstruktor benötigt den Service.BaseAddress-Wert, der als Parameter übergeben werden soll.

BatchRequest hat die folgenden Eigenschaften.

Eigenschaften Type Beschreibung des Dataflows
ContinueOnError Bool Steuert, ob der Stapelvorgang fortgesetzt werden soll, wenn ein Fehler auftritt.
ChangeSets List<ChangeSet> Ein oder mehrere Änderungssets, die in den Stapel aufgenommen werden sollen.
Requests List<HttpRequestMessage> Ein oder mehrere HttpMessageRequest-Elemente, die nach außerhalb von ChangeSet gesendet werden sollen.

Wenn ChangeSets oder Requests festgelegt sind, werden sie in HttpMessageContent eingekapselt und zum Content der Anforderung hinzugefügt. Die private ToMessageContent-Methode wendet die erforderlichen Änderungen bei Headern an und gibt HttpMessageContent für beide ChangeSets und Requests-Eigenschaften zurück.

ChangeSet

Ein Änderungssatz stellt eine Gruppe von Anforderungen dar, die innerhalb einer Transaktion abgeschlossen werden müssen.

Sie enthält eine einzige Eigenschaft:

Eigenschaften Type Beschreibung des Dataflows
Requests List<HttpRequestMessage> Ein oder mehr HttpMessageRequest-Elemente, die innerhalb der Transaktion durchgeführt werden sollen.

BatchResponse

BatchResponse hat eine einzige Eigenschaft:

Eigenschaften Type Beschreibung des Dataflows
HttpResponseMessages List<HttpResponseMessage> Die Antworten auf den $batch-Vorgang.

BatchResponse hat eine private ParseMultipartContent-Methode, die vom Abrufer der HttpResponseMessages-Eigenschaft verwendet wird, um das MultipartContent-Element zu analysien, dass in einzelne HttpResponseMessage-Elemente zurückgegeben wird.

Um auf die Typ-Eigenschaften der zurückgegebenen HttpResponseMessage-Instanzen zuzugreifen, können Sie die verwenden HttpResponseMessage As<T>-Erweiterungsmethode verwenden.

Methoden

Für Vorgänge, die häufig durchgeführt werden, enthält der Methods-Ordner Erweiterungen der Service- Klasse. Diese Methoden ermöglichen die Verwendung der entsprechenden *Anforderungsklassen in einer einzigen Zeile.

Dazu gehören folgende Methoden:

Methode Rückgabetyp Beschreibung des Dataflows
Create Task<EntityReference> Erstellt einen neuen Datensatz.
CreateRetrieve Task<JObject> Erstellt einen neuen Datensatz und ruft ihn ab.
Delete Task Löscht einen Datensatz.
FetchXml Task<FetchXmlResponse> Ruft die Ergebnisse einer FetchXml-Abfrage ab. Anfrage wird mit mithilfe von $batch mit POST gesendet, um Probleme zu mindern, bei denen lange mit GET gesendete URLs Grenzen überschreiten können.
GetColumnValue<T> Task<T> Ruft einen einzelnen Spaltenwert aus einer Tabellenzeile ab.
Retrieve Task<JObject> Ruft einen Datensatz ab.
RetrieveMultiple Task<RetrieveMultipleResponse> Ruft mehrere Datensätze ab.
SetColumnValue<T> Task Legt den Wert einer Spalte für eine Tabellenzeile fest.
Update Task Aktualisiert einen Datensatz.
Upsert Task<UpsertResponse> Führt ein Upsert für einen Datensatz aus.

Wenn in einer Beispielanwendung, die WebAPIService verwendet, der Vorgang keine API darstellt, die standardmäßig in Dataverse zu finden ist, wird die Methode in der Anwendung und nicht in WebAPIService festgelegt.

Das Beispiel für Web-API-Funktionen und -Aktionen (C#) verwendet z.B. eine Custom-API, die erst dann in Dataverse enthalten ist, wenn eine Lösung mit der Custom-API installiert ist. Die Definition für diese Methode befindet sich in der Beispielanwendung, die sie verwendet: FunctionsAndActions/Methods/IsSystemAdmin.cs

Typen

Der Types-Ordner enthält alle Klassen oder Aufzählungen, die ComplexTypes oder EnumTypes entsprechen und als Parameter oder Antworteigenschaften für Nachrichten benötigt werden.

Metadata

Der Metadata-Ordner enthält Messages und Types, die für Operationen spezifisch sind, die mit Dataverse-Schemadefinitionen arbeiten. Diese Klassen verfügen häufig über viele Eigenschaften, die komplexe Typen zurückgeben. Diese Typen werden im Beispiel für Web-API-Tabellenschemaovorgänge (C#) verwendet.

Siehe auch

Beispiel grundlegender Web-API-Operationen (C#)
Web API-Abfragedatenbeispiel (C#)
Beispiel bedingter Web-API-Operationen (C#)
Web-API-Funktionen- und Aktionen-Beispiel (C#)
Beispiel für Web-API-Tabellenschemavorgänge (C#)
Web-API WebApiService-Beispiel für parallele Operationen (C#)
Beispiel für parallele Web-API-Vorgänge mit TPL Dataflow-Komponenten (C#)

Hinweis

Können Sie uns Ihre Präferenzen für die Dokumentationssprache mitteilen? Nehmen Sie an einer kurzen Umfrage teil. (Beachten Sie, dass diese Umfrage auf Englisch ist.)

Die Umfrage dauert etwa sieben Minuten. Es werden keine personenbezogenen Daten erhoben. (Datenschutzbestimmungen).