Grundlegende Vorgänge mit dem Organisationsdienst durchführen

10 Minuten

In dieser Lerneinheit untersuchen wir die grundlegenden Vorgänge, bei denen der Organisationsdienst zur Interaktion mit Daten aus einer Dataverse-Umgebung verwendet wird.

Eine Zeile erstellen

Verwenden Sie die Methode Erstellen, um Zeilen zu erstellen. Es ist am besten, für die primäre Spalte der Tabelle mindestens einen Wert anzugeben, obwohl dies nicht erforderlich ist. Der Erstellungsvorgang weist der neuen Zeile einen GUID-Wert als Primärschlüssel zu. Es wird für die meisten Szenarios empfohlen, die automatische Zuweisung zuzulassen, obwohl dies zur Bereitstellung Ihres eigenen Werts unterstützt wird.

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

Sie können im gleichen Vorgang verwandte Zeilen erstellen, indem Sie die Eigenschaft RelatedEntities verwenden. Dafür ist es erforderlich den Namen der Beziehung und das zugehörig Entitätsobjekt anzugeben, das gleichzeitig zu erstellen ist. Im folgenden Beispiel werden die Konto‑ und Kontaktzeilen beide in einer einzigen Transaktion erstellt und mit der angegebenen Beziehung miteinander verknüpft.

Entity newAccount = new Entity("account");
newAccount["name"] = "Contoso";

Entity newContact = new Entity("contact");
newContact["firstname"] = "Jim";
newContact["lastname"] = "S";

newAccount.RelatedEntities.Add(new Relationship("account_primary_contact"),
    new EntityCollection(new List<Entity>() { newContact }));

Guid accountid = serviceClient.Create(newAccount);

Zeilen aktualisieren

Mit der Methode Aktualisieren können Sie eine Zeile aktualisieren. Verwenden Sie den Primär‑ oder den Alternativschlüssel, um Tabellenzeilen zu aktualisieren. Beim Aktualisieren einer Zeile sollten Sie nur die Spalten angeben, für die Daten angepasst werden sollen. Wenn das Entitätsobjekt unveränderte Spalten enthält, löst Dataverse jede Automatisierung aus, die auf die Anpassung dieser Spalten wartet, auch wenn sich der Wert nicht geändert hat. Im Folgenden finden Sie ein Beispiel der Aktualisierung mit dem Primärschlüssel, bei dem es sich um eine GUID handelt.

Entity updateAccount = new Entity("account",accountid);
updateAccount["accountnumber"] ="ABC123";
updateAccount["creditlimit"] = new Money(1000);

serviceClient.Update(updateAccount);

Sie können jedoch auch einen Alternativschlüssel verwenden, um eine Tabellenzeile zu aktualisieren. Sie müssen den Alternativschlüssel in der Tabelle definieren, bevor dies funktioniert. Im Folgenden wird die Kontotabellenzeile aktualisiert. Dazu wird die Kontonummer verwendet, die wir während der vorherigen Aktualisierung festgelegt haben.

Entity updateAccount = new Entity("account","accountnumber", "ABC123");
updateAccount["creditlimit"] = new Money(2300);
serviceClient.Update(updateAccount);

Sie haben zudem die Möglichkeit, KeyAttributeCollection zu verwenden, um mehrere Spalten bereitzustellen, die einen Alternativschlüssel bilden.

KeyAttributeCollection updateKeys = new KeyAttributeCollection
{
    { "name", "Contoso" },
    { "accountnumber", "Contoso123A" }
};
Entity updateAccount = new Entity("account", updateKeys);
updateAccount["creditlimit"] = new Money(5000);

serviceClient.Update(updateAccount);

Zeilen löschen

Verwenden Sie die Methode Löschen, um eine Zeile zu löschen. Verwenden Sie den Primär‑ oder den Alternativschlüssel, um eine Tabellenzeile zu löschen. Der folgende Code zeigt den einfachsten Löschvorgang mit dem Primärschlüssel an.

serviceClient.Delete("account", accountid);

Verwenden Sie zum Löschen mit einen Alternativschlüssel die Methode „Execute“ für die Nachricht „DeleteRequest“. Der folgende Code zeigt das Löschen einer Kontozeile mit einem bestimmten Alternativschlüssel für die Spalte Kontonummer.

var deleteRequest = new DeleteRequest
{
    Target = new EntityReference("account", "accountnumber", "Contoso123A")
};

serviceClient.Execute(deleteRequest);

Eine einzelne Zeile abrufen

Verwenden Sie die Methode Retrieve, um eine Zeile abzurufen. Verwenden Sie den Primär‑ oder den Alternativschlüssel, um eine Tabellenzeile abzurufen. Das folgende Codebeispiel zeigt den einfachsten Abrufvorgang mit dem Primärschlüssel an.

var retrieveAccount = serviceClient.Retrieve("account", accountid,
    new ColumnSet("name", "accountnumber", "creditlimit"));

Verwenden Sie zum Löschen mit einen Alternativschlüssel die Methode „Execute“ für die Nachricht „RetrieveRequest“. Das folgende Codebeispiel zeigt das Abrufen einer Kontozeile mit einem bestimmten Alternativschlüssel für die Spalte Kontonummer.

var altRetrieveKey = new EntityReference("account", "accountnumber",accountNumber);
var retrieveRequest = new RetrieveRequest
{
    Target = altRetrieveKey,
    ColumnSet = new ColumnSet("name", "accountnumber", "creditlimit")
};
var retrieveResult = (RetrieveResponse)serviceClient.Execute(retrieveRequest);

Mehrere Zeilen abrufen

Verwenden Sie die Methode RetrieveMultiple, um mehrere Zeilen aus einer Tabelle abzurufen, die Ihren Kriterien entsprechen. Es gibt mehrere Möglichkeiten, wie Sie die Abfragekriterien für welche Zeilen aus einer Tabelle oder aus Tabellen von Dataverse erstellen können. Jede Option bietet Vorteile, je nachdem welches Abfrageszenario vorliegt. Im Folgenden finden Sie die wichtigsten Optionen, die Sie mit der RetrieveMultiple-Methode verwenden können:

QueryExpression – Stark typisiertes Objektmodell zum Erstellen komplexer Abfragen, umfasst Daten aus verknüpften (verwandten) Zeilen, unterstützt jedoch keine Aggregationen und Gruppierungen.
QueryByAttribute – Einfacheres Modell als QueryExpression, hilfreich zum Abgleichen der Wertkriterien einer einzelnen Tabellenspalte, kann aber nur Daten aus einer einzelnen Tabelle zurückgeben.
FetchExpression – Verwenden Sie die Dataverse FetchXML-Abfragesprache, und ermöglichen Sie komplexe Abfragen mit Aggregationen, Gruppierungen und Dateneinschluss aus verknüpften (zugehörigen) Tabellenzeilen.
LINQ – Erfasst Abfragen mit der LINQ-Syntax, wobei die Funktionen wie bei QueryExpression beschränkt sind.

In den folgenden Beispielen sehen Sie für jede Option die gleichen Kriterien. Die Kriterien fragen die Kontotabelle ab, in der die Stadt Redmond ist, und geben die Spalten City und Line 1/2 of address1 zurück.

QueryExpression-Beispiel

var queryExpression = new QueryExpression("account")
{
    ColumnSet = new ColumnSet("address1_city", "address1_line1", "address1_line2"),
    Criteria = new FilterExpression
    {
        Conditions =
        {
            new ConditionExpression("address1_city", ConditionOperator.Equal, "Redmond")
        }
    }
};
EntityCollection queryExpressionResults = serviceClient.RetrieveMultiple(queryExpression);

QueryByAttribute-Beispiel

var queryByAttribute = new QueryByAttribute("account")
{
    ColumnSet = new ColumnSet("address1_city", "address1_line1", "address1_line2"),
    Attributes = { "address1_city" },
    Values = { "Redmond" }
};
EntityCollection queryByAttributeResults = serviceClient.RetrieveMultiple(queryByAttribute);

FetchExpression-Beispiel

var fetchXml = @"
<fetch version='1.0' output-format='xml-platform' mapping='logical' distinct='false'>
  <entity name='account'>
    <attribute name='address1_city' />
    <attribute name='address1_line1' />
    <attribute name='address1_line2' />
    <filter type='and'>
      <condition attribute='address1_city' operator='eq' value='Redmond' />
    </filter>
  </entity>
</fetch>";

var fetchExpression = new FetchExpression(fetchXml);
EntityCollection fetchResults = serviceClient.RetrieveMultiple(fetchExpression);

LINQ-Beispiel

var context = new OrganizationServiceContext(serviceClient);

var linqQuery = from acc in context.CreateQuery("account")
                where (string)acc["address1_city"] == "Redmond"
                select new
                {
                    Address1_City = (string)acc["address1_city"],
                    Address1_Line1 = (string)acc["address1_line1"],
                    Address1_Line2 = (string)acc["address1_line2"]
                };

var linqResults = linqQuery.ToList();

Weiter