Utiliser OrganizationServiceContext

  • Article

Dans Microsoft Dataverse, vous pouvez utiliser plusieurs classes qui implémentent l’interface IOrganizationService pour accéder aux services web. Sinon, vous pouvez utiliser le OrganizationServiceContext généré par la commande pac modelbuilder build de Power Platform CLI pour accéder à la fonctionnalité supplémentaire. La classe OrganizationServiceContext vous permet d’effectuer le suivi des modifications, de gérer des identités et des relations, et vous donne accès au fournisseur LINQ. Cette classe contient également une méthode OrganizationServiceContext.SaveChanges() utilisée pour envoyer les modifications apportées aux données que le contexte suit. Cette classe est basée sur le même concept que la classe DataServiceContext dans les services de données Windows Communication Foundation (WCF).

Pour générer cette classe, entrez une valeur pour le paramètre --serviceContextName lorsque vous générez les types à liaison anticipée. La commande pac modelbuilder build de Power Platform CLI utilise ce nom comme nom de la classe générée. Pour plus d’informations sur l’utilisation de la commande pac modelbuilder build , consultez Générer des classses pour la programmation avec liaison anticipée à l’aide du SDK pour .NET. Vous pouvez utiliser l’instance du contexte lorsque vous développez des applications, des plug-ins et des activités de workflow.

Utilisation de la classe OrganizationServiceContext

Pour instancier la classe de contexte, vous devez transmettre au constructeur de classe un objet qui implémente l’interface IOrganizationService. Une solution est de transmettre une instance de la classe CrmServiceClient. Pour plus d’informations sur l’interface IOrganizationService, voir Interface IOrganizationService.

L’exemple de code suivant montre comment créer une instance de la classe de contexte. Dans cet exemple, la classe de contexte a été nommée AdventureWorksCycleServiceContext en spécifiant ce nom avec le paramètre --serviceContextName lors de l’exécution de la commande pac modelbuilder build :

// 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);

Après avoir créé l’instance de contexte, vous pouvez commencer à suivre la création, la modification ou la suppression de lignes de tables (enregistrements d’entités).

Le contexte doit suivre toute ligne de table ou relation que vous souhaitez envoyer à Dataverse. Par exemple, récupérez une ligne avec une requête LINQ et le contexte suit cette entité, ou utilisez la méthode OrganizationServiceContext.Attach(Entity) pour indiquer au contexte de commencer à suivre la ligne. Vous pouvez utiliser des données dans une application cliente et créer des lignes, créer des lignes associées et modifier des lignes existantes, mais vous devez appeler la méthode SaveChanges sur les lignes suivies pour valider les modifications sur Dataverse.

Suivre les modifications

Pour déterminer la façon dont une ligne de table est suivie par le contexte, vous pouvez activer la propriété EntityState sur l’instance Entity dérivée. Vous devez indiquer au contexte de suivre une ligne de Dataverse en appelant diverses méthodes ou à l’aide d’une requête LINQ. Toutes les lignes retournées d’une requête LINQ sont suivies par le contexte de service.

Vous pouvez ajouter des objets au contexte de service en appelant l’une des méthodes suivantes dans OrganizationServiceContext.

méthode Utilisation
AddObject(Entity) Ajoute une ligne de table à l’ensemble de lignes que suit le contexte du service. Le statut de la ligne dans le contexte est défini sur Created. Si la méthode SaveChanges() est appelée, la ligne est créée ou ajoutée au serveur.
Attach(Entity) Ajoute une ligne de table à l’ensemble de lignes que suit le contexte du service. Le statut de la ligne dans le contexte est défini sur Unchanged. Si la méthode SaveChanges() est appelée, cette ligne n’est pas envoyée au serveur à moins que son statut ne change.
CreateQuery(String) Ajoute les résultats d’une requête à l’ensemble de lignes que suit le contexte du service.

Dans Dataverse, le contexte du service vous permet de créer et de mettre à jour les relations entre les lignes de tables. Les propriétés de navigation générées par la commande pac modelbuilder build de Power Platform CLI et présentes dans les classes à liaison anticipée vous permettent d’accéder et de modifier les propriétés et relations associées aux lignes. Le contexte du service doit suivre la ligne associée pour que la ligne associée soit disponible pour la mise à jour sur le serveur.

Utilisez les méthodes suivantes dans OrganizationServiceContext pour utiliser les lignes associées et ajouter la ligne au contexte de service :

Méthode Utiliser
AddRelatedObject(Entity, Relationship, Entity) Ajoute la cible au contexte. Appelle la méthode Attach(Entity) sur la ligne de table cible, puis appelle la méthode AddLink(Entity, Relationship, Entity) entre la ligne source et la ligne cible (associée).
AttachLink(Entity, Relationship, Entity) Ajoute la ligne associée au contexte pour le suivi. Le statut de la ligne dans le contexte est défini sur Unchanged.
AddLink(Entity, Relationship, Entity) Crée une relation entre les lignes source et cible. Ajoute la cible au contexte. Le statut de la ligne cible dans le contexte est défini sur Created.
LoadProperty(Entity, String) Charge l’entité associée définie pour la relation spécifiée. Donne accès aux lignes associées à l’aide de la propriété de navigation. Contactez la méthode AddObject(Entity) sur la ligne associée après avoir accédé à la ligne à l’aide d’une propriété de navigation sur la ligne parente.
UpdateObject(Entity) Modifie l’état de la ligne spécifiée dans OrganizationServiceContext à Modifié.
DeleteObject(Entity) Modifie l’état de la ligne spécifiée à supprimer dans OrganizationServiceContext.

Les lignes associées pour les lignes que vous avez récupérées avec LINQ sont nulles si vous n’utilisez pas LoadProperty(Entity, Relationship) pour les récupérer. L’exemple de code suivant montre comment accéder aux lignes de tâche associés à une ligne Contact spécifique.

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();  
}

Vous pouvez utiliser la méthode AddLink(Entity, Relationship, Entity) pour créer des associations. Vous devez appeler la méthode SaveChanges() avant que le serveur ne soit mis à jour avec les nouvelles informations de lien.

L’exemple de code suivant montre comment créer une association entre un contact et un compte.

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

Enregistrer les modifications

Le contexte du service contient un graphique des lignes de tables dont il effectue le suivi. L’ordre dans lequel le contexte du service traite les modifications apportées aux tables et les envoie au serveur est essentiel. Les mises à jour des lignes de la table principale sont traitées, puis les lignes des tables associées sont traitées à leur tour. Si une valeur est définie sur la ligne de table principale par la ligne de table associée, cette valeur est utilisée pour la mise à jour des données sur le serveur.

Si une erreur se produit lors de l’enregistrement des informations d’entité, un nouveau type d’exception qui contient SaveChangesResult est levé par la méthode OrganizationServiceContext.SaveChanges() indépendamment de la valeur du paramètre SaveChangesOptions transmis à la méthode.

Utiliser des méthodes virtuelles lorsque le contexte est modifié

Parfois, il peut être nécessaire d’agir en fonction des modifications apportées à OrganizationServiceContext. Pour ce faire, vous disposez de méthodes virtuelles qui vous permettent d’intercepter ou d’être prévenu d’une opération. Pour tirer profit de ces méthodes, vous devez effectuer une dérivation de OrganizationServiceContext ou modifier le contexte du service généré. Le tableau suivant répertorie les méthodes virtuelles.

Méthode Description
OnBeginEntityTracking(Entity) Appelé après qu’une ligne de table soit jointe à OrganizationServiceContext.
OnBeginLinkTracking(Entity, Relationship, Entity) Appelé après qu’une liaison soit jointe à OrganizationServiceContext.
OnEndEntityTracking(Entity) Appelé après qu’une ligne de table soit disjointe de OrganizationServiceContext.
OnEndEntityTracking(Entity) Appelé après qu’une liaison soit détachée de OrganizationServiceContext.
OnExecuting(OrganizationRequest) Appelé juste avant qu’une requête soit envoyée à Dataverse.
OnExecute(OrganizationRequest, OrganizationResponse) Appelé uniquement lorsqu’une demande est envoyée à Dataverse, qu’une exception se produise ou non.
OnSavingChanges(SaveChangesOptions) Appelé avant toute opération après un appel à SaveChanges.
OnSaveChanges(SaveChangesResultCollection) Appelé lorsque toutes les opérations d’un appel à SaveChanges sont terminées, ou en cas d’échec.

Opérations sur les données

Vous pouvez modifier, créer et supprimer des objets dans le contexte de service, et Dataverse suivent les modifications que vous avez apportées à ces objets. Lorsque la méthode OrganizationServiceContext.SaveChanges() est appelée, Dataverse génère et exécute des commandes qui appliquent les instructions insert, update ou delete sur les données dans Dataverse.

Lorsque vous utilisez les classes dérivées Entity à liaison anticipée, vous utilisez le nom de la table ou le nom du schéma de colonne pour spécifier une ligne de table ou une colonne à utiliser. Les noms de schéma sont définis dans les propriétés EntityMetadata.SchemaName et AttributeMetadata.SchemaName, ou vous pouvez utiliser les noms de classe et de propriété affichés dans le fichier de code généré. Cet exemple explique comment attribuer une valeur à l’attribut de messagerie d’une nouvelle instance de contact.

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

Créer une ligne de table

Lorsque vous souhaitez insérer des données de table dans Dataverse, vous devez créer une instance d’un type d’entité et ajouter l’objet à un contexte de service. Le contexte du service doit suivre l’objet avant de pouvoir enregistrer l’objet dans Dataverse.

Lors de la création d’une ligne de table, vous ajoutez l’objet d’entité au contexte du service à l’aide de la méthode AddObject(Entity).

Cet exemple explique comment instancier et enregistrer un nouveau contact à l’aide du modèle de données d’entité. Il montre également comment accéder à un attribut personnalisé.

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();

Il existe plusieurs points à prendre en compte dans l’exemple de code précédent. Tout d’abord, après l’instanciation d’un nouveau contact, transmettez l’objet de contact à la méthode OrganizationServiceContext.AddObject(Entity) pour que le contexte puisse commencer à suivre l’objet. Le deuxième point à noter est que le nouvel objet est enregistré sur le serveur à l’aide de la méthode OrganizationServiceContext.SaveChanges() .

Une fois que vous avez ajouté un objet au contexte et avant que la méthode OrganizationServiceContext.SaveChanges() soit appelée, le contexte génère un ID pour le nouvel objet. Une exception contenant SaveChangesResults est levée à partir de la méthode SaveChanges() en cas d’échec des mises à jour des données Dataverse.

Mettre à jour une ligne de table

Dataverse suit les modifications des objets qui sont associés au contexte de service. Pour modifier une ligne de table existante, vous devez d’abord ajouter l’objet au contexte. Pour ajouter un objet au contexte, vous devez d’abord extraire la ligne de table de Dataverse, puis ajouter l’objet au contexte en utilisant la méthode Attach(Entity). Une fois que l’objet est suivi par le contexte, vous pouvez mettre à jour la ligne en définissant ses colonnes (attributs de l’entité).

Cet exemple explique comment mettre une colonne de compte à jour en utilisant les classes à liaison anticipée.

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

L’exemple suivant montre comment supprimer une valeur de colonne.

Account.EMailAddress1 = null;

Il existe deux méthodes partielles nommées OnPropertyChanging et OnPropertyChanged pour chaque ligne de table. Ces méthodes sont appelées dans la configuration des propriétés. Vous pouvez développer les méthodes en utilisant des classes partielles pour insérer une logique métier personnalisée.

Supprimer une ligne de table

Pour supprimer une ligne de table, le contexte de service doit suivre l’objet. Une fois que l’objet est dans le contexte, vous pouvez utiliser la méthode DeleteObject(Entity) pour marquer l’objet dans le contexte en vue de le supprimer. Notez que la ligne de table dans Dataverse n’est pas supprimée tant que la méthode OrganizationServiceContext.SaveChanges() n’est pas appelée.

Voir aussi

Exemples de requêtes LINQ utilisant OrganizationServiceContext avec Dataverse
Générer des classses pour la programmation avec liaison anticipée à l’aide du SDK pour .NET
IOrganizationService
OrganizationServiceContext

Notes

Pouvez-vous nous indiquer vos préférences de langue pour la documentation ? Répondez à un court questionnaire. (veuillez noter que ce questionnaire est en anglais)

Le questionnaire vous prendra environ sept minutes. Aucune donnée personnelle n’est collectée (déclaration de confidentialité).