Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra. # Utilisation du modèle de persistance des objets .NET et de DynamoDB AWS SDK pour .NET fournit un modèle de persistance des objets qui vous permet de mapper vos classes côté client aux tables Amazon DynamoDB. Ensuite, chaque instance d’objet est mappée à un élément des tables correspondantes. Pour enregistrer vos objets côté client dans les tables, le modèle de persistance des objets fournit la classe `DynamoDBContext`, un point d’entrée dans DynamoDB. Cette classe fournit une connexion à DynamoDB, et vous permet d’accéder aux tables, d’effectuer diverses opérations CRUD ainsi que d’exécuter des requêtes. Le modèle de persistance des objets fournit un ensemble d'attributs permettant de mapper les classes côté client aux tables et properties/fields aux attributs des tables. **Note** Le modèle de persistance des objets n’autorise pas une API à créer, mettre à jour ou supprimer des tables. Il fournit uniquement des opérations sur les données. Vous ne pouvez utiliser que l'API de AWS SDK pour .NET bas niveau pour créer, mettre à jour et supprimer des tables. L’exemple suivant montre le fonctionnement du modèle de persistance des objets. Il commence par la table `ProductCatalog`. Sa clé primaire est `Id`. ``` ProductCatalog(Id, ...) ``` Supposons que vous avec une classe `Book` avec les propriétés `Title`, `ISBN` et `Authors`. Vous pouvez mapper la classe `Book` à la table `ProductCatalog` en ajoutant les attributs définis par le modèle de persistance des objets, comme illustré dans l’exemple de code C\$1 suivant. **Example** ``` [DynamoDBTable("ProductCatalog")] public class Book { [DynamoDBHashKey] public int Id { get; set; } public string Title { get; set; } public int ISBN { get; set; } [DynamoDBProperty("Authors")] public List BookAuthors { get; set; } [DynamoDBIgnore] public string CoverPage { get; set; } } ``` Dans l’exemple précédent, l’attribut `DynamoDBTable` mappe la classe `Book` à la table `ProductCatalog`. Le modèle de persistance des objets prend en charge les mappages explicite et par défaut entre les propriétés de classe et les attributs de table. + **Mappage explicite – **Pour mapper une propriété à une clé primaire, vous devez utiliser les attributs de modèle de persistance des objets `DynamoDBHashKey` et `DynamoDBRangeKey`. En outre, pour les attributs de clé non primaire, si un nom de propriété de votre classe et l’attribut de table correspondant auquel vous voulez le mapper ne sont pas identiques, vous devez définir le mappage en ajoutant explicitement l’attribut `DynamoDBProperty`. Dans l’exemple précédent, la propriété `Id` mappe à la clé primaire du même nom, et la propriété `BookAuthors` mappe à l’attribut `Authors` dans la table `ProductCatalog`. + **Mappage par défaut – **Par défaut, le modèle de persistance des objets mappe les propriétés de classe aux attributs du même nom dans la table. Dans l’exemple précédent, les propriétés `Title` et `ISBN` mappent aux attributs du même nom dans la table `ProductCatalog`. Vous n’avez pas à mapper chaque propriété de classe. Vous identifiez ces propriétés en ajoutant l’attribut `DynamoDBIgnore`. Lorsque vous enregistrez une instance `Book` dans la table, le `DynamoDBContext` n’inclut pas la propriété `CoverPage`. Il ne renvoie pas non plus cette propriété lorsque vous récupérez l’instance livre. Vous pouvez mapper des propriétés de types primitifs .NET tels que int et string. Vous pouvez également mapper n’importe quels types de données arbitraires tant que vous fournissez un convertisseur approprié pour mapper les données arbitraires à l’un des types DynamoDB. Pour en savoir plus sur le mappage de types arbitraires, consultez [Mappage de données arbitraires avec DynamoDB à l'aide AWS SDK pour .NET du modèle de persistance des objets](DynamoDBContext.ArbitraryDataMapping.md). Le modèle de persistance des objets prend en charge le verrouillage optimiste. Au cours d’une opération de mise à jour, cela garantit que vous disposez de la dernière copie de l’élément que vous êtes sur le point de mettre à jour. Pour de plus amples informations, veuillez consulter [Verrouillage optimiste à l'aide de DynamoDB et du modèle de persistance des objets AWS SDK pour .NET](DynamoDBContext.VersionSupport.md). Pour plus d’informations, consultez les rubriques ci-dessous. **Topics** + [Types de données pris en charge](#DotNetDynamoDBContext.SupportedTypes) + [Attributs DynamoDB du modèle de persistance des objets .NET](DeclarativeTagsList.md) + [DBContext Classe Dynamo issue du modèle de persistance des objets .NET](DotNetDynamoDBContext.md) + [Verrouillage optimiste à l'aide de DynamoDB et du modèle de persistance des objets AWS SDK pour .NET](DynamoDBContext.VersionSupport.md) + [Mappage de données arbitraires avec DynamoDB à l'aide AWS SDK pour .NET du modèle de persistance des objets](DynamoDBContext.ArbitraryDataMapping.md) ## Types de données pris en charge Le modèle de persistance des objets prend en charge un ensemble de types de données .NET primitifs, de collections et de types de données arbitraires. Le modèle prend en charge les types de données primitifs suivants. + `bool` + `byte` + `char` + `DateTime` + `decimal` + `double` + `float` + `Int16` + `Int32` + `Int64` + `SByte` + `string` + `UInt16` + `UInt32` + `UInt64` Le modèle de persistance des objets prend également en charge les types de collection .NET. `DynamoDBContext`est capable de convertir des types de collection concrets et de simples objets CLR ordinaires (POCOs). Le tableau suivant résume le mappage des types .NET précédents aux types DynamoDB. **** | Type primitif .NET | Type DynamoDB | | --- | --- | | Tous les types de numéro | `N` (type Number) | | Tous types de chaînes | `S` (type String) | | MemoryStream, octet [] | `B` (type Binary) | | bool | N (type de nombre). 0 représente false et 1 représente true. | | Types de collections | Type BS (ensemble de binaires), type SS (ensemble de chaînes) ou type NS (ensemble de nombres). | | DateTime | S (type String). Les valeurs DateTime sont stockées comme chaînes de format ISO-8601. | Le modèle de persistance des objets prend également en charge les types de données arbitraires. Toutefois, vous devez fournir un code de convertisseur pour mapper les types complexes aux types DynamoDB. **Note** Les valeurs binaires vides sont prises en charge. La lecture des valeurs de chaîne vides est prise en charge. Les valeurs d’attribut de chaîne vides sont prises en charge dans les valeurs d’attribut de type de chaîne Set lors de l’écriture dans DynamoDB. Les valeurs d’attribut de chaîne vides de type String et les valeurs de chaîne vides contenues dans le type List ou Map sont supprimées des demandes d’écriture. # Attributs DynamoDB du modèle de persistance des objets .NET Cette section décrit les attributs qu’offre le modèle de persistance des objets afin que vous puissiez mapper vos classes et propriétés aux tables et attributs DynamoDB. **Note** Dans les attributs suivants, seuls les attributs `DynamoDBTable` et `DynamoDBHashKey` sont obligatoires. ## Dynamo DBGlobal SecondaryIndexHashKey Mappe une propriété de classe à la clé de partition d’un index secondaire global. Utilisez cet attribut si vous devez interroger (`Query`) un index secondaire global. ## Dynamo DBGlobal SecondaryIndexRangeKey Mappe une propriété de classe à la clé de tri d’un index secondaire global. Utilisez cet attribut si vous devez interroger (`Query`) un index secondaire global, et souhaitez affiner vos résultats à l’aide de la clé de tri d’index. ## Clé Dynamo DBHash Mappe une propriété de classe à la clé de partition de la clé primaire de la table. Les attributs de clé primaire ne peuvent pas être de type collection. L’exemple de code C\$1 suivant mappe la classe `Book` à la table `ProductCatalog`, et la propriété `Id` à la clé de partition de clé primaire de la table. ``` [DynamoDBTable("ProductCatalog")] public class Book { [DynamoDBHashKey] public int Id { get; set; } // Additional properties go here. } ``` ## Dynamo DBIgnore Indique que la propriété associée devrait être ignorée. Si vous ne souhaitez enregistrer aucune de vos propriétés de classe, vous pouvez ajouter cet attribut afin de demander à `DynamoDBContext` de ne pas inclure cette propriété lors de l’enregistrement d’objets dans la table. ## Dynamo DBLocal SecondaryIndexRangeKey Mappe une propriété de classe à la clé de tri d’un index secondaire local. Utilisez cet attribut si vous devez interroger (`Query`) un index secondaire local, et souhaitez affiner vos résultats à l’aide de la clé de tri d’index. ## Dynamo DBProperty Mappe une propriété de classe à un attribut de table. Si la propriété de classe mappe à un attribut de table du même nom, vous n’avez pas besoin de spécifier cet attribut. Toutefois, si les noms ne sont pas les mêmes, vous pouvez utiliser cette étiquette pour indiquer le mappage. Dans l’instruction C\$1 suivante, la `DynamoDBProperty` mappe la propriété `BookAuthors` à l’attribut `Authors` dans la table. ``` [DynamoDBProperty("Authors")] public List BookAuthors { get; set; } ``` `DynamoDBContext` utilise ces informations de mappage pour créer l’attribut `Authors` lors de l’enregistrement de données d’objet dans la table correspondante. ## Dynamo DBRenamable Spécifie un autre nom pour une propriété de classe. Ceci est utile si vous écrivez un convertisseur personnalisé pour mapper des données arbitraires à une table DynamoDB où le nom d’une propriété de classe diffère du nom d’un attribut de table. ## Clé Dynamo DBRange Mappe une propriété de classe à la clé de tri de la clé primaire de la table. Si la table possède une clé primaire composite (clé de partition et clé de tri), vous devez spécifier les attributs `DynamoDBHashKey` et `DynamoDBRangeKey` dans votre mappage de classe. Par exemple, l’exemple de table `Reply` a une clé primaire composée de la clé de partition `Id` et de la clé de tri `Replenishment`. L’exemple de code C\$1 suivant mappe la classe `Reply` à la table `Reply`. La définition de classe indique également que deux de ses propriétés mappent à la clé primaire. ``` [DynamoDBTable("Reply")] public class Reply { [DynamoDBHashKey] public int ThreadId { get; set; } [DynamoDBRangeKey] public string Replenishment { get; set; } // Additional properties go here. } ``` ## Dynamo DBTable Identifie la table cible dans DynamoDB à laquelle la classe mappe. Par exemple, l’exemple de code C\$1 suivant mappe la classe `Developer` à la table `People` dans DynamoDB. ``` [DynamoDBTable("People")] public class Developer { ...} ``` Cet attribut peut être hérité ou remplacé. + L’attribut `DynamoDBTable` peut être hérité. Dans l’exemple précédent, si vous ajoutez une nouvelle classe, `Lead`, qui hérite de la classe `Developer`, elle mappe également à la table `People`. Les objets `Developer` et `Lead` sont stockés dans la table `People`. + L’attribut `DynamoDBTable` peut également être remplacé. Dans l’exemple de code C\$1 suivant, la classe `Manager` hérite de la classe `Developer`. Cependant, l’ajout explicite de l’attribut `DynamoDBTable` a pour effet de mapper la classe à une autre table (`Managers`). ``` [DynamoDBTable("Managers")] public class Manager : Developer { ...} ``` Vous pouvez ajouter le paramètre facultatif, `LowerCamelCaseProperties`, pour demander à DynamoDB de mettre la première lettre du nom de propriété en minuscule lors du stockage des objets dans une table, comme dans l’exemple C\$1 suivant. ``` [DynamoDBTable("People", LowerCamelCaseProperties=true)] public class Developer { string DeveloperName; ... } ``` Lors de l’enregistrement d’instances de la classe `Developer`, `DynamoDBContext` enregistre la propriété `DeveloperName` en tant que `developerName`. ## Dynamo DBVersion Identifie une propriété de classe pour stocker le numéro de version de l’élément. Pour plus d’informations sur la gestion des versions, consultez [Verrouillage optimiste à l'aide de DynamoDB et du modèle de persistance des objets AWS SDK pour .NET](DynamoDBContext.VersionSupport.md). # DBContext Classe Dynamo issue du modèle de persistance des objets .NET La classe `DynamoDBContext` est le point d’entrée de la base de données Amazon DynamoDB. Elle fournit une connexion à DynamoDB, et vous permet d’accéder à vos données dans diverses tables, d’effectuer diverses opérations CRUD, ainsi que d’exécuter des requêtes. La classe `DynamoDBContext` fournit les méthodes suivantes. **Topics** + [Créez MultiTable BatchGet](#w2aac17b9c21c23c39b7) + [Créez MultiTable BatchWrite](#w2aac17b9c21c23c39b9) + [CreateBatchGet](#w2aac17b9c21c23c39c11) + [CreateBatchWrite](#w2aac17b9c21c23c39c13) + [Suppression](#w2aac17b9c21c23c39c15) + [Dispose](#w2aac17b9c21c23c39c17) + [ExecuteBatchGet](#w2aac17b9c21c23c39c19) + [ExecuteBatchWrite](#w2aac17b9c21c23c39c21) + [FromDocument](#w2aac17b9c21c23c39c23) + [FromQuery](#w2aac17b9c21c23c39c25) + [FromScan](#w2aac17b9c21c23c39c27) + [GetTargetTable](#w2aac17b9c21c23c39c29) + [Equilibreur de](#w2aac17b9c21c23c39c31) + [Query](#w2aac17b9c21c23c39c33) + [Enregistrer](#w2aac17b9c21c23c39c35) + [Analyser](#w2aac17b9c21c23c39c37) + [ToDocument](#w2aac17b9c21c23c39c39) + [Spécification de paramètres facultatifs pour Dynamo DBContext](#OptionalConfigParams) ## Créez MultiTable BatchGet Crée un objet `MultiTableBatchGet` composé de plusieurs objets `BatchGet`. Chacun de ces objets `BatchGet` peut être utilisé pour récupérer des éléments d’une table DynamoDB. Pour récupérer les éléments des tables, utilisez la méthode `ExecuteBatchGet` en passant l’objet `MultiTableBatchGet` en tant que paramètre. ## Créez MultiTable BatchWrite Crée un objet `MultiTableBatchWrite` composé de plusieurs objets `BatchWrite`. Chacun de ces objets `BatchWrite` peut être utilisé pour écrire ou supprimer des éléments dans une table DynamoDB. Pour écrire dans des tables, utilisez la méthode `ExecuteBatchWrite` en passant l’objet `MultiTableBatchWrite` en tant que paramètre. ## CreateBatchGet Crée un objet `BatchGet` que vous pouvez utiliser pour extraire plusieurs éléments d’une table. ## CreateBatchWrite Crée un objet `BatchWrite` que vous pouvez utiliser pour insérer plusieurs éléments dans une table ou supprimer plusieurs éléments d’une table. ## Suppression Supprime un élément de la table. La méthode requiert la clé primaire de l’élément que vous souhaitez supprimer. Vous pouvez fournir en tant que paramètre à cette méthode la valeur de clé primaire ou un objet côté client contenant une valeur de clé primaire. + Si vous spécifiez un objet côté client en tant que paramètre et avez activé le verrouillage optimiste, la suppression ne réussit que si les versions côté client et côté serveur de l’objet correspondent. + Si vous spécifiez uniquement la valeur de clé primaire en tant que paramètre, la suppression réussit, que vous ayez activé ou non le verrouillage optimiste. **Note** Pour effectuer cette opération en arrière-plan, utilisez la méthode `DeleteAsync` à la place. ## Dispose Élimine toutes les ressources gérées et non gérées. ## ExecuteBatchGet Lit les données d’une ou plusieurs tables, en traitant tous les objets `BatchGet` en un objet `MultiTableBatchGet`. **Note** Pour effectuer cette opération en arrière-plan, utilisez la méthode `ExecuteBatchGetAsync` à la place. ## ExecuteBatchWrite Ecrit ou supprime des données dans une ou plusieurs tables, en traitant tous les objets `BatchWrite` en un objet `MultiTableBatchWrite`. **Note** Pour effectuer cette opération en arrière-plan, utilisez la méthode `ExecuteBatchWriteAsync` à la place. ## FromDocument Pour une instance de `Document`, la méthode `FromDocument` renvoie une instance d'une classe côté client. Ceci est utile si vous souhaitez utiliser les classes de modèle de document avec le modèle de persistance des objets pour effectuer des opérations de données. Pour plus d'informations sur les classes de modèles de documents fournies par le AWS SDK pour .NET, consultez[Utilisation du modèle de document .NET dans DynamoDB](DotNetSDKMidLevel.md). Supposons que vous ayez un objet `Document` nommé `doc` qui contient une représentation d’un l’élément `Forum`. (Pour voir comment construire cet objet, consultez la description de la méthode `ToDocument`, plus loin dans cette rubrique. Vous pouvez utiliser le paramètre `FromDocument` pour récupérer l’élément `Forum` à partir de `Document`, comme illustré dans l’exemple de code C\$1 suivant. **Example** ``` forum101 = context.FromDocument(101); ``` **Note** Si votre objet `Document` implémente l’interface `IEnumerable`, vous pouvez utiliser la méthode `FromDocuments` à la place. Cela vous permet d'itérer sur toutes les instances de classe dans le `Document`. ## FromQuery Exécute une opération `Query` avec les paramètres de requête définis dans un objet `QueryOperationConfig`. **Note** Pour effectuer cette opération en arrière-plan, utilisez la méthode `FromQueryAsync` à la place. ## FromScan Exécute une opération `Scan` avec les paramètres d'analyse définis dans un objet `ScanOperationConfig`. **Note** Pour effectuer cette opération en arrière-plan, utilisez la méthode `FromScanAsync` à la place. ## GetTargetTable Récupère la table cible pour le type spécifié. Ceci est utile si vous écrivez un convertisseur personnalisé pour mapper des données arbitraires à une table DynamoDB, et devez déterminer la table associée à un type de données personnalisé. ## Equilibreur de Récupère un élément dans une table. La méthode requiert uniquement la clé primaire de l’élément que vous souhaitez extraire. Par défaut, DynamoDB renvoie l’élément ayant des valeurs éventuellement cohérentes. Pour plus d’informations sur le modèle de cohérence éventuelle, consultez [Cohérence en lecture DynamoDB](HowItWorks.ReadConsistency.md). `Load`ou la `LoadAsync` méthode appelle l'[GetItem](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_GetItem.html)opération, qui vous oblige à spécifier la clé primaire de la table. Comme `GetItem` ignore le paramètre `IndexName`, vous ne pouvez pas charger un élément à l’aide de la partition ou de la clé de tri d’un index. Vous devez donc utiliser la clé primaire de la table pour charger un élément. **Note** Pour effectuer cette opération en arrière-plan, utilisez la méthode `LoadAsync` à la place. Pour voir un exemple d’utilisation de la méthode `LoadAsync` pour effectuer des opérations CRUD de haut niveau sur une table DynamoDB, consultez l’exemple suivant. ``` /// /// Shows how to perform high-level CRUD operations on an Amazon DynamoDB /// table. /// public class HighLevelItemCrud { public static async Task Main() { var client = new AmazonDynamoDBClient(); DynamoDBContext context = new DynamoDBContext(client); await PerformCRUDOperations(context); } public static async Task PerformCRUDOperations(IDynamoDBContext context) { int bookId = 1001; // Some unique value. Book myBook = new Book { Id = bookId, Title = "object persistence-AWS SDK for.NET SDK-Book 1001", Isbn = "111-1111111001", BookAuthors = new List { "Author 1", "Author 2" }, }; // Save the book to the ProductCatalog table. await context.SaveAsync(myBook); // Retrieve the book from the ProductCatalog table. Book bookRetrieved = await context.LoadAsync(bookId); // Update some properties. bookRetrieved.Isbn = "222-2222221001"; // Update existing authors list with the following values. bookRetrieved.BookAuthors = new List { " Author 1", "Author x" }; await context.SaveAsync(bookRetrieved); // Retrieve the updated book. This time, add the optional // ConsistentRead parameter using DynamoDBContextConfig object. await context.LoadAsync(bookId, new DynamoDBContextConfig { ConsistentRead = true, }); // Delete the book. await context.DeleteAsync(bookId); // Try to retrieve deleted book. It should return null. Book deletedBook = await context.LoadAsync(bookId, new DynamoDBContextConfig { ConsistentRead = true, }); if (deletedBook == null) { Console.WriteLine("Book is deleted"); } } } ``` ## Query Interroge une table sur la base des paramètres de requête que vous fournissez. Vous pouvez interroger une table uniquement si elle comporte une clé primaire composite (clé de partition et clé de tri). Lors de l’interrogation, vous devez spécifier une clé de partition et une condition qui s’applique à la clé de tri. Supposons que vous disposez d’une classe `Reply` côté client mappée à la table `Reply` dans DynamoDB. L’exemple de code C\$1 suivant interroge la table `Reply` pour trouver les réponses des unités d’exécution de forum publiées au cours des 15 derniers jours. La table `Reply` possède une clé primaire qui a la clé de partition `Id` et la clé de tri `ReplyDateTime`. **Example** ``` DynamoDBContext context = new DynamoDBContext(client); string replyId = "DynamoDB#DynamoDB Thread 1"; //Partition key DateTime twoWeeksAgoDate = DateTime.UtcNow.Subtract(new TimeSpan(14, 0, 0, 0)); // Date to compare. IEnumerable latestReplies = context.Query(replyId, QueryOperator.GreaterThan, twoWeeksAgoDate); ``` Ceci renvoie une collection d’objets `Reply`. La méthode `Query` renvoie une collection `IEnumerable` « avec chargement différé ». Elle ne renvoie initialement qu’une seule page de résultats puis effectue un appel de service pour la page suivante si nécessaire. Pour obtenir tous les éléments correspondants, vous devez itérer uniquement sur la collection `IEnumerable`. Si votre table possède une clé primaire simple (clé de partition), vous ne pouvez pas utiliser la méthode `Query`. Au lieu de cela, vous pouvez utiliser la méthode `Load` et fournir la clé de partition pour récupérer l’élément. **Note** Pour effectuer cette opération en arrière-plan, utilisez la méthode `QueryAsync` à la place. ## Enregistrer Enregistre l’objet spécifié dans la table. Si la clé primaire spécifiée dans l’objet d’entrée n’existe pas dans la table, la méthode ajoute un nouvel élément à celle-ci. Si la clé primaire existe, la méthode met à jour l’élément existant. Si le verrouillage optimiste est configuré, la mise à jour ne réussit que si les versions client et serveur de l’élément correspondent. Pour de plus amples informations, veuillez consulter [Verrouillage optimiste à l'aide de DynamoDB et du modèle de persistance des objets AWS SDK pour .NET](DynamoDBContext.VersionSupport.md). **Note** Pour effectuer cette opération en arrière-plan, utilisez la méthode `SaveAsync` à la place. ## Analyser Effectue une analyse de la table toute entière. Vous pouvez filtrer les résultats d’analyse en spécifiant une condition d’analyse. La condition peut être évaluée sur n’importe quel attribut dans la table. Supposons que vous disposez d’une classe `Book` côté client mappée à la table `ProductCatalog` dans DynamoDB. L’exemple C \$1 suivant analyse la table et renvoie uniquement les éléments livre dont le prix est inférieur à 0. **Example** ``` IEnumerable itemsWithWrongPrice = context.Scan( new ScanCondition("Price", ScanOperator.LessThan, price), new ScanCondition("ProductCategory", ScanOperator.Equal, "Book") ); ``` La méthode `Scan` renvoie une collection `IEnumerable` « avec chargement différé ». Elle ne renvoie initialement qu’une seule page de résultats puis effectue un appel de service pour la page suivante si nécessaire. Pour obtenir tous les éléments correspondants, vous devez seulement itérer sur la collection `IEnumerable`. Pour des raisons de performance, vous devez interroger vos tables et éviter une analyse de table. **Note** Pour effectuer cette opération en arrière-plan, utilisez la méthode `ScanAsync` à la place. ## ToDocument Renvoie une instance de la classe de modèle de document `Document` de votre instance de classe. Ceci est utile si vous souhaitez utiliser les classes de modèle de document avec le modèle de persistance des objets pour effectuer des opérations de données. Pour plus d'informations sur les classes de modèles de documents fournies par le AWS SDK pour .NET, consultez[Utilisation du modèle de document .NET dans DynamoDB](DotNetSDKMidLevel.md). Supposons que vous disposez d’une classe côté client mappée à l’exemple de table `Forum`. Vous pouvez ensuite utiliser un `DynamoDBContext` pour obtenir un élément en tant qu’objet `Document` à partir de la table `Forum`, comme illustré dans l’exemple de code C\$1 suivant. **Example** ``` DynamoDBContext context = new DynamoDBContext(client); Forum forum101 = context.Load(101); // Retrieve a forum by primary key. Document doc = context.ToDocument(forum101); ``` ## Spécification de paramètres facultatifs pour Dynamo DBContext Lors de l’utilisation du modèle de persistance des objets, vous pouvez spécifier les paramètres facultatifs suivants pour le `DynamoDBContext`. + **`ConsistentRead` – **Lors de la récupération de données à l’aide des opérations `Load`, `Query` ou `Scan`, vous pouvez ajouter ce paramètre facultatif pour demander les dernières valeurs pour les données. + **`IgnoreNullValues` – **Ce paramètre informe `DynamoDBContext` d’ignorer les valeurs null sur les attributs lors d’une opération `Save`. Si ce paramètre a la valeur false (ou s’il n’est pas défini), une valeur null est interprétée comme une directive pour supprimer l’attribut spécifique. + **`SkipVersionCheck` – **Ce paramètre informe `DynamoDBContext` ne pas comparer les versions lors de l’enregistrement ou de la suppression d’un élément. Pour plus d’informations sur la gestion des versions, consultez [Verrouillage optimiste à l'aide de DynamoDB et du modèle de persistance des objets AWS SDK pour .NET](DynamoDBContext.VersionSupport.md). + **`TableNamePrefix` – **Préfixe tous les noms de table avec une chaîne spécifique. Si ce paramètre a la valeur null (ou s’il n’est pas défini), aucun préfixe n’est utilisé. + `DynamoDBEntryConversion` – Spécifie le schéma de conversion utilisé par le client. Vous pouvez définir ce paramètre sur la version V1 ou V2. V1 est la version par défaut. En fonction de la version que vous définissez, le comportement de ce paramètre change. Par exemple : + Dans la version 1, le type de données `bool` est converti en type numérique `N`, où 0 représente false et 1 représente true. Dans la version 2, `bool` est converti en `BOOL`. + Dans la version 2, les listes et les tableaux ne sont pas regroupés avec HashSets. Les listes et tableaux de nombres, de types basés sur des chaînes et de types binaires sont convertis en type `L` (Liste), qui peut être envoyé vide pour mettre à jour une liste. Ce n’est pas le cas de la version 1, dans laquelle une liste vide n’est pas envoyée sur le réseau. Dans la version 1, les types de collection, tels que List HashSet, et les tableaux sont traités de la même manière. La liste et le tableau de chiffres sont convertis au type `NS` (ensemble de nombres). HashSet L’exemple suivant définit la version du schéma de conversion sur V2, ce qui modifie le comportement de conversion entre les types .NET et les types de données DynamoDB. ``` var config = new DynamoDBContextConfig { Conversion = DynamoDBEntryConversion.V2 }; var contextV2 = new DynamoDBContext(client, config); ``` L’exemple de code C\$1 suivant crée un nouveau `DynamoDBContext` en spécifiant deux des paramètres facultatifs précédents, `ConsistentRead` et `SkipVersionCheck`. **Example** ``` AmazonDynamoDBClient client = new AmazonDynamoDBClient(); ... DynamoDBContext context = new DynamoDBContext(client, new DynamoDBContextConfig { ConsistentRead = true, SkipVersionCheck = true}); ``` `DynamoDBContext` inclut ces paramètres facultatifs avec chaque demande que vous envoyez à l’aide de ce contexte. Au lieu de définir ces paramètres au niveau de `DynamoDBContext`, vous pouvez les spécifier pour des opérations individuelles que vous exécutez à l’aide de `DynamoDBContext`, comme illustré dans l’exemple de code C\$1 suivant. L’exemple charge un élément livre spécifique. La méthode `Load` de `DynamoDBContext` spécifie les paramètres facultatifs précédents, `ConsistentRead` et `SkipVersionCheck`. **Example** ``` AmazonDynamoDBClient client = new AmazonDynamoDBClient(); ... DynamoDBContext context = new DynamoDBContext(client); Book bookItem = context.Load(productId,new DynamoDBContextConfig{ ConsistentRead = true, SkipVersionCheck = true }); ``` Dans ce cas, `DynamoDBContext` inclut ces paramètres uniquement lors de l’envoi de la demande `Get`. # Verrouillage optimiste à l'aide de DynamoDB et du modèle de persistance des objets AWS SDK pour .NET La prise en charge du verrouillage optimiste dans le modèle de persistance des objets garantit que la version de l’élément pour votre application est identique à la version de l’élément côté serveur avant de mettre à jour ou de supprimer l’élément. Supposons que vous récupérez un élément à mettre à jour. Toutefois, avant de renvoyer vos mises à jour, une autre application met à jour le même élément. Maintenant, votre demande a une copie obsolète de l’élément. A défaut de verrouillage optimiste, toute mise à jour que vous effectuez remplace la mise à jour effectuée par l’autre application. La fonction de verrouillage optimiste du modèle de persistance des objets fournit l’étiquette `DynamoDBVersion` que vous pouvez utiliser pour activer le verrouillage optimiste. Pour utiliser cette fonctionnalité, vous ajoutez une propriété à votre classe pour stocker le numéro de version. Vous ajoutez l’attribut `DynamoDBVersion` à la propriété. Lorsque vous enregistrez l’objet pour la première fois, le `DynamoDBContext` attribue un numéro de version et incrémente cette valeur chaque fois que vous mettez à jour l’élément. Votre demande de mise à jour ou de suppression aboutit uniquement si la version de l’objet côté client correspond au numéro de version de l’élément côté serveur. Si votre application a une copie obsolète de l’élément, elle doit obtenir du serveur la dernière version de l’élément avant de pouvoir le mettre à jour ou le supprimer. L’exemple de code C\$1 suivant définit une classe `Book` avec des attributs de persistance des objets qui la mappent à la table `ProductCatalog`. La propriété `VersionNumber` dans la classe décorée avec l’attribut `DynamoDBVersion` stocke la valeur du numéro de version. **Example** ``` [DynamoDBTable("ProductCatalog")] public class Book { [DynamoDBHashKey] //Partition key public int Id { get; set; } [DynamoDBProperty] public string Title { get; set; } [DynamoDBProperty] public string ISBN { get; set; } [DynamoDBProperty("Authors")] public List BookAuthors { get; set; } [DynamoDBVersion] public int? VersionNumber { get; set; } } ``` **Note** Vous pouvez appliquer l’attribut `DynamoDBVersion` uniquement à un type primitif numérique nullable (tel que `int?`). Le verrouillage optimiste a l’impact suivant sur les opérations `DynamoDBContext` : + Pour un nouvel élément, `DynamoDBContext` attribue le numéro de version initial 0. Si vous récupérez un élément existant, mettez à jour une ou plusieurs de ses propriétés, puis tentez d’enregistrer les modifications, l’opération d’enregistrement n’aboutit que si les numéros de version côté client et côté serveur correspondent. `DynamoDBContext` incrémente le numéro de version. Vous n’avez pas besoin de définir le numéro de version. + La méthode `Delete` fournit des surcharges pouvant prendre une valeur de clé primaire ou un objet en tant que paramètre, comme illustré dans l’exemple de code C\$1 suivant. **Example** ``` DynamoDBContext context = new DynamoDBContext(client); ... // Load a book. Book book = context.Load(111); // Do other operations. // Delete 1 - Pass in the book object. context.Delete(book); // Delete 2 - Pass in the Id (primary key) context.Delete(222); ``` Si vous fournissez un objet en tant que paramètre, la suppression ne réussit que si la version de l’objet correspond à la version de l’élément côté serveur. Toutefois, si vous fournissez une valeur de clé primaire en tant que paramètre, `DynamoDBContext` ne connaît aucun numéro de version, et supprime l’élément sans effectuer la vérification de version. Notez que l’implémentation interne du verrouillage optimiste dans le code du modèle de persistance des objets utilise les actions d’API de mise à jour conditionnelle et de suppression conditionnelle dans DynamoDB. ## Désactivation du verrouillage optimiste Pour désactiver le verrouillage optimiste, utilisez la propriété de configuration `SkipVersionCheck`. Vous pouvez définir cette propriété lors de la création de `DynamoDBContext`. Dans ce cas, le verrouillage optimiste est désactivé pour toutes les demandes que vous effectuez à l’aide du contexte. Pour de plus amples informations, veuillez consulter [Spécification de paramètres facultatifs pour Dynamo DBContext](DotNetDynamoDBContext.md#OptionalConfigParams). Au lieu de définir la propriété au niveau du contexte, vous pouvez désactiver le verrouillage optimiste pour une opération spécifique, comme dans l’exemple de code C\$1 suivant. L’exemple utilise le contexte pour supprimer un élément livre. La méthode `Delete` définit la propriété `SkipVersionCheck` sur true, ce qui a pour effet de désactiver la vérification de version. **Example** ``` DynamoDBContext context = new DynamoDBContext(client); // Load a book. Book book = context.Load(111); ... // Delete the book. context.Delete(book, new DynamoDBContextConfig { SkipVersionCheck = true }); ``` # Mappage de données arbitraires avec DynamoDB à l'aide AWS SDK pour .NET du modèle de persistance des objets En plus des types .NET pris en charge (voir [Types de données pris en charge](DotNetSDKHighLevel.md#DotNetDynamoDBContext.SupportedTypes)), vous pouvez utiliser des types dans votre application pour lesquels il n’y a pas de mappage direct aux types Amazon DynamoDB. Le modèle de persistance des objets prend en charge le stockage de données de types arbitraires tant que vous fournissez le convertisseur pour convertir les données du type arbitraire au type DynamoDB, et inversement. Le code de convertisseur transforme les données lors de l’enregistrement et du chargement des objets. Vous pouvez créer n’importe quel type côté client. Cependant, les données stockées dans les tables sont l’un des types DynamoDB et, lors de la requête et de l’analyse, toutes les comparaisons de données effectuées sont faites par rapport aux données stockées dans DynamoDB. L’exemple de code C\$1 suivant définit une classe `Book` avec les propriétés `Id`, `Title`, `ISBN` et `Dimension`. La propriété `Dimension` est du `DimensionType` qui décrit les propriétés `Height`, `Width` et `Thickness`. L’exemple de code fournit les méthodes de convertisseur `ToEntry` et `FromEntry` pour convertir les données entre le `DimensionType` et les types de chaîne DynamoDB. Par exemple, lors de l’enregistrement d’une instance `Book`, le convertisseur crée une chaîne de `Dimension` de livre telle que « 8.5x11x.05 ». Lorsque vous récupérez un livre, il convertit la chaîne en instance `DimensionType`. L’exemple mappe le type `Book` à la table `ProductCatalog`. Il enregistre un exemple d’instance `Book`, le récupère, met à jour ses dimensions et enregistre de nouveau le `Book` mis à jour. Pour step-by-step obtenir des instructions sur le test de l'exemple suivant, reportez-vous à[Exemples de code .NET](CodeSamples.DotNet.md). **Example** ``` using System; using System.Collections.Generic; using Amazon.DynamoDBv2; using Amazon.DynamoDBv2.DataModel; using Amazon.DynamoDBv2.DocumentModel; using Amazon.Runtime; using Amazon.SecurityToken; namespace com.amazonaws.codesamples { class HighLevelMappingArbitraryData { private static AmazonDynamoDBClient client = new AmazonDynamoDBClient(); static void Main(string[] args) { try { DynamoDBContext context = new DynamoDBContext(client); // 1. Create a book. DimensionType myBookDimensions = new DimensionType() { Length = 8M, Height = 11M, Thickness = 0.5M }; Book myBook = new Book { Id = 501, Title = "AWS SDK for .NET Object Persistence Model Handling Arbitrary Data", ISBN = "999-9999999999", BookAuthors = new List { "Author 1", "Author 2" }, Dimensions = myBookDimensions }; context.Save(myBook); // 2. Retrieve the book. Book bookRetrieved = context.Load(501); // 3. Update property (book dimensions). bookRetrieved.Dimensions.Height += 1; bookRetrieved.Dimensions.Length += 1; bookRetrieved.Dimensions.Thickness += 0.2M; // Update the book. context.Save(bookRetrieved); Console.WriteLine("To continue, press Enter"); Console.ReadLine(); } catch (AmazonDynamoDBException e) { Console.WriteLine(e.Message); } catch (AmazonServiceException e) { Console.WriteLine(e.Message); } catch (Exception e) { Console.WriteLine(e.Message); } } } [DynamoDBTable("ProductCatalog")] public class Book { [DynamoDBHashKey] //Partition key public int Id { get; set; } [DynamoDBProperty] public string Title { get; set; } [DynamoDBProperty] public string ISBN { get; set; } // Multi-valued (set type) attribute. [DynamoDBProperty("Authors")] public List BookAuthors { get; set; } // Arbitrary type, with a converter to map it to DynamoDB type. [DynamoDBProperty(typeof(DimensionTypeConverter))] public DimensionType Dimensions { get; set; } } public class DimensionType { public decimal Length { get; set; } public decimal Height { get; set; } public decimal Thickness { get; set; } } // Converts the complex type DimensionType to string and vice-versa. public class DimensionTypeConverter : IPropertyConverter { public DynamoDBEntry ToEntry(object value) { DimensionType bookDimensions = value as DimensionType; if (bookDimensions == null) throw new ArgumentOutOfRangeException(); string data = string.Format("{1}{0}{2}{0}{3}", " x ", bookDimensions.Length, bookDimensions.Height, bookDimensions.Thickness); DynamoDBEntry entry = new Primitive { Value = data }; return entry; } public object FromEntry(DynamoDBEntry entry) { Primitive primitive = entry as Primitive; if (primitive == null || !(primitive.Value is String) || string.IsNullOrEmpty((string)primitive.Value)) throw new ArgumentOutOfRangeException(); string[] data = ((string)(primitive.Value)).Split(new string[] { " x " }, StringSplitOptions.None); if (data.Length != 3) throw new ArgumentOutOfRangeException(); DimensionType complexData = new DimensionType { Length = Convert.ToDecimal(data[0]), Height = Convert.ToDecimal(data[1]), Thickness = Convert.ToDecimal(data[2]) }; return complexData; } } } ```