Freigeben über


Migrieren Ihrer Anwendung zur Verwendung des Azure Cosmos DB .NET SDK v3

Von Bedeutung

Weitere Informationen zum Azure Cosmos DB .NET SDK v3 finden Sie in den Versionshinweisen, dem .NET GitHub-Repository, .NET SDK v3 Leistungstipps und dem Handbuch zur Problembehandlung.

In diesem Artikel werden einige Überlegungen beim Upgrade Ihrer vorhandenen .NET-Anwendung auf das neuere Azure Cosmos DB .NET SDK v3 für die API für NoSQL dargelegt. Azure Cosmos DB .NET SDK v3 entspricht dem Microsoft.Azure.Azure Cosmos DB-Namespace. Sie können die in diesem Dokument bereitgestellten Informationen verwenden, wenn Sie Ihre Anwendung aus einem der folgenden Azure Cosmos DB .NET SDKs migrieren:

  • Azure Cosmos DB .NET Framework SDK v2 für API für NoSQL
  • Azure Cosmos DB .NET Core SDK v2 für API für NoSQL

Die Anweisungen in diesem Artikel helfen Ihnen auch beim Migrieren der folgenden externen Bibliotheken, die jetzt Teil des Azure Cosmos DB .NET SDK v3 für API für NoSQL sind:

  • .NET-Change-Feed-Prozessorbibliothek 2.0
  • .NET Bulk Executor Library 1.1 oder höher

Neuerungen im .NET V3 SDK

Das v3 SDK enthält viele Verbesserungen der Benutzerfreundlichkeit und Leistung, darunter:

  • Intuitive Programmierungsmodellbenennung
  • .NET Standard 2.0 **
  • Erhöhte Leistung durch Stream-API-Unterstützung
  • Fluent-Hierarchie, die die Notwendigkeit der URI-Factory ersetzt
  • Integrierte Unterstützung für die Change Feed Processor-Bibliothek
  • Integrierte Unterstützung für Massenoperationen
  • Simulierte APIs für einfachere Komponententests
  • Batch-Verarbeitung für Transaktionen und Blazor-Unterstützung
  • Austauschbare Serialisierer
  • Skalieren nicht partitionierter und automatisch skalierter Container

** Das SDK zielt auf .NET Standard 2.0 ab, das die vorhandenen Azure Cosmos DB .NET Framework und .NET Core SDKs in einem einzigen .NET SDK vereint. Sie können das .NET SDK in jeder Plattform verwenden, die .NET Standard 2.0 implementiert, einschließlich Ihrer .NET Framework 4.6.1+ und .NET Core 2.0+-Anwendungen.

Die meisten Netzwerk-, Wiederholungslogik- und niedrigeren Ebenen des SDK bleiben weitgehend unverändert.

Das Azure Cosmos DB .NET SDK v3 ist jetzt Open Source. Wir begrüßen alle Pull-Anforderungen und protokollieren Probleme und verfolgen Feedback auf GitHub. Wir arbeiten daran, alle Features zu übernehmen, die die Benutzerfreundlichkeit verbessern.

Gründe für die Migration zum .NET v3 SDK

Neben den zahlreichen Verbesserungen an Benutzerfreundlichkeit und Leistung werden neue, im neuesten SDK vorgenommene Featureinvestitionen nicht wieder zu älteren Versionen portiert. Das v2 SDK befindet sich derzeit im Wartungsmodus. Für eine optimale Entwicklungsumgebung empfehlen wir, immer mit der neuesten unterstützten Version des SDK zu beginnen.

Wichtige Namensänderungen von v2 SDK zu v3 SDK

Die folgenden Namensänderungen wurden im .NET 3.0 SDK angewendet, um die API-Benennungskonventionen für die API für NoSQL auszurichten:

  • DocumentClient wird umbenannt in CosmosClient
  • Collection wird umbenannt in Container
  • Document wird umbenannt in Item

Alle Ressourcenobjekte werden mit zusätzlichen Eigenschaften umbenannt, die den Ressourcennamen zur Übersichtlichkeit enthalten.

Im Folgenden sind einige der Hauptklassennamenänderungen aufgeführt:

.NET v2 SDK .NET v3 SDK
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

Klassen, die im .NET v3 SDK ersetzt wurden

Die folgenden Klassen wurden im 3.0 SDK ersetzt:

  • Microsoft.Azure.Documents.UriFactory

Die Microsoft.Azure.Documents.UriFactory-Klasse wurde durch das Fluent-Design ersetzt.

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

  • Microsoft.Azure.Documents.Document

Da das .NET v3 SDK Benutzern das Konfigurieren eines benutzerdefinierten Serialisierungsmoduls ermöglicht, gibt es keinen direkten Ersatz für den Document Typ. Bei Verwendung von Newtonsoft.Json (Standard-Serialisierungsmodul) kann JObject verwendet werden, um die gleiche Funktionalität zu erzielen. Bei Verwendung einer anderen Serialisierungsengine können Sie deren Basis-JSON-Dokumenttyp verwenden (zum Beispiel JsonDocument für System.Text.Json). Es wird empfohlen, einen C#-Typ zu verwenden, der das Schema Ihrer Elemente widerspiegelt, anstatt auf generische Typen zu vertrauen.

  • Microsoft.Azure.Documents.Resource

Es gibt keinen direkten Ersatz für Resource, in Fällen, in denen sie für Dokumente verwendet wurde, folgen Sie den Anweisungen für Document.

  • Microsoft.Azure.Documents.AccessCondition

IfNoneMatch oder IfMatch sind jetzt auf Microsoft.Azure.Cosmos.ItemRequestOptions direkt verfügbar.

Änderungen an der Element-ID-Generierung

Die Element-ID wird im .NET v3 SDK nicht mehr automatisch ausgefüllt. Daher muss die Element-ID ausdrücklich eine generierte ID enthalten. Sehen Sie sich das folgende Beispiel an:

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

Standardverhalten für den Verbindungsmodus geändert

Das SDK v3 verwendet jetzt standardmäßig die Verbindungsmodi „Direct“ und „TCP“, während für das vorherige SDK v2 standardmäßig die Verbindungsmodi „Gateway“ und „HTTPS“ festgelegt waren. Diese Änderung bietet eine verbesserte Leistung und Skalierbarkeit.

Änderungen an FeedOptions (QueryRequestOptions in v3.0 SDK)

Die FeedOptions Klasse in SDK v2 wurde nun in das SDK v3 umbenannt QueryRequestOptions und innerhalb der Klasse wurden mehrere Eigenschaften in Name und/oder Standardwert geändert oder vollständig entfernt.

.NET v2 SDK .NET v3 SDK
FeedOptions.MaxDegreeOfParallelism QueryRequestOptions.MaxConcurrency - Standardwert und zugehöriges Verhalten bleiben gleich, die Vorgänge werden clientseitig während der parallelen Abfrageausführung seriell ohne Parallelität ausgeführt.
FeedOptions.PartitionKey QueryRequestOptions.PartitionKey - Verhalten beibehalten.
FeedOptions.EnableCrossPartitionQuery Entfernt. Das Standardverhalten in SDK 3.0 besteht darin, dass partitionsübergreifende Abfragen ausgeführt werden, ohne dass die Eigenschaft explizit aktiviert werden muss.
FeedOptions.PopulateQueryMetrics Entfernt. Sie ist jetzt standardmäßig und Teil der Diagnose aktiviert.
FeedOptions.RequestContinuation Entfernt. Jetzt zu den Abfragemethoden hochgestuft
FeedOptions.JsonSerializerSettings Entfernt. Erfahren Sie, wie Sie die Serialisierung für weitere Informationen anpassen.
FeedOptions.PartitionKeyRangeId Entfernt. Dasselbe Ergebnis kann mithilfe von FeedRange als Eingabe für die Abfragemethode abgerufen werden.
FeedOptions.DisableRUPerMinuteUsage Entfernt.

Erstellen eines Clients

Das .NET SDK v3 bietet eine Fluent-Klasse CosmosClientBuilder , die die Notwendigkeit der SDK v2 URI Factory ersetzt.

Das Fluent-Design erstellt URLs intern und ermöglicht die Übergabe eines einzelnen Container-Objekts anstelle von einem/einer DocumentClient, DatabaseName und DocumentCollection.

Im folgenden Beispiel wird ein neues CosmosClientBuilder mit einem starken ConsistencyLevel und einer Liste der bevorzugten Speicherorte erstellt:

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

Exceptions

Im v2 SDK wurde DocumentClientException verwendet, um Fehler während der Vorgänge zu signalisieren. Im Gegensatz dazu nutzt das v3 SDK CosmosException, wodurch StatusCode, Diagnostics und andere antwortbezogene Informationen verfügbar gemacht werden. Alle kompletten Informationen werden serialisiert, wenn ToString() verwendet wird.

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

Wenn das v2 SDK Direct-only-Diagnosen über die RequestDiagnosticsString-Eigenschaft verfügbar machte, verwendet das v3 SDK Diagnostics, das in allen Antworten und Ausnahmen verfügbar ist, die umfangreicher und nicht auf den Direct-Modus beschränkt sind. Sie umfassen nicht nur die für das SDK für den Vorgang aufgewendete Zeit, sondern auch die Regionen, die der Vorgang kontaktiert hat.

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

Verbindungsrichtlinie

Einige Einstellungen ConnectionPolicy in wurden umbenannt oder ersetzt durch CosmosClientOptions:

.NET v2 SDK .NET v3 SDK
EnableEndpointDiscovery LimitToEndpoint - Der Wert ist jetzt invertiert. Wenn EnableEndpointDiscovery auf true festgelegt wurde, sollte LimitToEndpoint auf false festgelegt werden. Bevor Sie diese Einstellung verwenden, müssen Sie verstehen , wie sie sich auf den Client auswirkt.
ConnectionProtocol Entfernt. Das Protokoll ist an den Modus gebunden, entweder Gateway (HTTPS) oder Direct (TCP). Der direkte Modus mit HTTPS-Protokoll wird im V3 SDK nicht mehr unterstützt, und die Empfehlung besteht darin, das TCP-Protokoll zu verwenden.
MediaRequestTimeout Entfernt. Anlagen werden nicht mehr unterstützt.
SetCurrentLocation CosmosClientOptions.ApplicationRegion kann verwendet werden, um denselben Effekt zu erzielen.
PreferredLocations CosmosClientOptions.ApplicationPreferredRegions kann verwendet werden, um denselben Effekt zu erzielen.
UserAgentSuffix CosmosClientBuilder.ApplicationName kann verwendet werden, um denselben Effekt zu erzielen.
UseMultipleWriteLocations Entfernt. Das SDK erkennt automatisch, ob das Konto mehrere Schreibendpunkte unterstützt.

Indizierungsrichtlinie

In der Indizierungsrichtlinie ist es nicht möglich, diese Eigenschaften zu konfigurieren. Wenn sie nicht angegeben sind, weisen diese Eigenschaften jetzt immer die folgenden Werte auf:

Eigenschaftsname Neuer Wert (nicht konfigurierbar)
Kind range
dataType String und Number

Exemplarische Indizierungsrichtlinien zum Ein- und Ausschließen von Pfaden finden Sie in diesem Abschnitt. Aufgrund von Verbesserungen im Abfragemodul hat die Konfiguration dieser Eigenschaften auch bei Verwendung einer älteren SDK-Version keine Auswirkungen auf die Leistung.

Sitzungstoken

Wenn das v2 SDK das Sitzungstoken einer Antwort als ResourceResponse.SessionToken für Fälle verfügbar gemacht hat, in denen das Sitzungstoken erforderlich war, da das Sitzungstoken ein Header ist, macht das v3 SDK diesen Wert in der Headers.Session Eigenschaft einer antwort verfügbar.

Zeitstempel

Wenn das v2 SDK den Zeitstempel eines Dokuments über die Timestamp Eigenschaft verfügbar macht, da Document er nicht mehr verfügbar ist, können Benutzer die _tsSystemeigenschaft einer Eigenschaft in ihrem Modell zuordnen.

OpenAsync

Für Anwendungsfälle, in denen OpenAsync() verwendet wurde, um den v2 SDK-Client aufzuwärmen, kann CreateAndInitializeAsync sowohl zum Erstellen als auch zum Aufwärmen eines v3 SDK-Clients verwendet werden.

Verwenden der Änderungsfeed-Prozessor-APIs direkt aus dem v3 SDK

Das v3 SDK verfügt über integrierte Unterstützung für die APIs des Änderungsfeedprozessors, sodass Sie das gleiche SDK zum Erstellen Ihrer Anwendung und der Änderung von Feedprozessor-Implementierungen verwenden können. Zuvor mussten Sie eine separate Änderungsfeedprozessorbibliothek verwenden.

Weitere Informationen finden Sie unter Migrieren von der Änderungsfeedprozessorbibliothek zum Azure Cosmos DB .NET v3 SDK

Feedabfragen ändern

Das Ausführen von Änderungsfeedabfragen im v3 SDK wird als Verwendung des Pullmodells für Änderungsfeeds betrachtet. Führen Sie die folgende Tabelle aus, um die Konfiguration zu migrieren:

.NET v2 SDK .NET v3 SDK
ChangeFeedOptions.PartitionKeyRangeId FeedRange - Um Parallelität beim Lesen des Änderungsfeeds zu erreichen, können die FeedRanges verwendet werden. Es ist kein erforderlicher Parameter mehr, Sie können den Änderungsfeed für einen gesamten Container jetzt problemlos lesen.
ChangeFeedOptions.PartitionKey FeedRange.FromPartitionKey - Ein FeedRange, der den gewünschten Partitionsschlüssel darstellt, kann verwendet werden, um den Änderungsfeed für diesen Partitionsschlüsselwert zu lesen.
ChangeFeedOptions.RequestContinuation ChangeFeedStartFrom.Continuation – Der Änderungsfeed-Iterator kann jederzeit beendet und fortgesetzt werden, indem die Fortsetzung gespeichert und beim Erstellen eines neuen Iterators verwendet wird.
ChangeFeedOptions.StartTime ChangeFeedStartFrom.Time
ChangeFeedOptions.StartFromBeginning ChangeFeedStartFrom.Beginning
ChangeFeedOptions.MaxItemCount ChangeFeedRequestOptions.PageSizeHint – Der Änderungsfeed-Iterator kann jederzeit beendet und fortgesetzt werden, indem die Fortsetzung gespeichert und beim Erstellen eines neuen Iterators verwendet wird.
IDocumentQuery.HasMoreResults response.StatusCode == HttpStatusCode.NotModified - Der Änderungsfeed ist konzeptionell unendlich, sodass immer mehr Ergebnisse vorliegen könnten. Wenn eine Antwort den HttpStatusCode.NotModified Statuscode enthält, bedeutet dies, dass zurzeit keine neuen Änderungen zum Lesen vorhanden sind. Sie können dies verwenden, um die Fortsetzung anzuhalten und zu speichern oder vorübergehend in den Schlafmodus zu wechseln oder zu warten und dann erneut ReadNextAsync aufzurufen, um nach neuen Änderungen zu testen.
Behandlung von Aufteilungen Es ist nicht mehr erforderlich, dass Benutzer Aufteilungsausnahmen beim Lesen des Änderungsfeeds behandeln. Aufteilungen werden transparent behandelt, ohne dass eine Benutzerinteraktion erforderlich ist.

Verwendung der Bulk-Executor-Bibliothek direkt aus dem V3 SDK

Das v3 SDK verfügt über integrierte Unterstützung für die Massenausführerbibliothek, sodass Sie das gleiche SDK zum Erstellen Ihrer Anwendung und zum Ausführen von Massenvorgängen verwenden können. Zuvor mussten Sie eine separate Bulk Executor-Bibliothek verwenden.

Weitere Informationen finden Sie unter So migrieren Sie von der Massenausführungsbibliothek zur Massenunterstützung im Azure Cosmos DB .NET V3 SDK

Anpassen der Serialisierung

Das .NET V2 SDK ermöglicht das Festlegen von JsonSerializerSettings in RequestOptions auf operativer Ebene, die zum Deserialisieren des Ergebnisdokuments verwendet wird:

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

Das .NET SDK v3 bietet eine Serialisierungsschnittstelle zum vollständigen Anpassen des Serialisierungsmoduls oder allgemeinerer Serialisierungsoptionen als Teil der Clienterstellung.

Das Anpassen der Serialisierung auf Vorgangsebene kann über die Verwendung von Stream-APIs erreicht werden:

// .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
        }
    }
}

Codeausschnittvergleiche

Der folgende Codeausschnitt zeigt die Unterschiede bei der Erstellung von Ressourcen zwischen .NET v2 und v3 SDKs:

Datenbankvorgänge

Erstellen einer Datenbank

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

Lesen einer Datenbank nach ID

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

Löschen einer Datenbank

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

Containervorgänge

Erstellen eines Containers (Autoskalierung + Gültigkeitsdauer mit Ablauf)

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

Lesen von Containereigenschaften

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

Container löschen

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

Element- und Abfragevorgänge

Erstellen eines Elements

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

Alle Elemente in einem Container lesen

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

Abfrageelemente

Änderungen an SqlQuerySpec (QueryDefinition in v3.0 SDK)

Die SqlQuerySpec Klasse in SDK v2 wurde nun in das SDK v3 umbenannt QueryDefinition .

SqlParameterCollection und SqlParameter wurde entfernt. Parameter werden jetzt QueryDefinition mithilfe eines Generator-Modells unter Verwendung von QueryDefinition.WithParameter hinzugefügt. Benutzer können auf die Parameter zugreifen mit 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);
        }
    }
}

Löschen eines Elements

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

Feedabfrage ändern

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
        }
    }
}

Nächste Schritte