Share via

Samouczek: tworzenie aplikacji konsolowej platformy .NET za pomocą usługi Azure Cosmos DB for NoSQL

  • Artykuł

DOTYCZY: NoSQL

Zestaw Azure SDK dla platformy .NET umożliwia dodawanie danych do interfejsu API dla kontenera NoSQL asynchronicznie lub wsadu transakcyjnego. W tym samouczku przedstawiono proces tworzenia nowej aplikacji konsolowej platformy .NET, która dodaje wiele elementów do kontenera.

Z tego samouczka dowiesz się, jak wykonywać następujące czynności:

  • Tworzenie bazy danych przy użyciu interfejsu API dla noSQL
  • Tworzenie aplikacji konsolowej platformy .NET i dodawanie zestawu Azure SDK dla platformy .NET
  • Dodawanie poszczególnych elementów do interfejsu API dla kontenera NoSQL
  • Wydajne pobieranie elementów z interfejsu API dla kontenera NoSQL
  • Tworzenie transakcji ze zmianami wsadowymi dla kontenera api for NoSQL

Wymagania wstępne

Tworzenie interfejsu API dla zasobów NoSQL

Najpierw utwórz pustą bazę danych w istniejącym interfejsie API dla konta NoSQL. Później utworzysz kontener przy użyciu zestawu Azure SDK dla platformy .NET.

  1. Przejdź do istniejącego konta interfejsu API dla noSQL w witrynie Azure Portal.

  2. W menu zasobów wybierz pozycję Klucze.

    Screenshot of an API for NoSQL account page. The Keys option is highlighted in the resource menu.

  3. Na stronie Klucze sprawdź i zarejestruj wartość pól Identyfikator URI i KLUCZ PODSTAWOWY. Te wartości będą używane w całym samouczku.

    Screenshot of the Keys page with the URI and Primary Key fields highlighted.

  4. W menu zasobów wybierz pozycję Eksplorator danych.

    Screenshot of the Data Explorer option highlighted in the resource menu.

  5. Na stronie Eksplorator danych wybierz opcję Nowa baza danych na pasku poleceń.

    Screenshot of the New Database option in the Data Explorer command bar.

  6. W oknie dialogowym Nowa baza danych utwórz nowy kontener z następującymi ustawieniami:

    Wartość
    Identyfikator bazy danych cosmicworks
    Typ przepływności bazy danych Ręczne
    Ilość przepływności bazy danych 400

    Screenshot of the New Database dialog in the Data Explorer with various values in each field.

  7. Wybierz przycisk OK , aby utworzyć bazę danych.

Tworzenie aplikacji konsolowej platformy .NET

Teraz utworzysz nową aplikację konsolową platformy .NET i zaimportujesz zestaw Azure SDK dla platformy .NET przy użyciu biblioteki z narzędzia Microsoft.Azure.Cosmos NuGet.

  1. Otwórz terminal w pustym katalogu.

  2. Tworzenie nowej aplikacji konsolowej przy użyciu wbudowanego console szablonu

    dotnet new console --langVersion preview

  3. Dodaj wersję Microsoft.Azure.Cosmos 3.31.1-preview pakietu z pakietu NuGet.

    dotnet add package Microsoft.Azure.Cosmos --version 3.31.1-preview

  4. Ponadto dodaj wersję System.CommandLine wstępną pakietu z pakietu NuGet.

    dotnet add package System.CommandLine --prerelease

  5. Ponadto dodaj Humanizer pakiet z narzędzia NuGet.

    dotnet add package Humanizer

  6. Skompiluj projekt aplikacji konsolowej.

    dotnet build

  7. Otwórz program Visual Studio Code przy użyciu bieżącego folderu projektu jako obszaru roboczego.

    Napiwek

    Możesz uruchomić polecenie code . w terminalu, aby otworzyć program Visual Studio Code i automatycznie otworzyć katalog roboczy jako bieżący obszar roboczy.

  8. Przejdź do pliku Program.cs i otwórz go. Usuń cały istniejący kod w pliku.

  9. Dodaj ten kod do pliku, aby użyć biblioteki System.CommandLine , aby przeanalizować wiersz polecenia dla dwóch ciągów przekazywanych za pośrednictwem --first opcji i --last .

    using System.CommandLine;

var command = new RootCommand();

var nameOption = new Option<string>("--name") { IsRequired = true };
var emailOption = new Option<string>("--email");
var stateOption = new Option<string>("--state") { IsRequired = true };
var countryOption = new Option<string>("--country") { IsRequired = true };

command.AddOption(nameOption);
command.AddOption(emailOption);
command.AddOption(stateOption);
command.AddOption(countryOption);

command.SetHandler(
    handle: CosmosHandler.ManageCustomerAsync, 
    nameOption, 
    emailOption,
    stateOption,
    countryOption
);

await command.InvokeAsync(args);

    Uwaga

    W tym samouczku nie jest to całkowicie ważne, aby zrozumieć, jak działa analizator wiersza polecenia. Analizator ma cztery opcje, które można określić, gdy aplikacja jest uruchomiona. Trzy z tych opcji są wymagane, ponieważ będą używane do konstruowania pól identyfikatora i klucza partycji.

  10. W tym momencie projekt nie zostanie skompilowane, ponieważ nie zdefiniowano jeszcze metody statycznej CosmosHandler.ManageCustomerAsync .

  11. Zapisz plik Program.cs.

Dodawanie elementów do kontenera przy użyciu zestawu SDK

Następnie użyjesz poszczególnych operacji, aby dodać elementy do kontenera api for NoSQL. W tej sekcji zdefiniujesz metodę CosmosHandler.ManageCustomerAsync .

  1. Utwórz nowy plik CosmosHandler.cs .

  2. W pliku CosmosHandler.cs dodaj nową dyrektywę using dla Humanizer przestrzeni nazw i Microsoft.Azure.Cosmos .

    using Humanizer;
using Microsoft.Azure.Cosmos;

  3. Utwórz nową klasę statyczną o nazwie CosmosHandler.

    public static class CosmosHandler
{ }

  4. Aby sprawdzić, czy ta aplikacja będzie działać, utwórz krótką implementację metody statycznej ManageCustomerAsync , aby wydrukować dane wejściowe wiersza polecenia.

    public static async Task ManageCustomerAsync(string name, string email, string state, string country)
{
    await Console.Out.WriteLineAsync($"Hello {name} of {state}, {country}!");
}

  5. Zapisz plik CosmosHandler.cs.

  6. Ponownie w terminalu uruchom aplikację.

    dotnet run -- --name 'Mica Pereira' --state 'Washington' --country 'United States'

  7. Dane wyjściowe polecenia powinny być zabawnym powitaniem.

    Hello Mica Pereira of Washington, United States!

  8. Wróć do pliku CosmosHandler.cs .

  9. W statycznej klasie CosmosHandler dodaj nowy private static readonly element członkowski typu CosmosClient o nazwie _client.

    private static readonly CosmosClient _client;

  10. Utwórz nowy konstruktor statyczny dla CosmosHandler klasy .

    static CosmosHandler()
{ }

  11. W konstruktorze utwórz nowe wystąpienie CosmosClient klasy przekazującej dwa parametry ciągu przy użyciu wartości URI i PRIMARY KEY , które zostały wcześniej zarejestrowane w laboratorium. Zapisz to nowe wystąpienie w elemencie _client członkowskim.

    static CosmosHandler()
{
    _client = new CosmosClient(
        accountEndpoint: "<uri>", 
        authKeyOrResourceToken: "<primary-key>"
    );
}

  12. Z powrotem w statycznej klasie CosmosHandler utwórz nową metodę asynchroniczną o nazwie GetContainerAsync , która zwraca Containerwartość .

    private static async Task<Container> GetContainer()
{ }

  13. Aby wykonać następne kroki, dodaj ten kod w metodzie GetContainerAsync .

    1. cosmicworks Pobierz bazę danych i zapisz ją w zmiennej o nazwie database.

      Database database = _client.GetDatabase("cosmicworks");

    2. Utwórz nowy rodzaj List<>string wartości na liście hierarchicznych ścieżek klucza partycji i zapisz je w zmiennej o nazwie keyPaths.

      List<string> keyPaths = new()
{
    "/address/country",
    "/address/state"
};

    3. Utwórz nową ContainerProperties zmienną o nazwie kontenera (customers) i liście ścieżek klucza partycji.

      ContainerProperties properties = new(
    id: "customers",
    partitionKeyPaths: keyPaths
);

    4. CreateContainerIfNotExistsAsync Użyj metody , aby podać właściwości kontenera i pobrać kontener. Ta metoda będzie asynchronicznie utworzyć kontener, jeśli jeszcze nie istnieje w bazie danych. Zwróć wynik jako dane wyjściowe GetContainerAsync metody .

      return await database.CreateContainerIfNotExistsAsync(
    containerProperties: properties
);

  14. Usuń cały kod w metodzie ManageCustomerAsync .

  15. Aby wykonać następne kroki, dodaj ten kod w metodzie ManageCustomerAsync .

    1. Asynchronicznie wywołaj metodę GetContainerAsync i zapisz wynik w zmiennej o nazwie container.

      Container container = await GetContainerAsync();

    2. Utwórz nową zmienną o nazwie id , która używa Kebaberize metody z Humanizer do przekształcenia parametru name metody.

      string id = name.Kebaberize();

      Uwaga

      Metoda Kebaberize zastąpi wszystkie spacje łącznikami i zweryfuje tekst do małych liter.

    3. Utwórz nowy anonimowy element wpisany przy użyciu nameparametrów , statei metody i country zmiennej id . Zapisz element jako zmienną o nazwie customer.

      var customer = new {
    id = id,
    name = name,
    address = new {
        state = state,
        country = country
    }
};

    4. Użyj metody asynchronicznej CreateItemAsync kontenera, aby utworzyć nowy element w kontenerze i przypisać metadane odpowiedzi HTTP do zmiennej o nazwie response.

      var response = await container.CreateItemAsync(customer);

    5. Zapisz wartości właściwości i RequestCharge zmiennej responseStatusCode w konsoli programu . Zapisz również wartość zmiennej id .

      Console.WriteLine($"[{response.StatusCode}]\t{id}\t{response.RequestCharge} RUs");

  16. Zapisz plik CosmosHandler.cs.

  17. Wróć do terminalu, ponownie uruchom aplikację.

    dotnet run -- --name 'Mica Pereira' --state 'Washington' --country 'United States'

  18. Dane wyjściowe polecenia powinny zawierać stan i żądanie opłaty za operację.

    [Created]       mica-pereira    7.05 RUs

    Uwaga

    Opłata za żądanie może się różnić.

  19. Uruchom aplikację jeszcze raz.

    dotnet run -- --name 'Mica Pereira' --state 'Washington' --country 'United States'

  20. Tym razem program powinien ulec awarii. Jeśli przewiniesz komunikat o błędzie, zobaczysz, że wystąpiła awaria z powodu konfliktu w unikatowym identyfikatorze elementów.

    Unhandled exception: Microsoft.Azure.Cosmos.CosmosException : Response status code does not indicate success: Conflict (409);Reason: (
    Errors : [
      "Resource with specified id or name already exists."
    ]
);

Pobieranie elementu przy użyciu zestawu SDK

Po utworzeniu pierwszego elementu w kontenerze możesz użyć tego samego zestawu SDK do pobrania elementu. W tym miejscu wykonasz zapytanie i wskażesz element, aby porównać różnicę użycia jednostek żądań (RU).

  1. Wróć do lub otwórz plik CosmosHandler.cs .

  2. Usuń wszystkie wiersze kodu z metody z ManageCustomerAsync wyjątkiem dwóch pierwszych wierszy.

    public static async Task ManageCustomerAsync(string name, string email, string state, string country)
{
    Container container = await GetContainerAsync();

    string id = name.Kebaberize();
}

  3. Aby wykonać następne kroki, dodaj ten kod w metodzie ManageCustomerAsync .

    1. Użyj metody asynchronicznej CreateItemAsync kontenera, aby utworzyć nowy element w kontenerze i przypisać metadane odpowiedzi HTTP do zmiennej o nazwie response.

      var response = await container.CreateItemAsync(customer);

    2. Utwórz nowy ciąg o nazwie sql z zapytaniem SQL, aby pobrać elementy, w których filtr (@id) jest zgodny.

      string sql = """
SELECT
    *
FROM customers c
WHERE c.id = @id
""";

    3. Utwórz nową QueryDefinition zmienną o nazwie query przekazującą sql ciąg jako jedyny parametr zapytania. Ponadto użyj metody płynu WithParameter , aby zastosować wartość zmiennej id do parametru @id .

      var query = new QueryDefinition(
    query: sql
)
    .WithParameter("@id", id);

    4. GetItemQueryIterator<> Użyj metody ogólnej i zmiennejquery, aby utworzyć iterator, który pobiera dane z usługi Azure Cosmos DB. Zapisz iterator w zmiennej o nazwie feed. Zawijaj to całe wyrażenie w instrukcji using, aby później usunąć iterator.

      using var feed = container.GetItemQueryIterator<dynamic>(
    queryDefinition: query
);

    5. Asynchronicznie wywołaj metodę ReadNextAsync zmiennej feed i zapisz wynik w zmiennej o nazwie response.

      var response = await feed.ReadNextAsync();

    6. Zapisz wartości właściwości i RequestCharge zmiennej responseStatusCode w konsoli programu . Zapisz również wartość zmiennej id .

      Console.WriteLine($"[{response.StatusCode}]\t{id}\t{response.RequestCharge} RUs");

  4. Zapisz plik CosmosHandler.cs.

  5. Po powrocie do terminalu uruchom aplikację, aby odczytać pojedynczy element przy użyciu zapytania SQL.

    dotnet run -- --name 'Mica Pereira'

  6. Dane wyjściowe polecenia powinny wskazywać, że zapytanie wymaga wielu jednostek RU.

    [OK]    mica-pereira    2.82 RUs

  7. Wróć do pliku CosmosHandler.cs , usuń wszystkie wiersze kodu z ManageCustomerAsync metody ponownie z wyjątkiem pierwszych dwóch wierszy.

    public static async Task ManageCustomerAsync(string name, string email, string state, string country)
{
    Container container = await GetContainerAsync();

    string id = name.Kebaberize();
}

  8. Aby wykonać następne kroki, dodaj ten kod w metodzie ManageCustomerAsync .

    1. Utwórz nowe wystąpienie klasy PartitionKeyBuilder , dodając state parametry i country jako wartość klucza partycji wieloczęściowej.

      var partitionKey = new PartitionKeyBuilder()
    .Add(country)
    .Add(state)
    .Build();

    2. Użyj metody kontenera ReadItemAsync<> , aby wskazać odczyt elementu z kontenera przy użyciu id zmiennych i partitionKey . Zapisz wynik w zmiennej o nazwie response.

      var response = await container.ReadItemAsync<dynamic>(
    id: id, 
    partitionKey: partitionKey
);

    3. Zapisz wartości właściwości i RequestCharge zmiennej responseStatusCode w konsoli programu . Zapisz również wartość zmiennej id .

      Console.WriteLine($"[{response.StatusCode}]\t{id}\t{response.RequestCharge} RU");

  9. Zapisz ponownie plik CosmosHandler.cs.

  10. Po powrocie do terminalu uruchom aplikację jeszcze raz, aby wskazać odczyt pojedynczego elementu.

    dotnet run -- --name 'Mica Pereira' --state 'Washington' --country 'United States'

  11. Dane wyjściowe polecenia powinny wskazywać, że zapytanie wymaga pojedynczej jednostki RU.

    [OK]    mica-pereira    1 RUs

Tworzenie transakcji przy użyciu zestawu SDK

Na koniec przejmiesz utworzony element, odczytujesz ten element i utworzysz inny powiązany element w ramach jednej transakcji przy użyciu zestawu Azure SDK dla platformy .NET.

  1. Wróć do lub otwórz plik CosmosHandler.cs .

  2. Usuń te wiersze kodu z ManageCustomerAsync metody .

    var response = await container.ReadItemAsync<dynamic>(
    id: id, 
    partitionKey: partitionKey
);

Console.WriteLine($"[{response.StatusCode}]\t{id}\t{response.RequestCharge} RUs");

  3. Aby wykonać następne kroki, dodaj ten nowy kod w metodzie ManageCustomerAsync .

    1. Utwórz nowy anonimowy element wpisany przy użyciu nameparametrów , statei metody i country zmiennej id . Zapisz element jako zmienną o nazwie customerCart. Ten element będzie reprezentować koszyk zakupów w czasie rzeczywistym dla klienta, który jest obecnie pusty.

      var customerCart = new {
    id = $"{Guid.NewGuid()}",
    customerId = id,
    items = new string[] {},
    address = new {
        state = state,
        country = country
    }
};

    2. Utwórz kolejny nowy element typu anonimowego nameprzy użyciu parametrów metody , statei country zmiennej id . Zapisz element jako zmienną o nazwie customerCart. Ten element będzie reprezentować informacje wysyłkowe i kontaktowe klienta.

      var customerContactInfo = new {
    id = $"{id}-contact",
    customerId = id,
    email = email,
    location = $"{state}, {country}",
    address = new {
        state = state,
        country = country
    }
};

    3. Utwórz nową partię przy użyciu metody kontenera CreateTransactionalBatch przekazującej zmienną partitionKey . Zapisz partię w zmiennej o nazwie batch. Użyj płynnych metod, aby wykonać następujące akcje:

      Metoda Parametr
      ReadItem id zmienna ciągu
      CreateItem customerCart zmienna typu anonimowego
      CreateItem customerContactInfo zmienna typu anonimowego 
      var batch = container.CreateTransactionalBatch(partitionKey)
    .ReadItem(id)
    .CreateItem(customerCart)
    .CreateItem(customerContactInfo);

    4. Użyj metody wsadowej ExecuteAsync , aby rozpocząć transakcję. Zapisz wynik w zmiennej o nazwie response.

      using var response = await batch.ExecuteAsync();

    5. Zapisz wartości właściwości i RequestCharge zmiennej responseStatusCode w konsoli programu . Zapisz również wartość zmiennej id .

      Console.WriteLine($"[{response.StatusCode}]\t{response.RequestCharge} RUs");

  4. Zapisz ponownie plik CosmosHandler.cs.

  5. Po powrocie do terminalu uruchom aplikację jeszcze raz, aby wskazać odczyt pojedynczego elementu.

    dotnet run -- --name 'Mica Pereira' --state 'Washington' --country 'United States'

  6. Dane wyjściowe polecenia powinny zawierać jednostki żądania używane dla całej transakcji.

    [OK]    16.05 RUs

    Uwaga

    Opłata za żądanie może się różnić.

Weryfikowanie końcowych danych w Eksploratorze danych

Aby podsumować kwestie, użyjesz Eksploratora danych w witrynie Azure Portal, aby wyświetlić dane i kontener utworzony w tym samouczku.

  1. Przejdź do istniejącego konta interfejsu API dla noSQL w witrynie Azure Portal.

  2. W menu zasobów wybierz pozycję Eksplorator danych.

    Screenshot of the Data Explorer option highlighted in the resource menu.

  3. Na stronie Eksplorator danych rozwiń cosmicworks bazę danych, a następnie wybierz customers kontener.

    Screenshot of the selected container node within the database node.

  4. Na pasku poleceń wybierz pozycję Nowe zapytanie SQL.

    Screenshot of the New SQL Query option in the Data Explorer command bar.

  5. W edytorze zapytań obserwuj ten ciąg zapytania SQL.

    SELECT * FROM c

  6. Wybierz pozycję Wykonaj zapytanie , aby uruchomić zapytanie i obserwować wyniki.

    Screenshot of the Execute Query option in the Data Explorer command bar.

  7. Wyniki powinny zawierać tablicę JSON z trzema elementami utworzonymi w tym samouczku. Zwróć uwagę, że wszystkie elementy mają tę samą hierarchiczną wartość klucza partycji, ale unikatowe pola identyfikatora. Przykładowe dane wyjściowe są obcięte w celu zwięzłości.

    [
  {
    "id": "mica-pereira",
    "name": "Mica Pereira",
    "address": {
      "state": "Washington",
      "country": "United States"
    },
    ...
  },
  {
    "id": "33d03318-6302-4559-b5c0-f3cc643b2f38",
    "customerId": "mica-pereira",
    "items": [],
    "address": {
      "state": "Washington",
      "country": "United States"
    },
    ...
  },
  {
    "id": "mica-pereira-contact",
    "customerId": "mica-pereira",
    "email": null,
    "location": "Washington, United States",
    "address": {
      "state": "Washington",
      "country": "United States"
    },
    ...
  }
]

Czyszczenie zasobów

Gdy baza danych używana w tym samouczku nie będzie już potrzebna, usuń bazę danych. W tym celu przejdź do strony konta, wybierz pozycję Eksplorator danych, wybierz cosmicworks bazę danych, a następnie wybierz pozycję Usuń.

Następne kroki

Po utworzeniu pierwszej aplikacji konsolowej platformy .NET przy użyciu usługi Azure Cosmos DB spróbuj wykonać następny samouczek, w którym zaktualizujesz istniejącą aplikację internetową, aby używać danych usługi Azure Cosmos DB.

Samouczek: tworzenie aplikacji internetowej ASP.NET za pomocą usługi Azure Cosmos DB for NoSQL