Einführung

  • 6 Minuten

Microsoft Dataverse stellt zwei primäre APIs für die Arbeit mit Daten bereit, das Dataverse SDK für .NET und die Web-API. Jede Technologie, die HTTP-Anfragen ausführen kann, kann die Web-API verwenden. Das Dataverse-SDK für .NET zielt auf Anwendungen ab, die mit .NET Framework oder .NET Core erstellt wurden.

Dieses Modul konzentriert sich auf das SDK für .NET und den Organisationsservice. Weitere Informationen zum Web-API finden Sie unter Den Microsoft Dataverse-Web-API verwenden im Dataverse-Entwicklerhandbuch.

Das DataverseSDK für .NET bietet Klassen und Tools, um .NET-Entwicklern das Erstellen von Dataverse-Erweiterungen und benutzerdefinierter Anwendungslogik zu erleichtern, die in Dataverse integriert werden kann. Sie können das SDK für .NET verwenden, wenn Sie Plug-Ins schreiben, benutzerdefinierte Web‑ oder Client-Apps, Azure Functions und weiteres erstellen.

Auf das Dataverse SDK für .NET wird in Ihrem Code mit einem der beiden NuGet-Pakete verwiesen. Zum Entwickeln von Dataverse-Plug-Ins würde das Microsoft.CrmSdk.CoreAssemblies NuGet Paket verwendet werden. Das NuGet-Paket Microsoft.PowerPlatform.Dataverse.Client wird für anderen .NET Framework- oder .NET Core-Code empfohlen. In diesem Modul wird Letzteres behandelt, viele der Konzepte sind jedoch für beide gültig.

Dataverse Organization-Service

Anwendungen, die das Dataverse SDK für .NET verwenden, arbeiten mit Daten und Diensten in einer Dataverse-Umgebung über eine Schnittstelle IOrganizationService zusammen, die allgemein als Organisationsdienst bezeichnet werden. Diese Schnittstelle legt die folgenden primären Methoden fest, die Sie verwenden können:

  • Zuordnen – Erstellt eine Verknüpfung zwischen Tabellenzeilen.
  • Erstellen – Erstellt neue Zeilen.
  • Löschen – Löschen Sie eine Zeile.
  • Zuordnen aufheben – Löschen Sie eine Verknüpfung zwischen Tabellenzeilen.
  • Ausführen – Verwendet ein Anforderungs-/Antwortmuster, um eine Nachricht auszuführen. Teil davon ist es auch, benutzerdefinierte Dataverse-APIs aufzurufen.
  • Retrieve – Rufen Sie eine einzelne Zeile ab.
  • RetrieveMultiple – Rufen Sie eine Zeilensammlung ab.
  • Update – Aktualisiert eine bestehende Zeile.

Mit dem Muster CreateAsync von Methodennamen können Sie über die Schnittstelle auch asynchrone Optionen für jede Methode verwenden.

Anwendungen können mit der Klasse ServiceClient eine Instanz eines Objekts abrufen, das die Schnittstelle IOrganizationService implementiert. Der ServiceClient verarbeitet die Logistik der Authentifizierung und verwaltet die Verbindung zur Dataverse-Umgebung.

Im folgenden Beispiel wird eine Instanz von ServiceClient abgerufen und eine neue Kontotabellenzeile erstellt.

    ServiceClient serviceClient = new ServiceClient("<connectionString>");

    Entity newAccount = new Entity("account");
    newAccount["name"] = "Fourth Coffee";
    Guid accountid = serviceClient.Create(newAccount);

Jede der Methoden wie „Create“ ist lediglich eine Hilfsmethode, mit der eine Anforderungsnachricht verfasst und die Execute-Methode zum Empfangen einer Antwortnachricht aufgerufen wird. Erstellen Sie die Anforderung mit der Klasse „CreateRequest“, und empfangen Sie die Antwortnachricht „CreateResponse“, um einen Erstellungsvorgang auszuführen. Dieses Muster ist für alle Dataverse Organization-Serviceprozesse gleich, auch wenn Sie benutzerdefinierte Dataverse-APIs festlegen.

Die Entitätsklasse verwenden

Verwenden Sie die Klasse Entität für die Darstellung der Daten, wenn Sie den Organisationsdienst zum Arbeiten mit Daten verwenden. Die Entitätsklasse repräsentiert eine Instanz einer Dataverse-Tabellenzeile. Wenn Sie mit den Daten arbeiten, können Sie zwei Programmierstile verwenden: frühe Bindung und späte Bindung. Die Hauptunterschiede befinden sich in der Typkonvertierung und Typprüfung. Die frühe Bindung ermöglicht die Überprüfung aller Typen zur Kompilierungszeit, sodass keine impliziten Umwandlungen stattfinden. Die späte Bindung prüft die Typen, wenn eine Aktion ausgeführt wird. Für die Entitätsklasse müssen Typen explizit angegeben werden, um implizite Umwandlungen zu verhindern.

Spät gebunden

Wenn Sie den spät gebundenen Stil verwenden, verwenden Sie die Entitätsklasse direkt, ohne dass Klassen für Ihr spezifisches Datenmodell generiert werden müssen. Der Zugriff auf Spalten einer Datenzeile (Entität) wird mit dem logischen Namen der Spalte durchgeführt. Dadurch kann für Code, dem möglicherweise nicht alle Spalten im Voraus bekannt sind, Flexibilität geboten werden. Er profitiert jedoch nicht von der Typprüfung und der Intellisense-Hilfe, die der früh gebundene Stil bereitstellt.

Im Folgenden finden Sie einen beispielhaften Code dazu, wie der spät gebundene Stil verwendet wird:

    Entity newAccount = new Entity("account");
    newAccount["name"] = "Fourth Coffee";
    newAccount["revenue"] = new Money(new decimal(5000000.00)); //Currency column
    newAccount["accountcategorycode"] = new OptionSetValue(1);  //Preferred customer choice column

Früh gebunden

Wenn Sie den Stil der frühen Bindung verwenden, arbeiten Sie direkt mit einer generierten Klasse, die für die Dataverse-Tabelle spezifisch ist, auf die Sie zugreifen. Die generierte Klasse erbt von der Entitätsklasse und verfügt über generierte Eigenschaften für jede Spalte in der Dataverse-Tabelle. Dieser Ansatz kann dazu beitragen, dass die Produktivität verbessert wird, da die Typprüfung zur Kompilierungszeit erfolgt und Sie von Visual Studio-IntelliSense profitieren können.

Im Folgenden finden Sie einen beispielhaften Code dazu, wie der früh gebundene Stil verwendet wird:

    var newAccount = new Account());
    newAccount.Name = "Fourth Coffee";
    newAccount.Revenue = new Money(new decimal(5000000.00)); //Currency column
    newAccount.AccountCategoryCode"] = new OptionSetValue(1);  //Preferred customer choice column

Es gibt mehrere Optionen, um die Klassen zu generieren, die neueste Option ist das Verwenden von Power Platform-CLI. Der folgende Code zeigt, wie der Befehl CLI-Modelbuilder verwendet wird, um Klassen für die Konto‑ und Kontakttabellen zu generieren.

pac modelbuilder build --outdirectory Models --serviceContextName ContosoServiceContext --namespace Contoso --entitynamesfilter "account;contact"

Da alle generierten Klassen von der Entität erben, können Sie die beiden Stile in Ihrem Code kombinieren.