Migration d’une application de façon à utiliser le SDK .NET Azure Cosmos DB v3

  • Article

S’APPLIQUE À : NoSQL

Important

Pour en savoir plus sur le Kit de développement logiciel (SDK) .NET Azure Cosmos DB v3, consultez les notes de publication, le référentiel GitHub .NET, les conseils de performances du Kit de développement logiciel (SDK) .NET v3 et le guide de résolution des problèmes.

Cet article souligne quelques-unes des considérations relatives à la mise à niveau de votre application .NET existante vers le Kit de développement logiciel (SDK) .NET Azure Cosmos DB v3 plus récent pour l’API pour NoSQL. Le Kit de développement logiciel (SDK) .NET Azure Cosmos DB v3 correspond à l’espace de noms Microsoft.Azure.Azure Cosmos DB. Vous pouvez utiliser les informations fournies dans ce document si vous migrez votre application à partir de l’un des Kits de développement logiciel (SDK) .NET Azure Cosmos DB suivants :

  • Kit de développement logiciel (SDK) .NET Framework Azure Cosmos DB v2 pour l’API pour NoSQL
  • Kit de développement logiciel (SDK) .NET Core Azure Cosmos DB v2 pour l’API pour NoSQL

Les instructions de cet article vous aideront également à migrer les bibliothèques externes suivantes, qui font désormais partie du Kit de développement logiciel (SDK) .NET Azure Cosmos DB v3 pour l’API pour NoSQL :

  • Bibliothèque du processeur de flux de modification .NET 2.0
  • Bibliothèque d’exécuteur en bloc .NET 1.1 ou ultérieure

Nouveautés dans le Kit de développement logiciel (SDK) .NET v3

Le Kit de développement logiciel (SDK) v3 contient de nombreuses améliorations en matière de convivialité et de performances, notamment :

  • Nom intuitif du modèle de programmation
  • .NET Standard 2.0**
  • Amélioration des performances grâce à la prise en charge de l’API de flux
  • Hiérarchie fluide qui remplace la nécessité d’une fabrique d’URI
  • Prise en charge intégrée des bibliothèques du processeur de flux de modification
  • Prise en charge intégrée des opérations en bloc
  • API Mockable pour faciliter les tests unitaires
  • Prise en charge des lots transactionnels et de Blazor
  • Sérialiseurs enfichables
  • Mise à l’échelle des conteneurs non partitionnés et mise à l’échelle automatique des conteneurs

** Le Kit de développement logiciel (SDK) cible le format .NET Standard 2.0 qui unifie les Kits de développement logiciel (SDK) .NET Framework Azure Cosmos DB et .NET Core existants en un seul SDK .NET. Vous pouvez utiliser le Kit de développement logiciel (SDK) .NET sur n’importe quelle plateforme qui implémente .NET Standard 2.0, y compris vos applications .NET Framework 4.6.1 et ultérieures et vos applications .NET Core 2.0 et ultérieures.

La majeure partie de la mise en réseau, de la logique de nouvelle tentative et des niveaux inférieurs du Kit de développement logiciel (SDK) restent largement inchangée.

Le Kit de développement logiciel (SDK) .NET Azure Cosmos DB v3 est désormais open source. Nous recevons toutes les demandes de tirage et nous enregistrerons les problèmes et suivrons les réactions surGitHub. Nous travaillerons à l’adoption de toute fonctionnalité susceptible d’améliorer l’expérience utilisateur.

Pourquoi migrer vers le Kit de développement logiciel (SDK) .NET v3

Outre les nombreuses améliorations en matière de convivialité et de performances, les nouvelles fonctionnalités investies dans le dernier Kit de développement logiciel (SDK) ne seront pas reportées sur les versions antérieures. Le Kit de développement logiciel (SDK) v2 est actuellement en mode maintenance. Pour une expérience de développement optimale, nous vous recommandons de toujours démarrer avec la version prise en charge la plus récente du Kit de développement logiciel (SDK).

Changements majeurs de nom du SDK v2 au SDK v3

Les changements de noms suivants ont été appliqués dans l’ensemble du Kit de développement logiciel (SDK) .NET 3.0 pour s’aligner sur les conventions d’affectation de noms de l’API pour NoSQL :

  • DocumentClient est renommé CosmosClient
  • Collection est renommé Container
  • Document est renommé Item

Tous les objets de ressource sont renommés avec des propriétés supplémentaires, qui incluent le nom de la ressource pour plus de clarté.

Voici quelques-uns des principaux changements apportés aux noms de classe :

SDK .NET v2 SDK .NET v3
Microsoft.Azure.Documents.Client.DocumentClient Microsoft.Azure.Cosmos.CosmosClient
Microsoft.Azure.Documents.Client.ConnectionPolicy Microsoft.Azure.Cosmos.CosmosClientOptions
Microsoft.Azure.Documents.Client.DocumentClientException Microsoft.Azure.Cosmos.CosmosException
Microsoft.Azure.Documents.Client.Database Microsoft.Azure.Cosmos.DatabaseProperties
Microsoft.Azure.Documents.Client.DocumentCollection Microsoft.Azure.Cosmos.ContainerProperties
Microsoft.Azure.Documents.Client.RequestOptions Microsoft.Azure.Cosmos.ItemRequestOptions
Microsoft.Azure.Documents.Client.FeedOptions Microsoft.Azure.Cosmos.QueryRequestOptions
Microsoft.Azure.Documents.Client.StoredProcedure Microsoft.Azure.Cosmos.StoredProcedureProperties
Microsoft.Azure.Documents.Client.Trigger Microsoft.Azure.Cosmos.TriggerProperties
Microsoft.Azure.Documents.SqlQuerySpec Microsoft.Azure.Cosmos.QueryDefinition

Classes remplacées dans le Kit de développement logiciel (SDK) .NET v3

Les classes suivantes ont été remplacées dans le Kit de développement logiciel (SDK) 3.0 :

  • Microsoft.Azure.Documents.UriFactory

La classe Microsoft.Azure.Documents.UriFactory a été remplacée par la conception fluide.

Container container = client.GetContainer(databaseName,containerName);
ItemResponse<SalesOrder> response = await this._container.CreateItemAsync(
        salesOrder,
        new PartitionKey(salesOrder.AccountNumber));
  • Microsoft.Azure.Documents.Document

Étant donné que le Kit de développement logiciel (SDK) .NET v3 permet aux utilisateurs de configurer un moteur de sérialisation personnalisé, il n’existe aucun remplacement direct pour le type Document. Lorsque vous utilisez Newtonsoft.Json (moteur de sérialisation par défaut), JObject peut être utilisé pour obtenir la même fonctionnalité. Quand vous utilisez un autre moteur de sérialisation, vous pouvez utiliser son type de document JSON de base (par exemple, JsonDocument pour System.Text.Json). Il est recommandé d’utiliser un type C# qui reflète le schéma de vos éléments au lieu de vous appuyer sur des types génériques.

  • Microsoft.Azure.Documents.Resource

Il n’existe aucun remplacement direct pour Resource, dans les cas où il a été utilisé pour les documents, suivez les instructions pour Document.

  • Microsoft.Azure.Documents.AccessCondition

IfNoneMatch ou IfMatch sont désormais disponibles directement sur le Microsoft.Azure.Cosmos.ItemRequestOptions .

Modifications apportées à la génération d’ID d’élément

L’ID d’élément n’est plus renseigné automatiquement dans le Kit de développement logiciel (SDK) .NET v3. Par conséquent, l’ID de l’élément doit inclure spécifiquement un ID généré. Consultez l’exemple suivant :

[JsonProperty(PropertyName = "id")]
public Guid Id { get; set; }

Modification du comportement par défaut pour le mode de connexion

Le Kit de développement logiciel (SDK) v3 est désormais défini par défaut sur les modes de connexion Direct + TCP par rapport au SDK v2 précédent, qui était défini par défaut sur les modes de connexion Passerelle + HTTPS. Cette modification permet d’améliorer les performances et la scalabilité.

Modifications apportées à FeedOptions (QueryRequestOptions dans le SDK v3.0)

La classe FeedOptions dans le Kit de développement logiciel (SDK) v2 a été renommée QueryRequestOptions dans le Kit de développement logiciel (SDK) v3 et, dans la classe, plusieurs propriétés ont subi des modifications de nom et/ou de valeur par défaut ou ont été supprimées complètement.

SDK .NET v2 SDK .NET v3
FeedOptions.MaxDegreeOfParallelism QueryRequestOptions.MaxConcurrency - la valeur par défaut et le comportement associé restent les mêmes, et les opérations exécutées côté client pendant l’exécution d’une requête parallèle seront exécutées en série sans parallélisme.
FeedOptions.PartitionKey QueryRequestOptions.PartitionKey - Comportement maintenu
FeedOptions.EnableCrossPartitionQuery Supprimé. Comportement par défaut dans le Kit de développement logiciel (SDK) 3.0 est que les requêtes entre les partitions seront exécutées sans qu’il soit nécessaire d’activer la propriété spécifiquement.
FeedOptions.PopulateQueryMetrics Supprimé. Il est désormais activé par défaut et fait partie des diagnostics.
FeedOptions.RequestContinuation Supprimé. Il a maintenant été promu aux méthodes de requête elles-mêmes.
FeedOptions.JsonSerializerSettings Supprimé. Pour plus d’informations, découvrez comment personnaliser la sérialisation.
FeedOptions.PartitionKeyRangeId Supprimé. Le même résultat peut être obtenu à partir de l’utilisation de FeedRange comme entrée dans la méthode de requête.
FeedOptions.DisableRUPerMinuteUsage Supprimé.

Construction d’un client

Le Kit de développement logiciel (SDK) .NET v3 fournit une classe CosmosClientBuilder fluide qui remplace la nécessité d’une fabrique d’URI pour le SDK v2.

La conception fluide crée des URL en interne et permet de faire circuler un objet Container unique à la place des objets DocumentClient, DatabaseName et DocumentCollection.

L’exemple suivant crée une propriété CosmosClientBuilder avec un ConsistencyLevel fort et une liste d’emplacements par défaut :

CosmosClientBuilder cosmosClientBuilder = new CosmosClientBuilder(
    accountEndpoint: "https://testcosmos.documents.azure.com:443/",
    authKeyOrResourceToken: "SuperSecretKey")
.WithConsistencyLevel(ConsistencyLevel.Strong)
.WithApplicationRegion(Regions.EastUS);
CosmosClient client = cosmosClientBuilder.Build();

Exceptions

Alors que le kit de développement logiciel (SDK) v2 utilisait DocumentClientException pour signaler des erreurs pendant des opérations, le kit de développement logiciel (SDK) v3 utilise CosmosException, qui expose les informations relatives aux réponses StatusCode, Diagnostics et autres. Toutes les informations complètes sont sérialisées lors de l’utilisation de la méthode ToString() :

catch (CosmosException ex)
{
    HttpStatusCode statusCode = ex.StatusCode;
    CosmosDiagnostics diagnostics = ex.Diagnostics;
    // store diagnostics optionally with diagnostics.ToString();
    // or log the entire error details with ex.ToString();
}

Diagnostics

Alors que le kit de développement logiciel (SDK) v2 avait des diagnostics uniquement directs disponibles via la propriété RequestDiagnosticsString, le kit de développement logiciel (SDK) v3 utilise les Diagnostics disponibles dans toutes les réponses et exceptions, qui sont plus riches et non limitées au mode direct. Elles incluent non seulement le temps passé sur le kit de développement logiciel (SDK) pour l’opération, mais également les régions que l’opération a contactées :

try
{
    ItemResponse<MyItem> response = await container.ReadItemAsync<MyItem>(
                    partitionKey: new PartitionKey("MyPartitionKey"),
                    id: "MyId");
    
    TimeSpan elapsedTime = response.Diagnostics.GetElapsedTime();
    if (elapsedTime > somePreDefinedThreshold)
    {
        // log response.Diagnostics.ToString();
        IReadOnlyList<(string region, Uri uri)> regions = response.Diagnostics.GetContactedRegions();
    }
}
catch (CosmosException cosmosException) {
    string diagnostics = cosmosException.Diagnostics.ToString();
    
    TimeSpan elapsedTime = cosmosException.Diagnostics.GetElapsedTime();
    
    IReadOnlyList<(string region, Uri uri)> regions = cosmosException.Diagnostics.GetContactedRegions();
    
    // log cosmosException.ToString()
}

ConnectionPolicy

Certains paramètres dans ConnectionPolicy ont été renommés ou remplacés par CosmosClientOptions :

SDK .NET v2 SDK .NET v3
EnableEndpointDiscovery LimitToEndpoint – La valeur est désormais inversée. Si EnableEndpointDiscovery était défini sur true, LimitToEndpoint doit être défini sur false. Avant d’utiliser ce paramètre, vous devez comprendre comment il affecte le client.
ConnectionProtocol Supprimé. Le protocole est lié au mode, qu’il s’agisse de la passerelle (HTTP) ou du mode direct (TCP). Le mode direct avec le protocole HTTPS n’est plus pris en charge sur le Kit de développement logiciel (SDK) v3, et il est recommandé d’utiliser le protocole TCP.
MediaRequestTimeout Supprimé. Les pièces jointes ne sont plus prises en charge.
SetCurrentLocation CosmosClientOptions.ApplicationRegion peut être utilisé pour obtenir le même effet.
PreferredLocations CosmosClientOptions.ApplicationPreferredRegions peut être utilisé pour obtenir le même effet.
UserAgentSuffix CosmosClientBuilder.ApplicationName peut être utilisé pour obtenir le même effet.
UseMultipleWriteLocations Supprimé. Le Kit de développement logiciel (SDK) détecte automatiquement la prise en charge par le compte de multiples points de terminaison d’écriture.

Stratégie d’indexation

La stratégie d’indexation ne permet pas de configurer ces propriétés. Lorsque ces propriétés ne sont pas spécifiées, leurs valeurs par défaut sont les suivantes :

Nom de la propriété Nouvelle valeur (non configurable)
Kind range
dataType String et Number

Consultez cette section pour obtenir des exemples de stratégie d’indexation pour l’inclusion et l’exclusion de chemins d’accès. En raison des améliorations apportées au moteur de requête, la configuration de ces propriétés, même en utilisant une ancienne version du Kit de développement logiciel (SDK), n’a aucun impact sur les performances.

Jeton de session

Alors que le kit de développement logiciel (SDK) v2 exposait le jeton de session d’une réponse comme ResourceResponse.SessionToken quand la capture du jeton de session était requise, parce que le jeton de session est un en-tête, le SDK v3 expose cette valeur dans la propriété Headers.Session de toute réponse.

Timestamp

Alors que le kit de développement logiciel (SDK) v2 exposait l’horodateur (timestamp) d’un document via la propriété Timestamp, parce que Document n’est plus disponible, les utilisateurs peuvent mapper la Timestamp_ts à une propriété dans leur modèle.

OpenAsync

Pour les cas d’utilisation où OpenAsync() était utilisé pour le préchauffage du client SDK v2, CreateAndInitializeAsync peut être utilisé pour OpenAsync() un client SDK v3.

Utilisation des API du processeur de flux de modification directement à partir du SDK v3

Le Kit de développement logiciel (SDK) v3 offre une prise en charge intégrée des API du processeur de flux de modification, ce qui vous permet d’utiliser le même SDK pour générer votre application et modifier l’implémentation du processeur de flux. Auparavant, vous deviez utiliser une bibliothèque du processeur de flux de modification distincte.

Pour plus d’informations, consultez comment migrer de la bibliothèque du processeur de flux de modification vers le Kit de développement logiciel (SDK) .NET Azure Cosmos DB v3.

Requêtes de flux de modification

L’exécution de requêtes de flux de modification sur le kit de développement logiciel (SDK) v3 est considérée comme utilisant le modèle d’extraction de flux de modification. Suivez ce tableau pour migrer la configuration :

SDK .NET v2 SDK .NET v3
ChangeFeedOptions.PartitionKeyRangeId FeedRange - Pour obtenir un parallélisme qui lit le flux de modification, FeedRanges peut être utilisé. Il ne s’agit plus d’un paramètre obligatoire, vous pouvez maintenant facilement lire le flux de modification pour un conteneur entier.
ChangeFeedOptions.PartitionKey FeedRange.FromPartitionKey - Un FeedRange représentant la clé de partition souhaitée peut être utilisé pour lire le flux de modification de cette valeur de clé de partition.
ChangeFeedOptions.RequestContinuation ChangeFeedStartFrom.Continuation - L’itérateur de flux de modification peut être arrêté et repris à tout moment en enregistrant la continuation et en l’utilisant lors de la création d’un itérateur.
ChangeFeedOptions.StartTime ChangeFeedStartFrom.Time
ChangeFeedOptions.StartFromBeginning ChangeFeedStartFrom.Beginning
ChangeFeedOptions.MaxItemCount ChangeFeedRequestOptions.PageSizeHint - L’itérateur de flux de modification peut être arrêté et repris à tout moment en enregistrant la continuation et en l’utilisant lors de la création d’un itérateur.
IDocumentQuery.HasMoreResults response.StatusCode == HttpStatusCode.NotModified - Le flux de modification est conceptuellement infini, il peut donc toujours y avoir plus de résultats. Lorsqu’une réponse contient le code d’état HttpStatusCode.NotModified, cela signifie qu’il n’y a pas de nouvelles modifications à lire pour l’instant. Vous pouvez l’utiliser pour arrêter et enregistrer la continuation ou pour veiller temporairement ou attendre, puis appeler ReadNextAsync à nouveau pour tester les nouvelles modifications.
Gestion des fractionnements Il n’est plus nécessaire aux utilisateurs de gérer les exceptions fractionnées lors de la lecture du flux de modification ; les fractionnements sont gérés de manière transparente sans avoir besoin d’interaction de l’utilisateur.

Utilisation de la bibliothèque d’exécuteur en bloc directement à partir du Kit de développement logiciel (SDK) v3

Le Kit de développement logiciel (SDK) v3 offre une prise en charge intégrée de la bibliothèque d’exécuteur en bloc, ce qui vous permet d’utiliser le même Kit de développement logiciel (SDK) pour créer votre application et effectuer des opérations en bloc. Auparavant, vous deviez utiliser une bibliothèque d’exécuteur en bloc distincte.

Pour plus d’informations, consultez Comment migrer de la bibliothèque d’exécuteur en bloc vers la prise en charge en bloc dans le SDK .NET Azure Cosmos DB v3

Personnalisation de la sérialisation

Le SDK .NET V2 permet de définir JsonSerializerSettings dans RequestOptions au niveau opérationnel utilisé pour désérialiser le document de résultat :

// .NET V2 SDK
var result = await container.ReplaceDocumentAsync(document, new RequestOptions { JsonSerializerSettings = customSerializerSettings })

Le SDK .NET v3 fournit une interface de sérialiseur pour entièrement personnaliser le moteur de sérialisation ou des options de sérialisation plus génériques dans le cadre de la construction du client.

La personnalisation de la sérialisation au niveau de l’opération peut être effectuée à l’aide des API Stream :

// .NET V3 SDK
using(Response response = await this.container.ReplaceItemStreamAsync(stream, "itemId", new PartitionKey("itemPartitionKey"))
{

    using(Stream stream = response.ContentStream)
    {
        using (StreamReader streamReader = new StreamReader(stream))
        {
            // Read the stream and do dynamic deserialization based on type with a custom Serializer
        }
    }
}

Comparaison d’extraits de code

L’extrait de code suivant montre les différences dans la façon dont les ressources sont créées entre les Kits de développement logiciel (SDK) .NET v2 et v3.

Opérations de base de données

Création d'une base de données

// Create database with no shared provisioned throughput
DatabaseResponse databaseResponse = await client.CreateDatabaseIfNotExistsAsync(DatabaseName);
Database database = databaseResponse;
DatabaseProperties databaseProperties = databaseResponse;

// Create a database with a shared manual provisioned throughput
string databaseIdManual = new string(DatabaseName + "_SharedManualThroughput");
database = await client.CreateDatabaseIfNotExistsAsync(databaseIdManual, ThroughputProperties.CreateManualThroughput(400));

// Create a database with shared autoscale provisioned throughput
string databaseIdAutoscale = new string(DatabaseName + "_SharedAutoscaleThroughput");
database = await client.CreateDatabaseIfNotExistsAsync(databaseIdAutoscale, ThroughputProperties.CreateAutoscaleThroughput(4000));

Lire une base de données par identifiant

// Read a database
Console.WriteLine($"{Environment.NewLine} Read database resource: {DatabaseName}");
database = client.GetDatabase(DatabaseName);
Console.WriteLine($"{Environment.NewLine} database { database.Id.ToString()}");

// Read all databases
string findQueryText = "SELECT * FROM c";
using (FeedIterator<DatabaseProperties> feedIterator = client.GetDatabaseQueryIterator<DatabaseProperties>(findQueryText))
{
    while (feedIterator.HasMoreResults)
    {
        FeedResponse<DatabaseProperties> databaseResponses = await feedIterator.ReadNextAsync();
        foreach (DatabaseProperties _database in databaseResponses)
        {
            Console.WriteLine($"{ Environment.NewLine} database {_database.Id.ToString()}");
        }
    }
}

Supprimer une base de données

// Delete a database
await client.GetDatabase(DatabaseName).DeleteAsync();
Console.WriteLine($"{ Environment.NewLine} database {DatabaseName} deleted.");

// Delete all databases in an account
string deleteQueryText = "SELECT * FROM c";
using (FeedIterator<DatabaseProperties> feedIterator = client.GetDatabaseQueryIterator<DatabaseProperties>(deleteQueryText))
{
    while (feedIterator.HasMoreResults)
    {
        FeedResponse<DatabaseProperties> databaseResponses = await feedIterator.ReadNextAsync();
        foreach (DatabaseProperties _database in databaseResponses)
        {
            await client.GetDatabase(_database.Id).DeleteAsync();
            Console.WriteLine($"{ Environment.NewLine} database {_database.Id} deleted");
        }
    }
}

Opérations sur les conteneurs

Créer un conteneur (mise à l’échelle automatique + durée de vie avec expiration)

private static async Task CreateManualThroughputContainer(Database database)
{
    // Set throughput to the minimum value of 400 RU/s manually configured throughput
    string containerIdManual = ContainerName + "_Manual";
    ContainerResponse container = await database.CreateContainerIfNotExistsAsync(
        id: containerIdManual,
        partitionKeyPath: partitionKeyPath,
        throughput: 400);
}

// Create container with autoscale
private static async Task CreateAutoscaleThroughputContainer(Database database)
{
    string autoscaleContainerId = ContainerName + "_Autoscale";
    ContainerProperties containerProperties = new ContainerProperties(autoscaleContainerId, partitionKeyPath);

    Container container = await database.CreateContainerIfNotExistsAsync(
        containerProperties: containerProperties,
        throughputProperties: ThroughputProperties.CreateAutoscaleThroughput(autoscaleMaxThroughput: 4000);
}

// Create a container with TTL Expiration
private static async Task CreateContainerWithTtlExpiration(Database database)
{
    string containerIdManualwithTTL = ContainerName + "_ManualTTL";

    ContainerProperties properties = new ContainerProperties
        (id: containerIdManualwithTTL,
        partitionKeyPath: partitionKeyPath);

    properties.DefaultTimeToLive = (int)TimeSpan.FromDays(1).TotalSeconds; //expire in 1 day

    ContainerResponse containerResponse = await database.CreateContainerIfNotExistsAsync(containerProperties: properties);
    ContainerProperties returnedProperties = containerResponse;
}

Lire les propriétés du conteneur

private static async Task ReadContainerProperties(Database database)
{
    string containerIdManual = ContainerName + "_Manual";
    Container container = database.GetContainer(containerIdManual);
    ContainerProperties containerProperties = await container.ReadContainerAsync();
}

Supprimer un conteneur

private static async Task DeleteContainers(Database database)
{
    string containerIdManual = ContainerName + "_Manual";

    // Delete a container
    await database.GetContainer(containerIdManual).DeleteContainerAsync();

    // Delete all CosmosContainer resources for a database
    using (FeedIterator<ContainerProperties> feedIterator = database.GetContainerQueryIterator<ContainerProperties>())
    {
        while (feedIterator.HasMoreResults)
        {
            foreach (ContainerProperties _container in await feedIterator.ReadNextAsync())
            {
                await database.GetContainer(_container.Id).DeleteContainerAsync();
                Console.WriteLine($"{Environment.NewLine}  deleted container {_container.Id}");
            }
        }
    }
}

Opérations sur les éléments et les requêtes

Créer un élément

private static async Task CreateItemAsync(Container container)
{
    // Create a SalesOrder POCO object
    SalesOrder salesOrder1 = GetSalesOrderSample("Account1", "SalesOrder1");
    ItemResponse<SalesOrder> response = await container.CreateItemAsync(salesOrder1,
        new PartitionKey(salesOrder1.AccountNumber));
}

private static async Task RunBasicOperationsOnDynamicObjects(Container container)
{
    // Dynamic Object
    dynamic salesOrder = new
    {
        id = "SalesOrder5",
        AccountNumber = "Account1",
        PurchaseOrderNumber = "PO18009186470",
        OrderDate = DateTime.UtcNow,
        Total = 5.95,
    };
    Console.WriteLine("\nCreating item");
    ItemResponse<dynamic> response = await container.CreateItemAsync<dynamic>(
        salesOrder, new PartitionKey(salesOrder.AccountNumber));
    dynamic createdSalesOrder = response.Resource;
}

Lire tous les éléments figurant dans un conteneur

private static async Task ReadAllItems(Container container)
{
    // Read all items in a container
    List<SalesOrder> allSalesForAccount1 = new List<SalesOrder>();

    using (FeedIterator<SalesOrder> resultSet = container.GetItemQueryIterator<SalesOrder>(
        queryDefinition: null,
        requestOptions: new QueryRequestOptions()
        {
            PartitionKey = new PartitionKey("Account1"),
            MaxItemCount = 5
        }))
    {
        while (resultSet.HasMoreResults)
        {
            FeedResponse<SalesOrder> response = await resultSet.ReadNextAsync();
            SalesOrder salesOrder = response.First();
            Console.WriteLine($"\n1.3.1 Account Number: {salesOrder.AccountNumber}; Id: {salesOrder.Id}");
            allSalesForAccount1.AddRange(response);
        }
    }
}

Éléments de requête

Modifications apportées à SqlQuerySpec (QueryDefinition dans le kit de développement logiciel v3.0)

La classe SqlQuerySpec du kit de développement logiciel v2 a maintenant été renommée QueryDefinition dans le kit de développement logiciel v3.

SqlParameterCollection et SqlParameter ont été supprimés. Les paramètres sont désormais ajoutés à QueryDefinition avec un modèle de générateur à l’aide de QueryDefinition.WithParameter. Les utilisateurs peuvent accéder aux paramètres avec QueryDefinition.GetQueryParameters

private static async Task QueryItems(Container container)
{
    // Query for items by a property other than Id
    QueryDefinition queryDefinition = new QueryDefinition(
        "select * from sales s where s.AccountNumber = @AccountInput")
        .WithParameter("@AccountInput", "Account1");

    List<SalesOrder> allSalesForAccount1 = new List<SalesOrder>();
    using (FeedIterator<SalesOrder> resultSet = container.GetItemQueryIterator<SalesOrder>(
        queryDefinition,
        requestOptions: new QueryRequestOptions()
        {
            PartitionKey = new PartitionKey("Account1"),
            MaxItemCount = 1
        }))
    {
        while (resultSet.HasMoreResults)
        {
            FeedResponse<SalesOrder> response = await resultSet.ReadNextAsync();
            SalesOrder sale = response.First();
            Console.WriteLine($"\n Account Number: {sale.AccountNumber}; Id: {sale.Id};");
            allSalesForAccount1.AddRange(response);
        }
    }
}

Supprimer un élément

private static async Task DeleteItemAsync(Container container)
{
    ItemResponse<SalesOrder> response = await container.DeleteItemAsync<SalesOrder>(
        partitionKey: new PartitionKey("Account1"), id: "SalesOrder3");
}

Requête de flux de modification

private static async Task QueryChangeFeedAsync(Container container)
{
    FeedIterator<SalesOrder> iterator = container.GetChangeFeedIterator<SalesOrder>(ChangeFeedStartFrom.Beginning(), ChangeFeedMode.Incremental);

    string continuation = null;
    while (iterator.HasMoreResults)
    {
        FeedResponse<SalesOrder> response = await iteratorForTheEntireContainer.ReadNextAsync();
    
        if (response.StatusCode == HttpStatusCode.NotModified)
        {
            // No new changes
            continuation = response.ContinuationToken;
            break;
        }
        else 
        {
            // Process the documents in response
        }
    }
}

Étapes suivantes