Benutzerdefinierte virtuelle Entitätsdatenanbieter

  • Artikel

Durch Verwenden von Dynamics 365 for Customer Engagement (on-premises) Data SDK haben .NET-Entwickler die Möglichkeit zum Erstellen benutzerdefinierter virtueller Entitätsdatenanbieter, um externe Datenquellentypen zu kennen, die nicht von einem vorhandenen Datenanbieter unterstützt werden. Jeder Datenanbieter besteht aus einem wiederverwendbaren Satz von Dynamics 365 for Customer Engagement (on-premises)-Plugins, die die unterstützten CRUD-Vorgänge implementieren. (Die erste Version ist auf die Lesevorgänge Retrieve und RetrieveMultiple beschränkt.) Dieser Abschnitt enthält grundlegende Informationen über Datenanbieter und Ansätze zur Entwicklung angepasster Anbieter, einschließlich Beispielcode.

Notiz

Alternativ zum Erstellen eines benutzerdefinierten Datenquellenanbieters, sollten Sie erwägen, die Datenquelle an einen vorhandenen Datenanbieter anzupassen. Wenn Sie z. B. eine Schnittstelle von ODatas v4 zur externen Datenquelle erstellen, dann können Sie auf sie mit dem angegebenen Standard-Datenanbieter ODatas v4 direkt zugreifen. Die Funktion zum Hinzufügen dieser REST-Schnittstelle variiert nach der zugrunde liegenden Datendiensttechnologie, beispielsweise WCF Data Services 4.5. OData hat breiten Branchesupport, mit einer breiten Palette von dedizierten von Tools und kompatiblen Technologien.

Voraussetzungen

Benutzerdefinierte Datenanbieter erfordern erhebliche Entwicklungsressourcen, um sie zu erstellen und zu warten. Sie benötigen mindestens grundlegende Kenntnisse der folgenden Bereiche:

Außerdem müssen Sie das Dynamics 365 for Customer Engagement (on-premises) Data SDK manuell herunterladen oder das entsprechende NuGet Paket in Ihre Projekte aufnehmen. Das SDK ist mit Visual Studio 2015 oder 2017 kompatibel.

Kategorien von Anbietern

Es gibt zwei allgemeine Kategorien von Datenanbietern, die Sie mit den virtuellen Entitätsdaten SDK-Assemblys erstellen können: generisch oder gezielt. Die folgende Tabelle beschreibt nur diese beiden Ansätze und ordnet sie dem Datenanbieterentwicklungsmodell zu, das für diesen Ansatz bestgeeignet ist.

Kategorie Entwickler-Modell Beschreibung
Generisch "Bare Metal"-Anbieter Diese können FetchXML-Abfrageausdrücke Anbieter der zugeordneten Anforderung für externe Datenquelle flexibel übersetzen, und geben die resultierenden Entitätsinstanzen zurückgegeben. Solch ein Anbieter kann für alle Instanzen des Datenquellentyps wiederverwendet werden. Diese Methode ist am allgemeinsten, jedoch kompliziert zu entwickeln. Wenn das Schema der Datenquelle geändert wird, müssen die betroffenen virtuellen Entitäten nur neu zugeordnet werden.
Ausgerichtet LINQ-Anbieter für bekanntes Schema Ein solcher Anbieter übersetzt nur knapp Abfragen an den zugeordneten LINQ-Anruf an eine vertraute, vorhandene Datenquelleninstanz. Die Datenquelle sollte ein LINQ-Anbieter sein, wie in diesem Thema beschrieben Aktivieren einer Datenquelle für LINQ-Abfragen. Diese Methode ist auf eine bestimmte Datenquelleninstanz eingeschränkt, es ist aber wesentlich weniger Codierung erforderlich. Wenn das Schema der Datenquelle geändert wird, muss der Datenanbieter aktualisiert und neu erstellt werden.

Der Standard-Odata v4-Datenanbieter und der Cosmos DB-Datenanbieter sind Beispiele für generische Anbieter.

Schritte, um einen benutzerdefinierten Datenanbieter zu verwenden

Es gibt mehrere Schritte, die erforderlich sind, um eine virtuelle Entitätsdaten-Provider-Lösung zu erstellen, die in Ihre Dynamics 365 for Customer Engagement (on-premises) importiert werden kann:

  1. Entwickeln des benutzerdefinierten Datenanbieter-Pug-Ins in DLL (oder ein Satz von DLLs).
  2. Registrieren des benutzerdefinierten Datenanbieters in Ihrem Dynamics 365 for Customer Engagement (on-premises)-Service unter Verwendung des Plug-In-Registrierungstools (PRT).
  3. Erstellen einer Datenanbieterlösung.
  4. Anpassen der Datenquellenentität, um einen Typ oder besondere Instanz widerzuspiegeln.
  5. Exportieren Sie die benutzerdefinierte Datenanbieterlösung.

Plug-In-Entwicklung

Da virtuelle Entitäten in dieser Version schreibgeschützt sind, schreiben Sie den Datenanbieter in Form eines Plug-Ins, das auf Abrufen und RetrieveMultiple-Ereignissen registriert ist. Jedes jeweilige Ereignis enthält Informationen im Ausführungskontext, die die Art von Daten beschreiben, die zurückzugeben sind.

Ereignis Ausführungskontext
Abrufen Beschreibt, welche Entität abzurufen sind sowie die Attribute alle verknüpften Entitäten, die einzuschließen sind.
RetrieveMultiple Enthält ein QueryExpression-Objekt, das die Abfrage definiert. Das Framework enthält eine QueryExpressionVisitor-Klasse, die dazu konzipiert ist, um verschiedene Teile der Abfrageausdruckstruktur zu überprüfen.

Für beide Ereignisse müssen Sie:

  1. Konvertieren Sie die entsprechenden Informationen im Ausführungskontext in eine Abfrage, die für Ihre externe Datenquelle funktioniert.
  2. Abrufen von Daten aus dem externen System.
  3. Für Abrufen konvertieren Sie Daten in eine Entität; andernfalls, für RetrieveMultiple, konvertieren Sie sie in eine EntityCollection. Das Ergebnis wird mithilfe der Dynamics 365 Customer Engagement (on-premises)-Plattform dem Benutzer zurückgegeben, der die Abfrage ausführt.

Die Klassen im Microsoft.Xrm.Sdk.Data-Namespace enthalten ein Framework, das Sie verwenden können, um die Dynamics 365 Customer Engagement (on-premises) Abfrageinformationen im Ausführungskontext in einer Abfrage in dem Format zuzuordnen, das für die externe Datenquelle geeignet ist. Dieses Framework hilft Ihnen, die Daten zu konvertieren, die zu den entsprechenden Entität oder EntityCollection-Typen zurückgegeben werden, die von der Dynamics 365 Customer Engagement (on-premises) Plattform erwartet wird.

Datenanbieterausnahmen

Wenn aus irgendeinem Grund Ihr Code nicht das erwartete Ergebnis erzielen kann, müssen Sie den entsprechenden Fehler auslösen. Der Microsoft.Xrm.Sdk.Data.Exceptions-Namespace enthält die folgenden Ausnahmeklassen, die von dem SdkExceptionBase abgeleitet sind, das Sie für diesen Zweck verwenden können:

Ausnahme-Klasse Beschreibung
AttributeNotFoundException Die Abfrage gibt ein Attribut an, das nicht in dem zugeordneten externen Datensatz gefunden wurde. Tritt in der Regel als Ergebnis der fehlerhaften Typzuordnung oder einer externen Datenquellenschemaänderung auf.
AuthenticationException Ein Fehler ist bei der Sicherheitsauthentifizierung für den externem auf Datenquellenservice aufgetreten, z. B. HTTP-Status 401 wird von externe Datenservice erhalten. Tritt in der Regel auf, weil der aktuelle Benutzer nicht die erforderlichen Rechte hat, oder die zugeordneten Informationen in EntityDataSource sind falsch.
EndpointException Die Endpunktkonfiguration in der Datenquellenentität ist ungültig oder der Endpunkt ist nicht vorhanden.
EntityNotFoundException Die Abfrage zielt auf eine Entität, die nicht vorhanden ist. Tritt in der Regel als Ergebnis der fehlerhaften Typzuordnung oder einer externen Datenquellenschemaänderung auf.
GenericDataAccessException Ein allgemeiner Datenzugriffsfehler ist aufgetreten, wird verwendet, wenn der Fehler nicht einer bestimmteren Ausnahme zugeordnet ist.
InvalidMetadataException
InvalidQueryException Die angegebene Abfrage ist ungültig; beispielsweise eine ungültige die Klauselkombination oder ein nicht unterstützter Vergleichsoperator.
ObjectNotFoundException Der angegebene Datensatz in der externen Datenquelle ist nicht vorhanden.
TimeoutException Der externe Vorgang wurde nicht in der angegeben Zeit abgeschlossen; z. B. das Ergebnis eines HTTP-Status 408 des externen Datenservices.

Plug-In-Registrierung

Im Gegensatz zu gewöhnliches ein Plug-In verwenden Sie die Plugin Registration Tool (PRT), um die Assembly und Plug-Ins die für jedes Ereignis zu registrieren. Sie registrieren nicht bestimmte Schritte. Ihr Plug-In wird ausgeführt in der Phase 30, der Hauptkerntransaktionsphase für den Vorgang, die nicht für gewöhnliche Plugin-Schritte verfügbar ist. Statt Schritte zu registrieren, konfigurieren Sie die Datenanbieteranwendung mit den Entitäten Microsoft.Dynamics.CRM.EntityDataProvider und Microsoft.Dynamics.CRM.EntityDataSource.

Entität Beschreibung
EntityDataProvider Definiert die Plug-Ins, die für jedes Ereignis verwendet werden und den logischen Namen der Datenquelle.
EntityDataSource Stellt den Entitätskontext und alle Verbindungsinformationen zur Verfügung, die für externe die Datenquelle erforderlich sind, einschließlich aller geheimen Informationen, die nötig sind, um sich zu authentifizieren.

Wenn die Metadaten für Ihre virtuelle Entität konfiguriert werden, werden die Plug-Ins mithilfe des PRT registriert und die richtigen Konfigurationsdaten in EntityDataProvider und EntityDataSource festgelegt sind, beginnt die virtuelle Entität, auf Anforderungen zu reagieren.