Nachrichten mit dem SDK für .NET verwenden

  • Artikel

Es ist wichtig zu verstehen, dass alle Datenvorgänge in Dataverse als Nachrichten definiert sind und die Definitionen dieser Nachrichten in Dataverse gespeichert werden.

Jede Nachricht verfügt über Folgendes:

  • Einen eindeutigen Namen
  • Eine Sammlung an Eingabeparametern
  • Eine Sammlung an Ausgabeparametern

Es gibt drei verschiedene Möglichkeiten, wie Sie eine Nachricht mit dem SDK für .NET verwenden können. Dieser werden in den folgenden Abschnitten erklärt:

Methode Beschreibung
OrganizationRequest- und OrganizationResponse-Klassen Verwenden Sie diese Klassen, wenn Sie keine SDK-Anforderungs- und Antwortklassen haben. Möglicherweise verwenden Sie lieber diesen Ansatz, anstatt SDK-Anforderungs- und Antwortklassen zu generieren, wenn Sie den Nachrichtennamen und die Details der Eingabe- und Ausgabeparameter kennen.
SDK-Anforderungs- und Antwortklassen Die Verwendung dieser Klassen ist die häufigste Art, Nachrichten zu verwenden. Für viele Nachrichten sind bereits Klassen im SDK für .NET festgelegt. Für benutzerdefinierte Aktionen können Sie Klassen generieren.
IOrganizationService-Methoden Der IOrganizationService bietet einige Methoden für allgemeine Datenvorgänge. Diese Methoden sind die schnellste und einfachste Möglichkeit, die gängigsten Datenvorgänge auszuführen.

OrganizationRequest- und OrganizationResponse-Klassen

Hinweis

Die Verwendung der OrganizationRequest- und OrganizationResponse-Klassen ist nicht die üblichste Methode, wie Nachrichten in Dataverse verwendet werden. Diese Klassen demonstrieren jedoch, wie Nachrichten implementiert werden. Dies zu verstehen ist wichtig, um zu verstehen, wie andere Teile von Dataverse funktionieren.

Sie können eine Nachricht ohne SDK-Anforderungs- und Antwortklassen verwenden.

  1. Verwenden Sie die OrganizationRequest-Klasse.

  2. Senden Sie die Anforderung mit der IOrganizationService.Execute-Methode, die eine OrganizationResponse-Instanz zurückgibt.

    Die Elemente in der Sammlung OrganizationResponse.Results enthalten die Ergebnisse.

Wenn Sie beispielsweise einen Firmendatensatz erstellen möchten, können Sie dies folgendermaßen tun:

public static Guid OrganizationRequestExample(IOrganizationService service) {

   // Instantiate an Entity instance of type 'account'
    var account = new Entity("account");
    account["name"] = "Test account";

   // Instantiate a collection of parameters with one item 'Target',
   // set to the account entity instance
    ParameterCollection parameters = new ParameterCollection
    {
        { "Target", account }
    };

   // Instantiate an OrganizationRequest instance setting the
   // RequestName and Parameters
    OrganizationRequest request = new OrganizationRequest()
    {
        RequestName = "Create",
        Parameters = parameters
    };

   // Send the request using the IOrganizationService.Execute method
    OrganizationResponse response = service.Execute(request);

   // Parse the output parameter 'id' from the Results
    return (Guid)response.Results["id"];
}

Um einen Firmendatensatz mit dieser Methode zu erstellen, müssen Sie Folgendes kennen:

  • Den Namen der Nachricht: Create.
  • Name und Datentyp aller Eingabeparameter: Ein einzelner Parameter mit dem Namen Target, der eine Entität ist.
  • Name und Datentyp aller Ausgabeparameter: Ein einzelner Parameter mit dem Namen id, der eine GUID ist.

Diese Informationen werden in Dataverse gespeichert. Die SdkMessage-Tabelle enthält Informationen zu allen Nachrichten.

Dataverse verwaltet Informationen über die Eingabe- und Ausgabeparameter in privaten Tabellen. Sie müssen es nicht abrufen, da es einen einfacheren Weg gibt: die Verwendung der SDK-Anforderungs- und Antwortklassen.

SDK-Anforderungs- und Antwortklassen

SDK-Anforderungs- und Antwortklassen reduzieren die Komplexität der Verwendung der OrganizationRequest- und OrganizationResponse-Klassen. Sie müssen den Namen der Nachricht sowie die Eingabe- und Ausgabeparameter nicht kennen, da diese in den Klassen enthalten sind.

Das SDK für .NET enthält Definitionen für allgemeine Dataverse-Nachrichten in diesen Namespaces:

Namespace Beschreibung
Microsoft.Xrm.Sdk.Messages Nachrichten für allgemeine Datenvorgänge und Nachrichten zum Erstellen und Ändern von Schemadaten, die auch als Metadaten bezeichnet werden.
Microsoft.Crm.Sdk.Messages Nachrichten für Geschäftslogik und Vorgänge zur Unterstützung spezieller Funktionen zur Unterstützung von Application Lifecycle Management (ALM) und Apps. Einige Nachrichten in diesem Namespace unterstützen Funktionen, die nur in Microsoft Dynamics 365-Geschäftsanwendungen zu finden sind.

Diese Klassen enthalten Eigenschaften für alle Eingabe- und Ausgabeparameter.

  • Die Klassen, die mit *Request enden, enthalten die Eigenschaften für Eingabeparameter.

    Diese Klassen erben von der OrganizationRequest-Klasse.

  • Die Klassen, die mit *Response enden, enthalten die Eigenschaften für Ausgabeparameter.

    Diese Klassen erben von der OrganizationResponse-Klasse.

Um beispielsweise einen Datensatz zu erstellen, können Sie die Klasse Microsoft.Xrm.Sdk.Messages.CreateRequest verwenden, um die Anforderung vorzubereiten. Verwenden Sie IOrganizationService.Execute, um die Anforderung zu senden, und die Ergebnisse liegen in Form einer Microsoft.Xrm.Sdk.Messages.CreateResponse-Klasseninstanz vor.

Im folgenden Beispiel wird die Klasse Microsoft.Xrm.Sdk.Messages.CreateRequest mit einer generierten Klasse mit früher Bindung für die Kontoentität verwendet:

public static Guid CreateRequestExample(IOrganizationService service)
{
    // Instantiate an Account using generated early-bound class
    var account = new Account
    {
        Name = "Test account"
    };

    // Instantiate a CreateRequest
    var request = new CreateRequest
    {
        // Set the Target property
        Target = account
    };

    // Send the request using the IOrganizationService.Execute method
    // Cast the OrganizationResponse into a CreateResponse
    var response = (CreateResponse)service.Execute(request);

    // Return the id property value
    return response.id;
}

Generierte Klassen für benutzerdefinierte Aktionen

Es gibt andere Nachrichten, die keine Klassen im SDK haben. Beispielsweise enthalten installierte Lösungen häufig neue Nachrichtendefinitionen, die als benutzerdefinierte Aktionen (benutzerdefinierte API- oder benutzerdefinierte Prozessaktionen) definiert sind. Informationen zum Erstellen eigener Nachrichten

Entwickler können *Request- und *Response-Klassen für die in ihrer Umgebung gefundenen Nachrichten mithilfe des Power Platform CLI-Befehls „pac modelbuilder build“ generieren. Benutzen Sie den Parameter --generateActions, um *Request- und *Response-Klassen zu generieren. Weitere Informationen über das Generieren von Klassen mit früher Bindung für das SDK für .NET

Übergeben optionaler Parameter mit einer Anfrage

Es gibt mehrere optionale Parameter, die Sie übergeben können, um spezielle Verhalten auf Meldungen anzuwenden. Sie können die IOrganizationService-Methoden nicht verwenden, wenn Sie optionale Parameter nutzen. Sie müssen die SDK-Anforderungsklassen oder die OrganizationRequest-Klasse verwenden.

Mehr Informationen: Optionale Parameter verwenden

IOrganizationService-Methoden

In Ergänzung zu IOrganizationService.Execute-Methode, die IOrganizationService-Schnittstelle gibt an, dass die folgenden Methoden ebenfalls implementiert werden müssen. Diese Methoden kapseln die entsprechenden Anforderungs- und Antwortklassen:

Methode Anforderungs-/Antwortklassen
Create CreateRequest / CreateResponse
Retrieve RetrieveRequest / RetrieveResponse
RetrieveMultiple RetrieveMultipleRequest / RetrieveMultipleResponse
Update UpdateRequest / UpdateResponse
Delete DeleteRequest / DeleteResponse
Associate AssociateRequest / AssociateResponse
Disassociate DisassociateRequest / DisassociateResponse

Diese Methoden vereinfachen die Ausführung dieses Vorgangs mit weniger Codezeilen. Das folgende Beispiel verwendet die IOrganizationService.Create-Methode, um einen Firmendatensatz zu erstellen:

public static Guid CreateMethodExample(IOrganizationService service)
{
   // Instantiate an Account using generated early-bound class
    var account = new Account
    {
        Name = "Test account"
    };

    // Use the Create method to get the id of the created account.
    return service.Create(account);
}

Wie Sie sehen, werden allgemeine Datenvorgänge mithilfe der IOrganizationService-Methoden optimiert, und andere Nachrichten können mit den Request- und Response-Klassen in den SDK-Assemblys einfacher verwendet oder mit Tools generiert werden. In den meisten Fällen müssen Sie die zugrundeliegenden OrganizationRequest- und OrganizationResponse-Klassen nicht verwenden, aber es ist wichtig, die verschiedenen verfügbaren Optionen zur Verwendung von Nachrichten zu verstehen, insbesondere wenn Sie mit benutzerdefinierten APIs und Plug-Ins arbeiten.

Arbeiten mit Nachrichten in Plug-Ins

Die Daten, die einen Vorgang in einem Plug-In beschreiben, haben die Form IExecutionContext.InputParameters und IExecutionContext.OutputParameters.

In den PreValidation- und PreOperation-Phasen vor dem main-Vorgang der Ereignispipeline enthalten die IExecutionContext.InputParameters die OrganizationRequest.Parameters.

Mit einer benutzerdefinierten API liest Ihr Plug-In die IExecutionContext.InputParameters und enthält Logik zum Festlegen der IExecutionContext.OutputParameters im Rahmen der main-Vorgangsphase.

Nach der main-Phase des Vorgangs enthalten die IExecutionContext.OutputParameters die OrganizationResponse.Results in der PostOperation-Phase.

Wenn Sie die Struktur der Meldungen verstehen, erkennen Sie auch, wo Sie die Daten finden, die Sie innerhalb des Plug-Ins prüfen oder ändern möchten.

Weitere Informationen:

Private Nachrichten

Microsoft Dataverse enthält einige Nachrichten, die nicht für Nicht-Microsoft-Entwickler vorgesehen sind. Microsoft hat diese Nachrichten hinzugefügt, um die Funktion zu aktivieren, aber auch Nicht-Microsoft-Lösungen können sie über die Custom-API-Funktion hinzufügen. Die Eigenschaft SdkMessage.IsPrivate sagt Ihnen, welche Meldungen privat sind.

Achtung

Sie sollten keine privaten Nachrichten verwenden, es sei denn, Sie haben sie als Custom-API erstellt. Durch das Markieren einer Nachricht als privat weist der Lösungsherausgeber ausdrücklich darauf hin, dass andere Apps zur Verwendung der Nachricht nicht unterstützt werden. Sie können die Nachricht jederzeit entfernen oder wichtige Änderungen vornehmen. Die Verwendung dieser Nachrichten durch andere Personen als den Lösungsherausgeber wird nicht unterstützt. Das Aufrufen von privaten Nachrichten aus Plug-ins wird nicht unterstützt.

Weitere Informationen: Custom-APIs erstellen und verwenden

Unterstützung von Tabellen für Nachrichten

Einige Nachrichten können mit mehreren Tabellen verwendet werden. Die Create-, Update- und Delete-Nachrichten können zum Beispiel für die meisten Tabellen verwendet werden, aber einige Tabellen unterstützen möglicherweise nicht alle allgemeinen Nachrichten.

Diese Informationen werden in der SdkMessageFilter-Tabelle gespeichert. Sie können diese Tabelle abfragen, um festzustellen, ob Sie eine Nachricht für eine Tabelle verwenden können.

Verwenden Sie diese statische Methode, um eine Liste mit Namen von Nachrichten zu erhalten, die mit einer Tabelle arbeiten können:

/// <summary>
/// Write the names of messages for a table to the console
/// </summary>
/// <param name="service">The authenticated IOrganizationService to use</param>
/// <param name="tableName">The logical name of the table</param>
static void OutputTableMessageNames(IOrganizationService service, string tableName)
{
    var query = new QueryExpression(entityName: "sdkmessagefilter")
    {
        Criteria =
        {
            Conditions =
            {
                new ConditionExpression(
                    attributeName:"primaryobjecttypecode",
                    conditionOperator: ConditionOperator.Equal,
                    value: tableName)
            }
        },
        // Link to SdkMessage to get the names
        LinkEntities =
        {
            new LinkEntity(
                linkFromEntityName:"sdkmessagefilter",
                linkToEntityName: "sdkmessage",
                linkFromAttributeName: "sdkmessageid",
                linkToAttributeName: "sdkmessageid",
                joinOperator: JoinOperator.Inner)
            {
                EntityAlias = "sdkmessage",
                Columns = new ColumnSet("name"),
                LinkCriteria =
                {
                    Conditions =
                    {
                        // Don't include private messages
                        new ConditionExpression("isprivate", ConditionOperator.Equal, false)
                    }
                }
            }
        }
    };

    EntityCollection results = service.RetrieveMultiple(query);

        foreach (var entity in results.Entities)
        {
            Console.WriteLine(((AliasedValue)entity["sdkmessage.name"]).Value);
        }
}

Wenn Sie diese Methode verwenden und den Parameter tableName auf account setzen, erhalten Sie Ergebnisse, die diese Nachrichtennamen enthalten:

Ausgabe:

Assign
Create
Delete
GrantAccess
Merge
ModifyAccess
Retrieve
RetrieveMultiple
RetrievePrincipalAccess
RetrieveSharedPrincipalsAndAccess
RevokeAccess
SetState
SetStateDynamicEntity
Update

Hinweis

Einige dieser Nachrichten sind veraltet. SetState und SetStateDynamicEntity sind noch vorhanden, aber Sie sollten stattdessen Update verwenden.

Unterstützung von Nachrichten für Tabellen

Einige Nachrichten können nur mit spezifischen Tabellen verwendet werden. Beispielsweise können Sie die RetrieveUnpublishedMultiple-Nachricht nur mit einem bestimmten Tabellensatz verwenden, der Daten enthält, die veröffentlicht werden können.

Diese Informationen werden in der SdkMessageFilter-Tabelle gespeichert. Sie können diese Tabelle abfragen, um festzustellen, welche Tabellen für eine spezifische Nachricht verwendet werden können.

Verwenden Sie diese statische Methode, um eine Liste mit Namen von Tabellen zu erhalten, die mit einer Nachricht verwendet werden können.

/// <summary>
/// Write the names of tables for a message to the console
/// </summary>
/// <param name="service">The authenticated IOrganizationService to use</param>
/// <param name="messageName">The name of the message</param>
static void OutputTablesForMessage(IOrganizationService service, string messageName) {

    var query = new QueryExpression(entityName: "sdkmessage")
    {
        Criteria = { 
            Conditions =
            {
                new ConditionExpression(
                        attributeName: "name",
                        conditionOperator: ConditionOperator.Equal,
                        value: messageName)
            }
        },
        LinkEntities = {
            new LinkEntity(
                linkFromEntityName:"sdkmessage",
                linkToEntityName: "sdkmessagefilter",
                linkFromAttributeName: "sdkmessageid",
                linkToAttributeName: "sdkmessageid",
                joinOperator: JoinOperator.Inner)
            {
                EntityAlias = "sdkmessagefilter",
                Columns = new ColumnSet("primaryobjecttypecode"),
            }
        }
    };

            EntityCollection results = service.RetrieveMultiple(query);
            List<string> names = new List<string>();

            foreach (var entity in results.Entities)
            {
                names.Add(((AliasedValue)entity["sdkmessagefilter.primaryobjecttypecode"]).Value as string);
            }

            names.Distinct().ToList().ForEach(name => Console.WriteLine(name));
}

Wenn Sie diese Methode verwenden und den Parameter messageName auf RetrieveUnpublishedMultiple setzen, erhalten Sie Ergebnisse, die diese Tabellennamen enthalten:

Ausgabe:

organizationui
systemform
savedquery
savedqueryvisualization
sitemap
hierarchyrule
appmodule
appconfig
appconfiginstance
webresource
mobileofflineprofile
mobileofflineprofileitem
mobileofflineprofileitemassociation
navigationsetting
appelement
appsetting
teammobileofflineprofilemembership
usermobileofflineprofilemembership

Hinweis

  • Bei bestimmten Nachrichten werden möglicherweise Platzhalterwerte zurückgegeben, z. B. DeletedEntity for objectTypeCode=11478 oder new_system_donotuseentity_rp53fd1p1ekxpa_t12_b71d6344c5. Dies sind keine gültigen Tabellennamen. Ignorieren Sie diese Werte.

  • Diese Abfrage gibt auch private Tabellen zurück. Im vorherigen Beispiel: organizationui,hierarchyrule, appelement und appsetting sind private Tabellen und werden für die Verwendung nicht unterstützt.

Siehe auch

Tabellenvorgänge mithilfe des SDK für .NET
Verwenden von ExecuteAsync zum asynchronen Ausführen von Messages
Führt Nachrichten in einer einzelnen Datenbanktransaktion aus.
Mehrere Anforderungen mit dem SDK für .NET ausführen

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