Rychlý start: Azure Cosmos DB pro MongoDB pro .NET s ovladačem MongoDB

Článek
03/28/2024

PLATÍ PRO: MongoDB

Začněte s MongoDB vytvářet databáze, kolekce a dokumenty v rámci prostředku služby Azure Cosmos DB. Pomocí následujícího postupu nasaďte do svého prostředí minimální řešení pomocí Azure Developer CLI.

Referenční dokumentace k rozhraní API pro MongoDB Package (NuGet) s referenční dokumentací | k rozhraní API pro MongoDB / Microsoft.Azure.Cosmos) | Azure Developer CLI

Požadavky

Účet Azure s aktivním předplatným. Vytvoření účtu zdarma
Účet GitHub

Účet Azure s aktivním předplatným. Vytvoření účtu zdarma
Azure Developer CLI
Docker Desktop

Nastavení

Nasaďte vývojový kontejner tohoto projektu do svého prostředí. Pak pomocí Azure Developer CLI (azd) vytvořte účet služby Azure Cosmos DB pro MongoDB a nasaďte kontejnerizovanou ukázkovou aplikaci. Ukázková aplikace používá klientskou knihovnu ke správě, vytváření, čtení a dotazování ukázkových dat.

Důležité

Účty GitHubu zahrnují nárok na úložiště a hodiny jádra bez poplatků. Další informace najdete v zahrnutých hodinách úložiště a jader pro účty GitHubu.

Otevřete terminál v kořenovém adresáři projektu.
Ověřte se v Rozhraní příkazového řádku Azure Developer CLI pomocí azd auth loginrozhraní příkazového řádku . Postupujte podle kroků určených nástrojem k ověření v rozhraní příkazového řádku pomocí vašich upřednostňovaných přihlašovacích údajů Azure.
```
azd auth login
```
Slouží azd init k inicializaci projektu.
```
azd init
```
Během inicializace nakonfigurujte jedinečný název prostředí.

Tip

Název prostředí se také použije jako název cílové skupiny prostředků. Pro účely tohoto rychlého startu zvažte použití .msdocs-cosmos-db-
Nasaďte účet služby Azure Cosmos DB pomocí azd up. Šablony Bicep také nasazují ukázkovou webovou aplikaci.
```
azd up
```
Během procesu zřizování vyberte své předplatné a požadované umístění. Počkejte na dokončení procesu zřizování. Proces může trvat přibližně pět minut.

Po dokončení zřizování prostředků Azure se do výstupu zahrne adresa URL spuštěné webové aplikace.

Deploying services (azd deploy)

  (✓) Done: Deploying service web
- Endpoint: <https://[container-app-sub-domain].azurecontainerapps.io>

SUCCESS: Your application was provisioned and deployed to Azure in 5 minutes 0 seconds.

Pomocí adresy URL v konzole přejděte do webové aplikace v prohlížeči. Sledujte výstup spuštěné aplikace.

Instalace klientské knihovny

Klientská knihovna je k dispozici prostřednictvím Balíčku NuGet Microsoft.Azure.Cosmos .

Otevřete terminál a přejděte do /src/web složky.
```
cd ./src/web
```
Pokud ještě není nainstalovaný, nainstalujte MongoDb.Driver balíček pomocí dotnet add package.
```
dotnet add package MongoDb.Driver
```
Pokud ještě není nainstalovaný, nainstalujte Azure.Identity balíček.
```
dotnet add package Azure.Identity
```

Objektový model

Než začnete vytvářet aplikaci, podívejme se na hierarchii prostředků ve službě Azure Cosmos DB. Azure Cosmos DB má konkrétní objektový model, který se používá k vytváření a přístupu k prostředkům. Azure Cosmos DB vytváří prostředky v hierarchii, které se skládají z účtů, databází, kolekcí a dokumentů.

Diagram hierarchie služby Azure Cosmos DB, včetně účtů, databází, kolekcí a dokumentů

K interakci s těmito prostředky použijete následující třídy MongoDB:

MongoClient – Tato třída poskytuje logickou reprezentaci na straně klienta pro vrstvu rozhraní API pro MongoDB ve službě Azure Cosmos DB. Objekt klienta slouží ke konfiguraci a spouštění požadavků na službu.
MongoDatabase – Tato třída je odkazem na databázi, která může nebo nemusí existovat ve službě ještě. Databáze je ověřena na straně serveru, když se pokusíte o přístup k databázi nebo provedete operaci s ní.
Collection – Tato třída je odkazem na kolekci, která ještě nemusí ve službě existovat. Kolekce se ověří na straně serveru, když se s ní pokusíte pracovat.

Vzorový kód ukázaný v tomto článku vytvoří databázi s názvem adventureworks kolekce s názvem products. Kolekce products je navržená tak, aby obsahovala podrobnosti o produktu, jako je název, kategorie, množství a indikátor prodeje. Každý produkt obsahuje také jedinečný identifikátor.

Ověření klienta

V adresáři projektu otevřete soubor Program.cs . V editoru přidejte direktivu using pro MongoDB.Driver.

using MongoDB.Driver;

Definujte novou instanci MongoClient třídy pomocí konstruktoru a Environment.GetEnvironmentVariable načtěte připojovací řetězec, kterou jste nastavili dříve.

// New instance of CosmosClient class
var client = new MongoClient(Environment.GetEnvironmentVariable("MONGO_CONNECTION"));

Vytvořit databázi

Tuto metodu MongoClient.GetDatabase použijte k vytvoření nové databáze, pokud ještě neexistuje. Tato metoda vrátí odkaz na existující nebo nově vytvořenou databázi.

// Database reference with creation if it does not already exist
var db = client.GetDatabase("adventure");

Vytvoření kolekce

Pokud MongoDatabase.GetCollection ještě neexistuje, vytvoří se nová kolekce a vrátí odkaz na kolekci.

// Container reference with creation if it does not alredy exist
var _products = db.GetCollection<Product>("products");

Vytvoření položky

Nejjednodušší způsob, jak vytvořit novou položku v kolekci, je vytvořit třídu nebo typ záznamu jazyka C# se všemi členy, které chcete serializovat do formátu JSON. V tomto příkladu má záznam C# jedinečný identifikátor, pole kategorie pro klíč oddílu a další název, množství a pole prodeje.

public record Product(
    string Id,
    string Category,
    string Name,
    int Quantity,
    bool Sale
);

Vytvořte položku v kolekci pomocí záznamu Product voláním IMongoCollection<TDocument>.InsertOne.

// Create new object and upsert (create or replace) to container
_products.InsertOne(new Product(
    Guid.NewGuid().ToString(),
    "gear-surf-surfboards",
    "Yamba Surfboard", 
    12, 
    false
));

Získání položky

Ve službě Azure Cosmos DB můžete položky načíst tak, že vytvoříte dotazy pomocí Linqu. Voláním a předáním výrazu jazyka C# v sadě SDK IMongoCollection.FindAsync<> vyfiltrujte výsledky.

// Read a single item from container
var product = (await _products.FindAsync(p => p.Name.Contains("Yamba"))).FirstOrDefault();
Console.WriteLine("Single product:");
Console.WriteLine(product.Name);

Dotazování položek

Po vložení položky můžete spustit dotaz, abyste získali všechny položky, které odpovídají určitému filtru, tím, že s kolekcí zachází jako s IQueryable. Tento příklad používá výraz k filtrování produktů podle kategorie. Po volání AsQueryableMongoQueryable.Where volání načtěte sadu filtrovaných položek.

// Read multiple items from container
_products.InsertOne(new Product(
    Guid.NewGuid().ToString(),
    "gear-surf-surfboards",
    "Sand Surfboard",
    4,
    false
));

var products = _products.AsQueryable().Where(p => p.Category == "gear-surf-surfboards");

Console.WriteLine("Multiple products:");
foreach (var prod in products)
{
    Console.WriteLine(prod.Name);
}

Spuštění kódu

Tato aplikace vytvoří databázi a kolekci rozhraní MongoDb API služby Azure Cosmos DB. Příklad pak vytvoří položku a pak přečte úplně stejnou položku zpět. Nakonec příklad vytvoří druhou položku a pak provede dotaz, který by měl vrátit více položek. V každém kroku příklad vypíše metadata do konzoly o krocích, které provedl.

Pokud chcete aplikaci spustit, přejděte pomocí terminálu do adresáře aplikace a spusťte aplikaci.

dotnet run

Výstup aplikace by měl být podobný tomuto příkladu:

Single product name: 
Yamba Surfboard
Multiple products:
Yamba Surfboard
Sand Surfboard

Vyčištění prostředků

Pokud už účet Azure Cosmos DB pro MongoDB nepotřebujete, můžete odstranit odpovídající skupinu prostředků.

az group delete Pomocí příkazu odstraňte skupinu prostředků.

az group delete --name $resourceGroupName

Pomocí rutiny Remove-AzResourceGroup odstraňte skupinu prostředků.

$parameters = @{
    Name = $RESOURCE_GROUP_NAME
}
Remove-AzResourceGroup @parameters