Udostępnij za pośrednictwem

Migrowanie aplikacji do używania zestawu .NET SDK platformy .NET usługi Azure Cosmos DB w wersji 3

  • Artykuł

DOTYCZY: NoSQL

Ważne

Aby dowiedzieć się więcej na temat zestawu .NET SDK platformy .NET usługi Azure Cosmos DB w wersji 3, zobacz Informacje o wersji, repozytorium GitHub platformy .NET, porady dotyczące wydajności zestawu SDK platformy .NET w wersji 3 i przewodnik rozwiązywania problemów.

W tym artykule przedstawiono niektóre zagadnienia dotyczące uaktualniania istniejącej aplikacji .NET do nowszego zestawu .NET SDK platformy .NET usługi Azure Cosmos DB w wersji 3 dla interfejsu API dla noSQL. Zestaw .NET SDK platformy .NET usługi Azure Cosmos DB w wersji 3 odpowiada przestrzeni nazw Microsoft.Azure.Azure Cosmos DB. Możesz użyć informacji podanych w tym dokumencie, jeśli migrujesz aplikację z dowolnego z następujących zestawów SDK platformy .NET usługi Azure Cosmos DB:

  • Zestaw SDK platformy .NET Framework usługi Azure Cosmos DB w wersji 2 dla interfejsu API dla noSQL
  • Zestaw .NET Core SDK usługi Azure Cosmos DB w wersji 2 dla interfejsu API dla noSQL

Instrukcje zawarte w tym artykule ułatwiają również migrowanie następujących bibliotek zewnętrznych, które są obecnie częścią zestawu .NET SDK platformy .NET usługi Azure Cosmos DB w wersji 3 dla interfejsu API dla noSQL:

  • Biblioteka procesora zestawienia zmian platformy .NET 2.0
  • Biblioteka funkcji wykonawczej operacji zbiorczych platformy .NET w wersji 1.1 lub nowszej

Co nowego w zestawie .NET V3 SDK

Zestaw SDK w wersji 3 zawiera wiele ulepszeń użyteczności i wydajności, w tym:

  • Intuicyjne nazewnictwo modelu programowania
  • .NET Standard 2.0 **
  • Zwiększona wydajność dzięki obsłudze interfejsu API strumienia
  • Płynna hierarchia, która zastępuje potrzebę fabryki identyfikatorów URI
  • Wbudowana obsługa biblioteki procesora zestawienia zmian
  • Wbudowana obsługa operacji zbiorczych
  • Pozorowane interfejsy API ułatwiające testowanie jednostkowe
  • Obsługa partii transakcyjnej i platformy Blazor
  • Podłączane serializatory
  • Skalowanie kontenerów bez partycjonowania i skalowania automatycznego

** Zestaw SDK jest przeznaczony dla platformy .NET Standard 2.0, która łączy istniejące zestawy .NET Framework i .NET Core SDK usługi Azure Cosmos DB w jeden zestaw .NET SDK. Zestaw .NET SDK można używać na dowolnej platformie, która implementuje platformę .NET Standard 2.0, w tym programy .NET Framework 4.6.1+ i .NET Core 2.0+.

Większość sieci, logiki ponawiania i niższych poziomów zestawu SDK pozostaje w dużej mierze niezmieniona.

Zestaw .NET SDK platformy .NET usługi Azure Cosmos DB w wersji 3 jest teraz typu open source. Z zadowoleniem przyjmujemy wszelkie żądania ściągnięcia i będziemy rejestrować problemy i śledzić opinie w witrynie GitHub. Będziemy pracować nad podjęciem wszelkich funkcji, które poprawią jakość obsługi klienta.

Dlaczego warto przeprowadzić migrację do zestawu SDK platformy .NET w wersji 3

Oprócz wielu ulepszeń użyteczności i wydajności nowe inwestycje w funkcje wprowadzone w najnowszym zestawie SDK nie zostaną przywrócone do starszych wersji. Zestaw SDK w wersji 2 jest obecnie w trybie konserwacji. Aby uzyskać najlepsze środowisko programistyczne, zalecamy zawsze rozpoczynanie pracy z najnowszą obsługiwaną wersją zestawu SDK.

Główne zmiany nazw z zestawu SDK w wersji 2 na zestaw SDK w wersji 3

W zestawie SDK platformy .NET 3.0 zastosowano następujące zmiany nazw, aby dostosować je do konwencji nazewnictwa interfejsu API dla interfejsu API dla noSQL:

  • DocumentClient zmieniono nazwę na CosmosClient
  • Collection zmieniono nazwę na Container
  • Document zmieniono nazwę na Item

Nazwy wszystkich obiektów zasobów są zmieniane z dodatkowymi właściwościami, które zawierają nazwę zasobu w celu zapewnienia przejrzystości.

Poniżej przedstawiono niektóre zmiany nazwy głównej klasy:

Zestaw SDK platformy .NET w wersji 2 Zestaw SDK platformy .NET w wersji 3
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

Klasy zastąpione w zestawie SDK platformy .NET w wersji 3

W zestawie SDK 3.0 zastąpiono następujące klasy:

  • Microsoft.Azure.Documents.UriFactory

Klasa Microsoft.Azure.Documents.UriFactory została zastąpiona przez płynny projekt.

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

Ponieważ zestaw SDK platformy .NET w wersji 3 umożliwia użytkownikom konfigurowanie niestandardowego aparatu serializacji, nie ma bezpośredniego zastąpienia typu Document . W przypadku korzystania z pliku Newtonsoft.Json (domyślny aparat serializacji) JObject można użyć do osiągnięcia tej samej funkcjonalności. W przypadku korzystania z innego aparatu serializacji można użyć podstawowego typu dokumentu json (na przykład JsonDocument dla pliku System.Text.Json). Zaleceniem jest użycie typu języka C#, który odzwierciedla schemat elementów zamiast polegać na typach ogólnych.

  • Microsoft.Azure.Documents.Resource

Nie ma bezpośredniego zastąpienia dla Resourceelementu , w przypadkach, w których był używany dla dokumentów, postępuj zgodnie ze wskazówkami dotyczącymi programu Document.

  • Microsoft.Azure.Documents.AccessCondition

IfNoneMatch lub IfMatch są teraz dostępne Microsoft.Azure.Cosmos.ItemRequestOptions bezpośrednio.

Zmiany generowania identyfikatora elementu

Identyfikator elementu nie jest już wypełniany automatycznie w zestawie SDK platformy .NET w wersji 3. W związku z tym identyfikator elementu musi zawierać wygenerowany identyfikator. Wyświetl następujący przykład:

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

Zmieniono domyślne zachowanie trybu połączenia

Zestaw SDK w wersji 3 jest teraz domyślnie domyślnie w trybach połączenia Direct + TCP w porównaniu z poprzednim zestawem SDK w wersji 2, który domyślnie jest domyślnie trybami bramy i połączeń HTTPS. Ta zmiana zapewnia zwiększoną wydajność i skalowalność.

Zmiany w narzędziu FeedOptions (QueryRequestOptions w zestawie SDK w wersji 3.0)

Klasa FeedOptions w zestawie SDK w wersji 2 została zmieniona na QueryRequestOptions w zestawie SDK w wersji 3 i w klasie, kilka właściwości miało zmiany w nazwie i/lub wartości domyślnej lub zostały całkowicie usunięte.

Zestaw SDK platformy .NET w wersji 2 Zestaw SDK platformy .NET w wersji 3
FeedOptions.MaxDegreeOfParallelism QueryRequestOptions.MaxConcurrency — Wartość domyślna i skojarzone zachowanie pozostają takie same, operacje uruchamiane po stronie klienta podczas równoległego wykonywania zapytań będą wykonywane szeregowo bez równoległości.
FeedOptions.PartitionKey QueryRequestOptions.PartitionKey — Zachowanie zachowywane.
FeedOptions.EnableCrossPartitionQuery Usuwane. Domyślne zachowanie w zestawie SDK 3.0 polega na tym, że zapytania obejmujące wiele partycji będą wykonywane bez konieczności włączania właściwości.
FeedOptions.PopulateQueryMetrics Usuwane. Ta funkcja jest teraz domyślnie włączona i jest częścią diagnostyki.
FeedOptions.RequestContinuation Usuwane. Teraz jest ona promowana do samych metod zapytań.
FeedOptions.JsonSerializerSettings Usuwane. Zobacz, jak dostosować serializacji , aby uzyskać dodatkowe informacje.
FeedOptions.PartitionKeyRangeId Usuwane. Ten sam wynik można uzyskać przy użyciu elementu FeedRange jako danych wejściowych do metody zapytania.
FeedOptions.DisableRUPerMinuteUsage Usuwane.

Konstruowanie klienta

Zestaw .NET SDK w wersji 3 zapewnia płynną CosmosClientBuilder klasę, która zastępuje potrzebę fabryki identyfikatorów URI zestawu SDK w wersji 2.

Płynny projekt tworzy adresy URL wewnętrznie i umożliwia przekazywanie pojedynczego Container DocumentClientobiektu zamiast , DatabaseNamei DocumentCollection.

W poniższym przykładzie zostanie utworzona nowa CosmosClientBuilder z silną wartością ConsistencyLevel i listą preferowanych lokalizacji:

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

Wyjątki

W przypadku, gdy zestaw SDK w wersji 2 używany DocumentClientException do sygnalizowania błędów podczas operacji, zestaw SDK w wersji 3 używa CosmosExceptionelementu , który uwidacznia StatusCodeDiagnosticsinformacje związane z odpowiedziami i inne informacje dotyczące odpowiedzi. Wszystkie pełne informacje są serializowane, gdy ToString() są używane:

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

Diagnostyka

Jeśli zestaw SDK w wersji 2 ma dostępną diagnostykę tylko bezpośrednio za pośrednictwem RequestDiagnosticsString właściwości, zestaw SDK w wersji 3 jest Diagnostics dostępny we wszystkich odpowiedziach i wyjątkach, które są bogatsze i nie są ograniczone do trybu bezpośredniego. Obejmują one nie tylko czas spędzony na zestawie SDK dla operacji, ale także regiony, z którymi skontaktowała się operacja:

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

Niektóre ustawienia w programie ConnectionPolicy zostały zmienione lub zastąpione przez CosmosClientOptions:

Zestaw SDK platformy .NET w wersji 2 Zestaw SDK platformy .NET w wersji 3
EnableEndpointDiscovery LimitToEndpoint - Wartość jest teraz odwrócona, jeśli EnableEndpointDiscovery ustawiono wartość true, LimitToEndpoint powinna być ustawiona na falsewartość . Przed użyciem tego ustawienia należy zrozumieć , jak ma to wpływ na klienta.
ConnectionProtocol Usuwane. Protokół jest powiązany z trybem — bramą (HTTPS) lub bezpośrednim (TCP). Tryb bezpośredni z protokołem HTTPS nie jest już obsługiwany w zestawie SDK w wersji 3, a zaleceniem jest użycie protokołu TCP.
MediaRequestTimeout Usuwane. Załączniki nie są już obsługiwane.
SetCurrentLocation CosmosClientOptions.ApplicationRegion można użyć do osiągnięcia tego samego efektu.
PreferredLocations CosmosClientOptions.ApplicationPreferredRegions można użyć do osiągnięcia tego samego efektu.
UserAgentSuffix CosmosClientBuilder.ApplicationName można użyć do osiągnięcia tego samego efektu.
UseMultipleWriteLocations Usuwane. Zestaw SDK automatycznie wykrywa, czy konto obsługuje wiele punktów końcowych zapisu.

Zasady indeksowania

W zasadach indeksowania nie można skonfigurować tych właściwości. Gdy te właściwości nie zostaną określone, zawsze będą miały następujące wartości:

Nazwa właściwości Nowa wartość (niemożliwa do skonfigurowania)
Kind range
dataType String i Number

Zobacz tę sekcję, aby zapoznać się z przykładami zasad indeksowania, aby dołączać i wykluczać ścieżki. Ze względu na ulepszenia aparatu zapytań konfigurowanie tych właściwości, nawet w przypadku korzystania ze starszej wersji zestawu SDK, nie ma wpływu na wydajność.

Token sesji

Jeśli zestaw SDK w wersji 2 uwidocznił token sesji odpowiedzi, tak ResourceResponse.SessionToken jak w przypadku, gdy przechwytywanie tokenu sesji było wymagane, ponieważ token sesji jest nagłówkiem, zestaw SDK w wersji 3 uwidacznia wartość we Headers.Session właściwości dowolnej odpowiedzi.

Sygnatura czasowa

Jeśli zestaw SDK w wersji 2 uwidocznił sygnaturę czasową dokumentu za pośrednictwem Timestamp właściwości, ponieważ Document nie jest już dostępny, użytkownicy mogą mapować _ts właściwość systemową na właściwość w modelu.

OpenAsync

W przypadku przypadków użycia, w których OpenAsync() był używany do rozgrzewania klienta zestawu SDK w wersji 2, CreateAndInitializeAsync można użyć zarówno do tworzenia i rozgrzewania klienta zestawu SDK w wersji 3.

Korzystanie z interfejsów API procesora zestawienia zmian bezpośrednio z zestawu SDK w wersji 3

Zestaw SDK w wersji 3 ma wbudowaną obsługę interfejsów API procesora zestawienia zmian, umożliwiając korzystanie z tego samego zestawu SDK do kompilowania aplikacji i implementacji procesora zestawienia zmian. Wcześniej trzeba było użyć oddzielnej biblioteki procesora zestawienia zmian.

Aby uzyskać więcej informacji, zobacz jak przeprowadzić migrację z biblioteki procesora zestawienia zmian do zestawu SDK platformy .NET usługi Azure Cosmos DB w wersji 3

Zapytania zestawienia zmian

Wykonywanie zapytań zestawienia zmian w zestawie SDK w wersji 3 jest uważane za użycie modelu ściągania zestawienia zmian. Postępuj zgodnie z tą tabelą, aby przeprowadzić migrację konfiguracji:

Zestaw SDK platformy .NET w wersji 2 Zestaw SDK platformy .NET w wersji 3
ChangeFeedOptions.PartitionKeyRangeId FeedRange- W celu osiągnięcia równoległości odczytywanie zestawienia zmian FeedRanges można użyć. Nie jest to już wymagany parametr. Teraz możesz łatwo odczytać zestawienie zmian dla całego kontenera .
ChangeFeedOptions.PartitionKey FeedRange.FromPartitionKey — Element FeedRange reprezentujący żądany klucz partycji może służyć do odczytywania zestawienia zmian dla tej wartości klucza partycji.
ChangeFeedOptions.RequestContinuation ChangeFeedStartFrom.Continuation - Iterator zestawienia zmian można zatrzymać i wznowić w dowolnym momencie, zapisując kontynuację i używając jej podczas tworzenia nowego iteratora.
ChangeFeedOptions.StartTime ChangeFeedStartFrom.Time
ChangeFeedOptions.StartFromBeginning ChangeFeedStartFrom.Beginning
ChangeFeedOptions.MaxItemCount ChangeFeedRequestOptions.PageSizeHint - Iterator zestawienia zmian można zatrzymać i wznowić w dowolnym momencie, zapisując kontynuację i używając jej podczas tworzenia nowego iteratora.
IDocumentQuery.HasMoreResults response.StatusCode == HttpStatusCode.NotModified - Źródło zmian jest koncepcyjnie nieskończone, więc zawsze może być więcej wyników. Gdy odpowiedź zawiera HttpStatusCode.NotModified kod stanu, oznacza to, że w tej chwili nie ma żadnych nowych zmian do odczytania. Można jej użyć do zatrzymania i zapisania kontynuacji lub tymczasowego uśpienia lub oczekiwania, a następnie wywołać ReadNextAsync ponownie, aby przetestować nowe zmiany.
Obsługa podziału Użytkownicy nie muszą już obsługiwać wyjątków podziału podczas odczytywania zestawienia zmian, podziały będą obsługiwane w sposób niewidoczny bez konieczności interakcji z użytkownikiem.

Używanie biblioteki funkcji wykonawczej operacji zbiorczych bezpośrednio z zestawu SDK w wersji 3

Zestaw SDK w wersji 3 ma wbudowaną obsługę biblioteki funkcji wykonawczej operacji zbiorczych, umożliwiając korzystanie z tego samego zestawu SDK do kompilowania aplikacji i wykonywania operacji zbiorczych. Wcześniej było wymagane użycie oddzielnej biblioteki funkcji wykonawczej operacji zbiorczych.

Aby uzyskać więcej informacji, zobacz jak przeprowadzić migrację z biblioteki funkcji wykonawczej zbiorczej do zbiorczej obsługi zestawu SDK platformy .NET platformy .NET w usłudze Azure Cosmos DB w wersji 3

Dostosowywanie serializacji

Zestaw SDK platformy .NET w wersji 2 umożliwia ustawienie ustawień JsonSerializerSettings w obszarze RequestOptions na poziomie operacyjnym używanym do deserializacji dokumentu wynikowego:

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

Zestaw .NET SDK w wersji 3 udostępnia interfejs serializatora w celu pełnego dostosowania aparatu serializacji lub większej liczby ogólnych opcji serializacji w ramach konstrukcji klienta.

Dostosowanie serializacji na poziomie operacji można osiągnąć za pomocą interfejsów API usługi 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
        }
    }
}

Porównania fragmentów kodu

Poniższy fragment kodu przedstawia różnice w sposobie tworzenia zasobów między zestawami SDK platformy .NET w wersji 2 i 3:

Operacje bazy danych

Utwórz bazę danych 

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

Odczytywanie bazy danych na podstawie identyfikatora

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

Usuwanie bazy danych

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

Operacje kontenera

Tworzenie kontenera (autoskalowanie i czas wygaśnięcia z wygaśnięciem)

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

Odczytywanie właściwości kontenera

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

Usuwanie kontenera

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

Operacje elementów i zapytań

Tworzenie elementu

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

Odczytywanie wszystkich elementów w kontenerze

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

Elementy kwerend

Zmiany w obiekcie SqlQuerySpec (QueryDefinition w wersji 3.0 zestawu SDK)

Klasa SqlQuerySpec w zestawie SDK w wersji 2 została zmieniona na QueryDefinition w zestawie SDK w wersji 3.

SqlParameterCollection i SqlParameter został usunięty. Parametry są teraz dodawane do QueryDefinition elementu z modelem konstruktora przy użyciu polecenia QueryDefinition.WithParameter. Użytkownicy mogą uzyskiwać dostęp do parametrów za pomocą polecenia 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);
        }
    }
}

Usuwanie elementu

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

Zapytanie zestawienia zmian

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

Następne kroki