Zelfstudie: Een .NET-consoletoepassing ontwikkelen met Azure Cosmos DB voor NoSQL

Artikel
10/04/2024

VAN TOEPASSING OP: NoSQL

.NET

Met de Azure SDK voor .NET kunt u gegevens toevoegen aan een API voor NoSQL-container, hetzij asynchrone afzonderlijke bewerkingen of een transactionele batch. In deze zelfstudie wordt uitgelegd hoe u een nieuwe .NET-consoletoepassing maakt waarmee meerdere items aan een container worden toegevoegd.

In deze zelfstudie leert u het volgende:

Een database maken met behulp van API voor NoSQL
Een .NET-consoletoepassing maken en de Azure SDK voor .NET toevoegen
Afzonderlijke items toevoegen aan een API voor NoSQL-container
Items ophalen die efficiënt zijn uit een API voor NoSQL-container
Een transactie maken met batchwijzigingen voor de API voor NoSQL-container

Vereisten

Een bestaand Azure Cosmos DB for NoSQL-account.
- Als u een bestaand Azure-abonnement hebt, maakt u een nieuw account.
- Geen Azure-abonnement? U kunt Azure Cosmos DB gratis proberen zonder dat er een creditcard is vereist.
Visual Studio Code
.NET 8 of hoger
Ervaring met het schrijven van C#-toepassingen.

API maken voor NoSQL-resources

Maak eerst een lege database in het bestaande API voor NoSQL-account. U maakt een container met behulp van de Azure SDK voor .NET later.

Navigeer naar uw bestaande API voor NoSQL-account in Azure Portal.
Selecteer Sleutels in het resourcemenu.
Bekijk en noteer op de pagina Sleutels de waarde van de velden URI en PRIMAIRE SLEUTEL. Deze waarden worden in de zelfstudie gebruikt.
Selecteer Data Explorer in het resourcemenu.
Selecteer op de pagina Data Explorer de optie Nieuwe database op de opdrachtbalk.
Maak in het dialoogvenster Nieuwe database een nieuwe container met de volgende instellingen:

Weergegeven als

Database-id cosmicworks

Type databasedoorvoer Handmatig

Hoeveelheid databasedoorvoer 400
Selecteer OK om de database te maken.

	Weergegeven als
Database-id	`cosmicworks`
Type databasedoorvoer	Handmatig
Hoeveelheid databasedoorvoer	`400`

.NET-consoletoepassing maken

U maakt nu een nieuwe .NET-consoletoepassing en importeert de Azure SDK voor .NET met behulp van de Microsoft.Azure.Cosmos bibliotheek van NuGet.

Open een terminal in een lege map.
Een nieuwe consoletoepassing maken met behulp van de console ingebouwde sjabloon
```
dotnet new console --langVersion preview
```
Voeg de versie 3.31.1-preview van het Microsoft.Azure.Cosmos pakket toe vanuit NuGet.
```
dotnet add package Microsoft.Azure.Cosmos --version 3.31.1-preview
```
Voeg ook de voorlopige versie van het System.CommandLine pakket toe vanuit NuGet.
```
dotnet add package System.CommandLine --prerelease
```
Voeg ook het Humanizer pakket toe vanuit NuGet.
```
dotnet add package Humanizer
```
Bouw het consoletoepassingsproject.
```
dotnet build
```
Open Visual Studio Code met behulp van de huidige projectmap als werkruimte.

Tip

U kunt in de terminal uitvoeren code . om Visual Studio Code te openen en de werkmap automatisch te openen als de huidige werkruimte.
Navigeer naar het Program.cs-bestand en open het. Verwijder alle bestaande code in het bestand.

Voeg deze code toe aan het bestand om de bibliotheek System.CommandLine te gebruiken om de opdrachtregel te parseren voor twee tekenreeksen die via de --first en --last opties zijn doorgegeven.

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

Notitie

Voor deze zelfstudie is het niet helemaal belangrijk dat u begrijpt hoe de opdrachtregelparser werkt. De parser heeft vier opties die kunnen worden opgegeven wanneer de toepassing wordt uitgevoerd. Er zijn drie van de opties vereist, omdat ze worden gebruikt om de id- en partitiesleutelvelden samen te stellen.

Op dit moment wordt het project niet gebouwd omdat u de statische CosmosHandler.ManageCustomerAsync methode nog niet hebt gedefinieerd.
Sla het Program.cs bestand op.

Items toevoegen aan een container met behulp van de SDK

Vervolgens gebruikt u afzonderlijke bewerkingen om items toe te voegen aan de API voor NoSQL-container. In deze sectie definieert u de CosmosHandler.ManageCustomerAsync methode.

Maak een nieuw CosmosHandler.cs-bestand .
Voeg in het bestand CosmosHandler.cs een nieuwe using-instructie toe voor de Humanizer en Microsoft.Azure.Cosmos naamruimten.
```
using Humanizer;
using Microsoft.Azure.Cosmos;
```
Maak een nieuwe statische klasse met de naam CosmosHandler.
```
public static class CosmosHandler
{ }
```

Als u alleen wilt controleren of deze app werkt, maakt u een korte implementatie van de statische ManageCustomerAsync methode om de opdrachtregelinvoer af te drukken.

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

Sla het bestand CosmosHandler.cs op.

Voer de toepassing uit in de terminal.

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

De uitvoer van de opdracht moet een leuke begroeting zijn.
```
Hello Mica Pereira of Washington, United States!
```
Ga terug naar het CosmosHandler.cs-bestand .
Voeg binnen de statische CosmosHandler-klasse een nieuw private static readonly lid van het type CosmosClient met de naam _clienttoe.
```
private static readonly CosmosClient _client;
```
Maak een nieuwe statische constructor voor de CosmosHandler klasse.
```
static CosmosHandler()
{ }
```
Maak in de constructor een nieuw exemplaar van de CosmosClient klasse die twee tekenreeksparameters doorgeeft met de URI - en PRIMARY KEY-waarden die u eerder in het lab hebt vastgelegd. Sla dit nieuwe exemplaar op in het _client lid.
```
static CosmosHandler()
{
    _client = new CosmosClient(
        accountEndpoint: "<uri>", 
        authKeyOrResourceToken: "<primary-key>"
    );
}
```
Maak in de statische CosmosHandler-klasse een nieuwe asynchrone methode met de naam GetContainerAsync die een Container.
```
private static async Task<Container> GetContainerAsync()
{ }
```
Voor de volgende stappen voegt u deze code toe binnen de GetContainerAsync methode.
1. Haal de database op en sla deze op in een variabele met de cosmicworks naam database.
```
Database database = _client.GetDatabase("cosmicworks");
```
2. Maak een nieuwe algemene waarde List<> string in een lijst met hiërarchische partitiesleutelpaden en sla deze op in een variabele met de naam keyPaths.
```
List<string> keyPaths = new()
{
    "/address/country",
    "/address/state"
};
```
3. Maak een nieuwe ContainerProperties variabele met de naam van de container (customers) en de lijst met partitiesleutelpaden.
```
ContainerProperties properties = new(
    id: "customers",
    partitionKeyPaths: keyPaths
);
```
4. Gebruik de CreateContainerIfNotExistsAsync methode om de containereigenschappen op te geven en de container op te halen. Met deze methode wordt de container asynchroon gemaakt op basis van de naam als deze nog niet in de database bestaat. Retourneer het resultaat als de uitvoer van de GetContainerAsync methode.
```
return await database.CreateContainerIfNotExistsAsync(
    containerProperties: properties
);
```
Verwijder alle code in de ManageCustomerAsync methode.
Voor de volgende stappen voegt u deze code toe binnen de ManageCustomerAsync methode.
1. Roep de GetContainerAsync methode asynchroon aan en sla het resultaat op in een variabele met de naam container.
```
Container container = await GetContainerAsync();
```
2. Maak een nieuwe variabele met de naam id die gebruikmaakt van de Kebaberize methode van Humanizer om de name methodeparameter te transformeren.
```
string id = name.Kebaberize();
```
  Notitie
  
  De Kebaberize methode vervangt alle spaties door afbreekstreepjes en voegt de tekst samen in kleine letters.
3. Maak een nieuw anoniem getypt item met behulp van de nameparameters en statecountry methoden en de id variabele. Sla het item op als een variabele met de naam customer.
```
var customer = new {
    id = id,
    name = name,
    address = new {
        state = state,
        country = country
    }
};
```
4. Gebruik de asynchrone CreateItemAsync methode van de container om een nieuw item in de container te maken en de METAGEGEVENS van het HTTP-antwoord toe te wijzen aan een variabele met de naam response.
```
var response = await container.CreateItemAsync(customer);
```
5. Schrijf de waarden van de response variabele StatusCode en RequestCharge eigenschappen naar de console. Schrijf ook de waarde van de id variabele.
```
Console.WriteLine($"[{response.StatusCode}]\t{id}\t{response.RequestCharge} RUs");
```
Sla het bestand CosmosHandler.cs op.

Voer de toepassing opnieuw uit in de terminal.

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

De uitvoer van de opdracht moet een status en aanvraagkosten voor de bewerking bevatten.
```
[Created]       mica-pereira    7.05 RUs
```
Notitie

De kosten van uw aanvraag kunnen variëren.

Voer de toepassing nog één keer uit.

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

Deze keer moet het programma vastlopen. Als u door het foutbericht bladert, ziet u dat de crash is opgetreden vanwege een conflict in de unieke id voor de items.

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."
    ]
);

Een item ophalen met behulp van de SDK

Nu u uw eerste item in de container hebt gemaakt, kunt u dezelfde SDK gebruiken om het item op te halen. Hier leest u het item en wijst u het item aan om het verschil in ru-verbruik (request unit) te vergelijken.

Ga terug naar of open het CosmosHandler.cs bestand.

Verwijder alle regels code uit de ManageCustomerAsync methode, met uitzondering van de eerste twee regels.

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

    string id = name.Kebaberize();
}

Voor de volgende stappen voegt u deze code toe binnen de ManageCustomerAsync methode.
1. Gebruik de asynchrone CreateItemAsync methode van de container om een nieuw item in de container te maken en de METAGEGEVENS van het HTTP-antwoord toe te wijzen aan een variabele met de naam response.
```
var response = await container.CreateItemAsync(customer);
```
2. Maak een nieuwe tekenreeks met de naam sql met een SQL-query om items op te halen waarin een filter (@id) overeenkomt.
```
string sql = @"
SELECT
    *
FROM customers c
WHERE c.id = @id
";
```
3. Maak een nieuwe QueryDefinition variabele met de naam query doorgeven in de sql tekenreeks als de enige queryparameter. Gebruik ook de WithParameter vloeistofmethode om de waarde van de variabele id toe te passen op de @id parameter.
```
var query = new QueryDefinition(
    query: sql
)
    .WithParameter("@id", id);
```
4. Gebruik de GetItemQueryIterator<> algemene methode en de query variabele om een iterator te maken die gegevens ophaalt uit Azure Cosmos DB. Sla de iterator op in een variabele met de naam feed. Verpakt deze volledige expressie in een using-instructie om de iterator later te verwijderen.
```
using var feed = container.GetItemQueryIterator<dynamic>(
    queryDefinition: query
);
```
5. Roep asynchroon de methode van de ReadNextAsync feed variabele aan en sla het resultaat op in een variabele met de naam response.
```
var response = await feed.ReadNextAsync();
```
6. Schrijf de waarden van de response variabele StatusCode en RequestCharge eigenschappen naar de console. Schrijf ook de waarde van de id variabele.
```
Console.WriteLine($"[{response.StatusCode}]\t{id}\t{response.RequestCharge} RUs");
```
Sla het bestand CosmosHandler.cs op.
Voer in de terminal de toepassing uit om het ene item te lezen met behulp van een SQL-query.
```
dotnet run -- --name 'Mica Pereira' --state 'Washington' --country 'United States'
```
De uitvoer van de opdracht moet aangeven dat de query meerdere aanvraageenheden (RU's) vereist.
```
[OK]    mica-pereira    2.82 RUs
```

Verwijder in het bestand CosmosHandler.cs alle coderegels opnieuw uit de ManageCustomerAsync methode, met uitzondering van de eerste twee regels.

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

    string id = name.Kebaberize();
}

Voor de volgende stappen voegt u deze code toe binnen de ManageCustomerAsync methode.
1. Maak een nieuw exemplaar van PartitionKeyBuilder door de state en country parameters toe te voegen als een partitiesleutelwaarde met meerdere onderdelen.
```
var partitionKey = new PartitionKeyBuilder()
    .Add(country)
    .Add(state)
    .Build();
```
2. Gebruik de methode van ReadItemAsync<> de container om het item uit de container aan te wijzen met behulp van de id en partitionKey variabelen. Sla het resultaat op in een variabele met de naam response.
```
var response = await container.ReadItemAsync<dynamic>(
    id: id, 
    partitionKey: partitionKey
);
```
3. Schrijf de waarden van de response variabele StatusCode en RequestCharge eigenschappen naar de console. Schrijf ook de waarde van de id variabele.
```
Console.WriteLine($"[{response.StatusCode}]\t{id}\t{response.RequestCharge} RU");
```
Sla het CosmosHandler.cs bestand opnieuw op.
Voer in de terminal de toepassing nog één keer uit om het ene item te laten verwijzen.
```
dotnet run -- --name 'Mica Pereira' --state 'Washington' --country 'United States'
```
De uitvoer van de opdracht moet aangeven dat de query één RU vereist.
```
[OK]    mica-pereira    1 RUs
```

Een transactie maken met behulp van de SDK

Ten slotte neemt u het item dat u hebt gemaakt, leest u dat item en maakt u een ander gerelateerd item als onderdeel van één transactie met behulp van de Azure SDK voor .NET.

Ga terug naar of open het CosmosHandler.cs bestand.

Verwijder deze coderegels uit de ManageCustomerAsync methode.

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

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

Voor de volgende stappen voegt u deze nieuwe code toe binnen de ManageCustomerAsync methode.
1. Maak een nieuw anoniem getypt item met behulp van de nameparameters en statecountry methoden en de id variabele. Sla het item op als een variabele met de naam customerCart. Dit item vertegenwoordigt een realtime winkelwagen voor de klant die momenteel leeg is.
```
var customerCart = new {
    id = $"{Guid.NewGuid()}",
    customerId = id,
    items = new string[] {},
    address = new {
        state = state,
        country = country
    }
};
```
2. Maak nog een nieuw anoniem getypt item met behulp van de nameparameters en statecountry methodeparameters en de id variabele. Sla het item op als een variabele met de naam customerCart. Dit item vertegenwoordigt de verzend- en contactgegevens voor de klant.
```
var customerContactInfo = new {
    id = $"{id}-contact",
    customerId = id,
    email = email,
    location = $"{state}, {country}",
    address = new {
        state = state,
        country = country
    }
};
```
3. Maak een nieuwe batch met behulp van de methode van CreateTransactionalBatch de container die in de partitionKey variabele wordt doorgegeven. Sla de batch op in een variabele met de naam batch. Gebruik fluent-methoden om de volgende acties uit te voeren:
  
  Wijze Parameter
  
  ReadItem id tekenreeksvariabele
  
  CreateItem customerCart anonieme typevariabele
  
  CreateItem customerContactInfo anonieme typevariabele
```
var batch = container.CreateTransactionalBatch(partitionKey)
    .ReadItem(id)
    .CreateItem(customerCart)
    .CreateItem(customerContactInfo);
```
4. Gebruik de methode van ExecuteAsync de batch om de transactie te starten. Sla het resultaat op in een variabele met de naam response.
```
using var response = await batch.ExecuteAsync();
```
5. Schrijf de waarden van de response variabele StatusCode en RequestCharge eigenschappen naar de console. Schrijf ook de waarde van de id variabele.
```
Console.WriteLine($"[{response.StatusCode}]\t{response.RequestCharge} RUs");
```
Sla het CosmosHandler.cs bestand opnieuw op.
Voer in de terminal de toepassing nog één keer uit om het ene item te laten verwijzen.
```
dotnet run -- --name 'Mica Pereira' --state 'Washington' --country 'United States'
```
In de uitvoer van de opdracht moeten de aanvraageenheden worden weergegeven die worden gebruikt voor de hele transactie.
```
[OK]    16.05 RUs
```
Notitie

De kosten van uw aanvraag kunnen variëren.

Wijze	Parameter
`ReadItem`	`id` tekenreeksvariabele
`CreateItem`	`customerCart` anonieme typevariabele
`CreateItem`	`customerContactInfo` anonieme typevariabele

De laatste gegevens valideren in Data Explorer

Als u dingen wilt inpakken, gebruikt u Data Explorer in Azure Portal om de gegevens en container weer te geven die u in deze zelfstudie hebt gemaakt.

Navigeer naar uw bestaande API voor NoSQL-account in Azure Portal.
Selecteer Data Explorer in het resourcemenu.
Vouw op de pagina Data Explorer de cosmicworks database uit en selecteer vervolgens de customers container.
Selecteer nieuwe SQL-query in de opdrachtbalk.
Bekijk deze SQL-querytekenreeks in de queryeditor.
```
SELECT * FROM c
```
Selecteer Query uitvoeren om de query uit te voeren en bekijk de resultaten.

De resultaten moeten een JSON-matrix bevatten met drie items die in deze zelfstudie zijn gemaakt. U ziet dat alle items dezelfde hiërarchische partitiesleutelwaarde hebben, maar unieke id-velden. De voorbeelduitvoer die is opgenomen, wordt afgekapt voor kortheid.

[
  {
    "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"
    },
    ...
  }
]

Resources opschonen

Wanneer u deze niet meer nodig hebt, verwijdert u de database die in deze zelfstudie wordt gebruikt. Hiervoor gaat u naar de accountpagina, selecteert u Data Explorer, selecteert u de cosmicworks database en selecteert u Vervolgens Verwijderen.

Delen via