Verwenden von OrganizationServiceContext

  • Artikel

In Microsoft Dataverse können Sie mehrere Klassen, die die Schnittstelle IOrganizationService implementieren, für den Zugriff auf die Webdienste verwenden. Alternativ können Sie den OrganizationServiceContext durch das Power Platform CLI Pac Modellerstellungs-Buildbefehl verwenden, um Zugriff auf zusätzliche Funktionen zu erhalten. Durch die OrganizationServiceContext-Klasse können Sie Änderungen nachverfolgen, Identitäten und Beziehungen verwalten und auf den LINQ-Anbieter zugreifen. Diese Klasse enthält eine OrganizationServiceContext.SaveChanges() Methode, die Sie verwenden können, um die Änderungen an den Daten zu übermitteln, die der Kontext nachverfolgt. Diese Klasse basiert auf dem gleichen Konzept wie die DataServiceContext-Klasse im Windows Communication Foundation (WCF) Data Services.

Um diese Klasse zu generieren, stellen Sie einen Wert für den --serviceContextName Parameter bereit, wenn Sie Typen mit früher Bindung generieren. Der Power Platform CLI pac Modellerstellungs-Buildbefehl verwendet diesen Namen als den Namen der generierten Klasse. Weitere Informationen zur Verwendung des pac modelbuilder build Befehles finden Sie unter Klassen für die früh gebundene Programmierung mithilfe von SDK für .NET verwenden. Sie können die Kontextinstanz verwenden, wenn Sie Anwendungen, Plug-Ins und Workflowaktivitäten entwickeln.

So verwenden Sie die OrganizationServiceContext-Klasse

Um die Kontextklasse zu instanziieren, müssen Sie dem Klassenkonstruktor ein Objekt übergeben, das die IOrganizationService-Schnittstelle implementiert. Eine Option ist dabei, eine Instanz der CrmServiceClient-Klasse zu übergeben. Weitere Informationen zur IOrganizationService-Benutzeroberfläche finden Sie unter Organisationsservice-Benutzeroberfläche.

Das folgende Codebeispiel zeigt, wie eine neuen Instanz der Kontextklasse erstellt wird. In diesem Beispiel wurde die Kontextklasse AdventureWorksCycleServiceContext genannt, indem dieser Name mithilfe des --serviceContextName Parameters definiert wird, wenn der pac modelbuilder build Befehl ausgeführt wird.

// For early bound types to work correctly, they have to be enabled on the
// client connection. Here, _service is a reference to a ServiceClient or
// CrmServiceClient object. Those types implement IOrganizationService.
_service.EnableProxyTypes();
AdventureWorksCycleServiceContext context = new   
    AdventureWorksCycleServiceContext(_service);

Nachdem Sie die Kontextinstanz erstellt haben, können Sie damit beginnen, das Erstellen, Ändern oder Löschen von Tabellenzeilen (Entitätsdatensätzen) zu verfolgen.

Der Kontext muss jede Tabellenzeile oder Beziehung verfolgen, die Sie an Dataverse übermitteln wollen. Sie könnten z. B. eine Zeile mit einer LINQ-Abfrage abrufen und der Kontext würde diese Zeile verfolgen oder Sie könnten die OrganizationServiceContext. Attach(Entity) verwenden Methode, um den Kontext zu veranlassen, mit der Verfolgung der Zeile zu beginnen. Sie können mit Daten in einer Client-Anwendung arbeiten und neue Zeilen erstellen, verknüpfte Zeilen erstellen und vorhandene Zeilen ändern, aber Sie müssen die Methode SaveChanges für verknüpfte Zeilen aufrufen, um Änderungen an Dataverse zu übergeben.

Änderungen nachverfolgen

Um festzustellen, wie eine Tabellenzeile vom Kontext verfolgt wird, können Sie die Eigenschaft EntityState der abgeleiteten Entity-Instanz überprüfen. Sie müssen den Kontext benachrichtigen, um eine Zeile aus Dataverse zu verfolgen, indem Sie verschiedene Methoden aufrufen oder eine LINQ-Abfrage verwenden. Alle Zeilen, die von einer LINQ-Abfrage zurückgegeben werden, werden vom Servicekontext nachverfolgt.

Sie können Objekte zum Dienstkontext hinzufügen, indem Sie eine der folgenden Methoden in OrganizationServiceContext aufrufen.

Methode Verwenden
AddObject(Entity) Fügt eine Tabellenzeile zum Zeilensatz hinzu, den der Servicekontext verfolgt. Der Status der Zeile im Kontext wird auf Created gesetzt. Wenn die SaveChanges()-Methode aufgerufen wird, wird diese Zeile erstellt oder dem Server hinzugefügt.
Attach(Entity) Fügt eine Tabellenzeile zum Zeilensatz hinzu, den der Servicekontext verfolgt. Der Status der Zeile im Kontext wird auf Unchanged gesetzt. Wenn die SaveChanges()-Methode aufgerufen wird, wird diese Zeile nicht an den Server gesendet, es sei denn, ihr Status ändert sich.
CreateQuery(String) Fügt die Ergebnisse einer Abfrage dem Zeilensatz hinzu, den der Servicekontext verfolgt.

In Dataverse können Sie im Servicekontext Beziehungen zwischen Tabellenzeilen erstellen und aktualisieren. Die Navigationseigenschaften, die vom Power Platform CLI pac Modellersteller-Buildbefehls erstellt werden und sich in der früh gebundenen Klassen befinden, ermöglichen den Zugriff auf und die Änderung von zugehörigen Zeileneigenschaften und Beziehungen. Der Servicekontext muss die verwandte Zeile verfolgen, damit die verwandte Zeile zur Aktualisierung auf dem Server verfügbar ist.

Verwenden Sie die folgenden Methoden in OrganizationServiceContext, um mit verknüpften Zeilen zu arbeiten und die Zeile zum Dienstkontext hinzuzufügen:

Methode Verwenden
AddRelatedObject(Entity, Relationship, Entity) Fügt das Ziel dem Kontext hinzu. Ruft die Attach(Entity)-Methode auf der Ziel-Tabellenzeile auf und ruft dann die AddLink(Entity, Relationship, Entity)-Methode zwischen der Quellzeile und der (verwandten) Zielzeile auf.
AttachLink(Entity, Relationship, Entity) Fügt die zugehörige Zeile dem Kontext zur Verfolgung hinzu. Der Status der Zeile im Kontext wird auf Unchanged gesetzt.
AddLink(Entity, Relationship, Entity) Erzeugt eine Beziehung zwischen den Quell- und Zielzeilen. Fügt das Ziel dem Kontext hinzu. Der Status der Zielzeile im Kontext wird auf Created gesetzt.
LoadProperty(Entity, String) Lädt den verknüpften Entitätssatz, der für die angegebene Beziehung festgelegt wurde. Ermöglicht den Zugriff auf verwandte Zeilen über die Navigationseigenschaft. Rufen Sie die AddObject(Entity)-Methode für die verknüpfte Zeile auf, nachdem Sie über eine Navigationseigenschaft der übergeordneten Zeile auf die Zeile zugegriffen haben.
UpdateObject(Entity) Ändert den Status der angegebenen Zeile in der OrganizationServiceContext auf Geändert.
DeleteObject(Entity) Ändert den Status der angegebenen Zeile in der OrganizationServiceContext auf „.gelöscht“.

Beziehungszeilen für Zeilen, die Sie mit LINQ abgerufen haben, sind null, bis Sie LoadProperty(Entity, Relationship) verwenden, um sie abzurufen. Das folgende Codebeispiel zeigt, wie Sie auf Task-Zeilen zugreifen, die mit einer bestimmten Kontakt-Zeile verbunden sind.

Contact pam = context.ContactSet.Where(c => c.FirstName == "Pamela").FirstOrDefault();  
if (pam != null)  
{  
// pam.Contact_Tasks is null until you use LoadProperty  
    context.LoadProperty(pam, "Contact_Tasks");  
    Task firstTask = pam.Contact_Tasks.FirstOrDefault();  
}

Sie können die AddLink(Entity, Relationship, Entity) Methode verwenden, um Verbindungen herzustellen. Sie müssen die SaveChanges() aufrufen, bevor der Server mit den neuen Linkinformationen aktualisiert wird.

Die folgenden Codebeispiel zeigen, wie Sie eine Zuordnung zwischen einem Kontakt und einer Firma herstellen.

Relationship relationship = new Relationship("account_primary_contact");  
context.AddLink(contact, relationship, account);  
context.SaveChanges();

Änderungen speichern

Der Servicekontext hält ein Diagramm der Tabellenzeilen, die er verfolgt. Die Reihenfolge, in der der Servicekontext Tabellenänderungen verarbeitet und an den Server übermittelt, ist wichtig. Aktualisierungen von primären Tabellenzeilen werden verarbeitet, dann werden verwandte Tabellenzeilen verarbeitet. Wenn ein Wert in der primären Tabellenzeile durch die Bezugstabellenzeile gesetzt wird, wird dieser Wert beim Aktualisieren der Daten auf dem Server verwendet.

Wenn ein Fehler auftritt, wenn Entitätsinformationen gespeichert werden, wird ein neuer Ausnahmetyp, der SaveChangesResult enthalt, von der OrganizationServiceContext.SaveChanges() Methode ausgelöst, unabhängig vom Wert des SaveChangesOptions-Parameters, der an diese Methode übergeben wird.

Verwenden virtueller Methoden, wenn der Kontext geändert wird

Manchmal kann es erforderlich sein, Aktionen basierend auf Änderungen des OrganizationServiceContext auszuführen. Um dies zu erleichtern, werden virtuelle Methoden bereitgestellt, die es ermöglichen, Vorgänge abzufangen bzw. eine entsprechende Benachrichtigung zu erhalten. Um diese Möglichkeiten nutzen zu können, müssen Sie entweder vom OrganizationServiceContext ableiten oder den generierten Servicekontext ändern. Die folgende Tabelle listet die virtuellen Methoden auf.

Methode Beschreibung
OnBeginEntityTracking(Entity) Wird aufgerufen, nachdem eine Tabellenzeile an die OrganizationServiceContext angehängt wurde.
OnBeginLinkTracking(Entity, Relationship, Entity) Aufgerufen nachdem ein Link an den OrganizationServiceContext angefügt wurde.
OnEndEntityTracking(Entity) Wird aufgerufen, nachdem eine Tabellenzeile von der OrganizationServiceContext abgetrennt wurde.
OnEndEntityTracking(Entity) Aufgerufen nachdem ein Link aus dem OrganizationServiceContext entfernt wurde.
OnExecuting(OrganizationRequest) Aufgerufen direkt bevor eine Abfrage an Dataverse gesendet wird.
OnExecute(OrganizationRequest, OrganizationResponse) Aufgerufen direkt nachdem eine Abfrage an Dataverse gesendet wurde, unabhängig davon, ob eine Ausnahme aufgetreten ist oder nicht.
OnSavingChanges(SaveChangesOptions) Aufgerufen bevor ein Vorgang nach einem vom Aufruf von SaveChanges auftritt.
OnSaveChanges(SaveChangesResultCollection) Aufgerufen, wenn alle Vorgänge für einen Aufruf von SaveChanges abgeschlossen wurden, oder falls ein Fehler auftritt.

Datenvorgänge

Sie können Objekte im Servicekontext ändern, erstellen und löschen, und die an den Objekten vorgenommenen Änderungen werden von Dataverse nachverfolgt. Wenn OrganizationServiceContext.SaveChanges() Methode aufgerufen wird, werden die Befehle, die die entsprechenden Einfüge-, Aktualisierungs- oder Löschanweisungen für Daten in Dataverse ausführen, von Dataverse generiert und ausgeführt.

Wenn Sie mit früh gebundenen, von Entity abgeleiteten Klassen arbeiten, verwenden Sie den Tabellennamen und den Namen des Spaltenschemas, um eine Tabellenzeile oder Spalte anzugeben, mit der Sie arbeiten möchten. Schemanamen sind in EntityMetadata definiert. SchemaName und AttributeMetadata.SchemaNamedefiniert oder Sie können die Klassen- und Eigenschaftennamen verwenden, die in der Code-generierten Datei angezeigt werden. Das folgende Beispiel zeigt, wie Sie einen Wert dem E-Mail-Attribut einer neuen Kontaktinstanz zuweisen.

Contact contact = new Contact();
contact.EMailAddress1 = "sonny@contoso.com";

Eine neue Tabellenzeile erstellen

Wenn Sie Tabellendaten in Dataverse einfügen wollen, müssen Sie eine Instanz eines Entitätstyps erstellen und das Objekt zu einem Servicekontext hinzufügen. Der Servicekontext muss das Objekt nachverfolgen, damit er das Objekt in Dataverse speichern kann.

Wenn Sie eine neue Tabellenzeile erstellen, fügen Sie das Entitätsobjekt mit der Methode AddObject(Entity) zum Servicekontext hinzu.

Das folgende Beispiel zeigt, wie Sie einen neuen Kontakt unter Verwendung des Entitätsdatenmodells instanziieren und speichern können. Es veranschaulicht außerdem den Zugriff auf ein benutzerdefiniertes Attribut.

OrganizationServiceContext orgContext =new OrganizationServiceContext(svc);  
Contact contact = new Contact()     
 {  
   FirstName = "Charles",  
   LastName = "Brown",  
   Address1_Line1 = "123 Main St.",  
   Address1_City = "Des Moines",  
   Address1_StateOrProvince = "IA",  
   Address1_PostalCode = "21254",  
   new_twittername = "Chuck",  
   Telephone1 = "123-234-5678"  
 };   
orgContext.AddObject(contact);
orgContext.SaveChanges();

Es gibt mehrere Punkte, die Sie im vorherigen Codebeispiel beachten sollten. Nachdem ein neuer Kontakt instanziiert wurde müssen Sie zunächst dieses Kontaktobjekt an die OrganizationServiceContext.AddObject(Entity)- Methode übergeben, damit der Kontext mit der Nachverfolgung des Objekts beginnen kann. Der zweite Punkt, den Sie beachten sollten, ist, dass das neue Objekt auf dem Server gespeichert wird, indem die OrganizationServiceContext.SaveChanges()- Methode.

Wenn Sie ein Ziel zum Kontext und vor der OrganizationServiceContext.SaveChanges() Methode wurde, der generiert Kontext eine ID für das neue Objekt bezeichnet. Eine Ausnahme, die SaveChangesResults enthält, wird über die SaveChanges()-Methode ausgelöst, wenn Änderungen an Dataverse fehlschlagen.

Aktualisieren einer Tabellenzeile

Dataverse verfolgt Änderungen an Objekten, die an den Servicekontext angefügt sind. Um eine vorhandene Tabellenzeile zu ändern, müssen Sie zuerst das Objekt zum Kontext hinzufügen. Um ein Objekt zum Kontext hinzuzufügen, müssen Sie zuerst die Tabellenzeile aus Dataverse abrufen und dann das Objekt mit der Methode Attach(Entity) zum Kontext hinzufügen. Sobald das Objekt vom Kontext verfolgt wird, können Sie die Zeile aktualisieren, indem Sie ihre Spalten (Entitätsattribute) setzen.

Das folgende Beispiel zeigt, wie Sie eine Kontospalte unter Verwendung von früh gebundenen Klassen aktualisieren.

Account.EMailAddress1 = "Contoso-WebMaster@contoso.com";

Das folgende Beispiel zeigt, wie Sie einen Spaltenwert löschen können.

Account.EMailAddress1 = null;

Es gibt zwei Teilmethoden mit den Namen OnPropertyChanging und OnPropertyChanged für jede Tabellenzeile. Diese Methoden werden im Eigenschaftensetter aufgerufen. Sie können diese Methoden erweitern, indem Sie partielle Klassen verwenden, um benutzerdefinierte Geschäftslogik einzufügen.

Löschen einer Tabellenzeile

Um eine Tabellenzeile zu löschen, muss der Servicekontext das Objekt verfolgen. Nachdem das Objekt im Kontext verfügbar ist, können Sie die DeleteObject(Entity)-Methode verwenden, um das Objekt im Kontext zum Löschen zu markieren. Beachten Sie, dass die Tabellenzeile in Dataverse erst in der OrganizationServiceContext gelöscht wird. SaveChanges() Methode aufgerufen wird.

Siehe auch

LINQ-Abfragebeispiele mithilfe von OrganizationServiceContext mit Dataverse
Generieren von Klassen für die Programmierung mit früher Bindung mithilfe des SDK für .NET
IOrganizationService
OrganizationServiceContext

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