Mettre à jour et supprimer des lignes de table à l’aide du SDK pour .NET

Cet article comprend des exemples utilisant à la fois des styles de programmation à liaison anticipée et à liaison tardive. Pour plus d’informations, voir : Programmation avec liaison tardive et anticipée à l’aide du SDK pour .NET

Chacun des exemples utilise une variable svc qui représente une instance d’une classe qui met en place les méthodes dans l’interface IOrganizationService. Pour plus d’informations sur les classes qui prennent en charge cette interface, consultez l’interface IOrganizationService.

Mise à jour de base

Les deux exemples ci-dessous utilisent la méthode IOrganizationService.Update pour définir les valeurs de colonne d’une ligne de table précédemment extraite.

Utilisez la propriété Entity.Id pour transférer la valeur de l’identificateur unique de la ligne extraite vers l’instance d’entité utilisée pour exécuter l’opération de mise à jour.

var retrievedAccount = new Entity("account", new Guid("a976763a-ba1c-e811-a954-000d3af451d6"));

//Use Entity class with entity logical name
var account = new Entity("account");
account.Id = retrievedAccount.Id;
// set attribute values
// Boolean (Two option)
account["creditonhold"] = true;
// DateTime
account["lastonholdtime"] = DateTime.Now;
// Double
account["address1_latitude"] = 47.642311;
account["address1_longitude"] = -122.136841;
// Int
account["numberofemployees"] = 400;
// Money
account["revenue"] = new Money(new Decimal(2000000.00));
// Picklist (Option set)
account["accountcategorycode"] = new OptionSetValue(2); //Standard customer

//Update the account
svc.Update(account);

var retrievedAccount = new Account()
{ Id = new Guid("a976763a-ba1c-e811-a954-000d3af451d6") };

var account = new Account();
account.Id = retrievedAccount.Id;
// set attribute values
// Boolean (Two option)
account.CreditOnHold = true;
// DateTime
account.LastOnHoldTime = DateTime.Now;
// Double
account.Address1_Latitude = 47.642311;
account.Address1_Longitude = -122.136841;
// Int
account.NumberOfEmployees = 400;
// Money
account.Revenue = new Money(new Decimal(2000000.00));
// Picklist (Option set)
account.AccountCategoryCode = new OptionSetValue(2); //Standard customer

//Update the account
svc.Update(account);

Utiliser la classe UpdateRequest

Au lieu d’utiliser la méthode IOrganizationService.Update, vous pouvez utiliser la classe Entity à liaison tardive ou les classes d’entité à liaison anticipée générées avec la classe UpdateRequest en définissant l’instance d’entité sur la propriété UpdateRequest.Target, puis en utilisant la méthode IOrganizationService.Execute.

var request = new UpdateRequest()
{ Target = account };
svc.Execute(request);

Quand utiliser la classe UpdateRequest

Vous devez utiliser la classe UpdateRequest si vous souhaitez transmettre des paramètres facultatifs. Il existe deux cas où vous pourriez avoir besoin de paramètres spéciaux.

• Quand vous souhaitez que les règles de détection de doublons soient appliquées. Pour plus d’informations : Détecter les données dupliquées avec le SDK pour .NET
• Lorsque vous créez une ligne de table qui représente un composant de solution, tel que WebResource et souhaitez l’associer à une solution spécifique. Dans ce cas, vous incluriez la valeur Solution.UniqueName à l’aide du paramètre SolutionUniqueName. Pour plus d’informations : Utiliser des messages avec le SDK pour .NET

Vous devez également utiliser la classe UpdateRequest si vous souhaitez préciser un comportement d’accès concurrentiel optimiste. Pour plus d’informations : Comportement de l’accès concurrentiel optimiste

Utilise la classe UpdateMultipleRequest

La classe UpdateMultipleRequest est le moyen le plus performant de mettre à jour plusieurs enregistrements dans une seule demande. Pour plus d’informations : Messages d’opération en bloc

Mettre à jour les entités associées en une opération

De la même manière que vous pouvez Créer des lignes de table associées en une seule opération, vous pouvez également mettre à jour les lignes de tableau associées.

Pour mettre à jour les lignes de table associées, vous devez récupérer une ligne avec les lignes associées afin de pouvoir accéder aux valeurs d’ID. Pour plus d’informations : Extraire avec des lignes associées.

var account = new Entity("account");
account.Id = retrievedAccount.Id;

//Define relationships
var primaryContactRelationship = new Relationship("account_primary_contact");
var AccountTasksRelationship = new Relationship("Account_Tasks");

//Update the account name
account["name"] = "New Account name";

//Update the email address for the primary contact of the account
var contact = new Entity("contact");
contact.Id = retrievedAccount.RelatedEntities[primaryContactRelationship]
.Entities.FirstOrDefault().Id;
contact["emailaddress1"] = "someone_a@example.com";

List<Entity> primaryContacts = new List<Entity>();
primaryContacts.Add(contact);  
account.RelatedEntities.Add(primaryContactRelationship, new EntityCollection(primaryContacts));

// Find related Tasks that need to be updated
List<Entity> tasksToUpdate = retrievedAccount
.RelatedEntities[AccountTasksRelationship].Entities
.Where(t => t["subject"].Equals("Example Task")).ToList();

// A list to put the updated tasks
List<Entity> updatedTasks = new List<Entity>();

//Fill the list of updated tasks based on the tasks that need to but updated
tasksToUpdate.ForEach(t => {
var updatedTask = new Entity("task");
updatedTask.Id = t.Id;
updatedTask["subject"] = "Updated Subject";

updatedTasks.Add(updatedTask);
});

//Set the updated tasks to the collection
account.RelatedEntities.Add(AccountTasksRelationship, new EntityCollection(updatedTasks));

//Update the account and related contact and tasks
svc.Update(account);

var account = new Account();
account.Id = retrievedAccount.Id;

//Update the account
account.Name = "New Account name";

//Update the email address for the primary contact of the account
account.account_primary_contact = new Contact
{ Id = retrievedAccount.PrimaryContactId.Id, EMailAddress1 = "someone_a@example.com" };

// Find related Tasks that need to be updated
List<Task> tasksToUpdate = retrievedAccount.Account_Tasks
    .Where(t => t.Subject.Equals("Example Task")).ToList();

// A list to put the updated tasks
List<Task> updatedTasks = new List<Task>();

//Fill the list of updated tasks based on the tasks that need to but updated
tasksToUpdate.ForEach(t =>
{
    updatedTasks
    .Add(new Task() {
        ActivityId = t.ActivityId,
        Subject = "Updated Subject"
    });

});

//Set the updated tasks to the collection
account.Account_Tasks = updatedTasks;

//Update the account and related contact and tasks
svc.Update(account);

Rechercher des enregistrements dupliqués

Lors de la mise à jour d’une ligne de table, vous pouvez modifier les valeurs afin que la ligne représente un doublon d’une autre ligne. Pour plus d’informations : Détecter les données dupliquées avec le SDK pour .NET

Mettre à jour avec une clé secondaire

Si vous avez défini une clé secondaire pour une table, vous pouvez l’utiliser à la place de la clé primaire pour mettre à jour une ligne. Vous ne pouvez pas utiliser la classe à liaison anticipée pour spécifier la clé secondaire. Vous devez utiliser le constructeur Entity(String, KeyAttributeCollection) pour spécifier la clé secondaire.

Si vous souhaitez utiliser des types à liaison anticipée, vous pouvez convertir Entity en une classe à liaison anticipée à l’aide de la méthode Entity.ToEntity<T>.

L’exemple suivant montre comment mettre à jour un Account en utilisant un clé secondaire défini pour la colonne accountnumber (attribut).

var accountNumberKey = new KeyAttributeCollection();
accountNumberKey.Add(new KeyValuePair<string, object>("accountnumber", "123456"));

Account exampleAccount = new Entity("account", accountNumberKey).ToEntity<Account>();
exampleAccount.Name = "New Account Name";
svc.Update(exampleAccount);

Pour plus d′informations :

• Utiliser les clés secondaires
• Utilisation d’une clé secondaire pour référencer un enregistrement

Mettre à jour et supprimer des enregistrements dans des tables élastiques

Si vous mettez à jour ou supprimez des données de table élastique stockées dans des partitions, assurez-vous de spécifier la clé de partition lors de l’accès à ces données. En savoir plus : Partitionnement et mise à l’échelle horizontale

Utiliser Upsert

Généralement dans les scénarios d’intégration des données, vous devez créer ou mettre à jour les données dans Dataverse depuis d’autres sources. Dataverse peut avoir déjà des enregistrements avec le même identifiant unique, qui peut être une clé secondaire. S’il existe une ligne de tableau, vous souhaitez la mettre à jour. S’il n’existe pas, vous souhaitez le créer de telle sorte que les données ajoutées sont synchronisées avec les données sources. Il s’agit du scénario lorsque vous souhaitez utiliser Upsert.

L’exemple suivant utilise deux fois UpsertRequest. La première fois que la ligne de compte est créée et la deuxième fois qu’elle est mise à jour car elle a une valeur accountnumber et une clé secondaire utilise cette colonne (attribut).

Pour les deux appels, la propriété UpsertResponse.RecordCreated indique si l’opération a créé une ligne ou non.

// This environment has an alternate key set for the accountnumber attribute.

//Instantiate account entity with accountnumber value
var account = new Entity("account", "accountnumber", "0003");
account["name"] = "New Account";

//Use Upsert the first time
UpsertRequest request1 = new UpsertRequest() {
Target = account
};

//The new entity is created
var response1 = (UpsertResponse)svc.Execute(request1);
Console.WriteLine("Record Created: {0}",response1.RecordCreated); //true

//Update the name of the existing account entity
account["name"] = "Updated Account";

//Use Upsert for the second time
UpsertRequest request2 = new UpsertRequest()
{
Target = account
};

//The existing entity is updated.
var response2 = (UpsertResponse)svc.Execute(request2);
Console.WriteLine("Record Created: {0}", response2.RecordCreated); //false

Pour plus d’informations : Utilisation de Upsert pour insérer ou mettre à jour un enregistrement

Delete

La méthode IOrganizationService.Delete requiert simplement le nom logique de la table et l’identificateur unique. Peu importe si vous utilisez une classe Entity à liaison tardive ou une classe à liaison anticipée générée, vous pouvez utiliser la syntaxe suivante pour une opération de suppression en transmettant les propriétés Entity.LogicalName et Entity.Id.

svc.Delete(retrievedEntity.LogicalName, retrievedEntity.Id);

Ou vous pouvez utiliser les valeurs :

svc.Delete("account", new Guid("e5fa5509-2582-e811-a95e-000d3af40ae7"));

Utiliser la classe DeleteRequest

Vous pouvez utiliser la classe DeleteRequest au lieu de la méthode IOrganizationService.Delete, mais elle n’est requise que lorsque vous souhaitez spécifier un comportement d’accès concurrentiel optimiste.

var retrievedEntity = new Entity("account")
{
    Id = new Guid("c81ffd82-cd82-e811-a95c-000d3af49bf8"),
    RowVersion = "986335"

};

var request = new DeleteRequest()
{
    Target = retrievedEntity.ToEntityReference(),
    ConcurrencyBehavior = ConcurrencyBehavior.IfRowVersionMatches
};

svc.Execute(request);

Comportement d’accès concurrentiel optimiste

Vous pouvez préciser le comportement d’accès concurrentiel optimiste pour l’opération en définissant la propriété ConcurrencyBehavior des classes UpdateRequest ou DeleteRequest.

La logique de mise à jour ou de suppression de la ligne peut être basée sur des données obsolètes. Si les données actuelles diffèrent, car elles ont changé depuis leur extraction, l’accès concurrentiel optimiste permet d’annuler une mise à jour ou de supprimer une opération de telle sorte que vous pouvez la récupérer et utiliser les données actuelles afin de déterminer s’il convient de poursuivre ou non.

Pour déterminer si la ligne a été modifiée, vous n’avez pas besoin de comparer toutes les valeurs, vous pouvez utiliser la propriété RowVersion pour voir si elle a changé.

L’exemple suivant se produit uniquement quand :

• La RowVersion de la ligne dans la base de données est égale à 986323
• La table de compte est activée pour l’accès concurrentiel optimiste (la propriété EntityMetadata.IsOptimisticConcurrencyEnabled est true)
• La propriété RowVersion est définie sur la ligne transmise avec la requête.

Si RowVersion ne correspond pas, une erreur survient avec le message The version of the existing record doesn't match the RowVersion property provided..

var retrievedAccount = new Account()
{   
    Id = new Guid("a976763a-ba1c-e811-a954-000d3af451d6"), 
    RowVersion = "986323" 
};

var account = new Account();
account.Id = retrievedAccount.Id;
account.RowVersion = retrievedAccount.RowVersion;

// set attribute values
account.CreditOnHold = true;

//Update the account
var request = new UpdateRequest()
{ 
    Target = account,
    ConcurrencyBehavior = ConcurrencyBehavior.IfRowVersionMatches 
};

try
{
    svc.Execute(request);
}
catch (FaultException<OrganizationServiceFault> ex)
{
    switch (ex.Detail.ErrorCode)
    {
        case -2147088254: // ConcurrencyVersionMismatch 
        case -2147088253: // OptimisticConcurrencyNotEnabled 
            throw new InvalidOperationException(ex.Detail.Message);
        case -2147088243: // ConcurrencyVersionNotProvided
            throw new ArgumentNullException(ex.Detail.Message);
        default:
            throw ex;
    }
}

Pour plus d’informations :

• Accès concurrentiel optimiste
• Énumération ConcurrencyBehavior

Anciens messages de mise à jour

Il existe plusieurs messages spécialisés déconseillés qui exécutent des opérations de mise à jour. Dans les versions antérieures, il était nécessaire d’utiliser ces messages, mais maintenant les mêmes opérations doivent être exécutées en utilisant IOrganizationService.Update ou la classe UpdateRequest avec la méthode IOrganizationService.Execute.

<entity> fait référence à toute entité qui fournit cet attribut.

Pour plus d’informations : Comportement des opérations de mise à jour spécifiques

Voir aussi

Créer des lignes de table à l’aide du SDK pour .NET
Récupérer une ligne de table à l’aide du SDK pour .NET
Associer et dissocier des lignes de tables à l’aide du SDK pour .NET