Snabbstart: Azure Cosmos DB för MongoDB för .NET med MongoDB-drivrutinen

GÄLLER FÖR: Mongodb

Kom igång med MongoDB för att skapa databaser, samlingar och dokument i din Azure Cosmos DB-resurs. Följ de här stegen för att installera paketet och prova exempelkod för grundläggande uppgifter.

Kommentar

Exempelkodfragmenten är tillgängliga på GitHub som ett .NET-projekt.

API för MongoDB-referensdokumentation | MongoDB Package (NuGet)

Förutsättningar

Kravkontroll

  • I ett terminal- eller kommandofönster kör du dotnet --list-sdks för att kontrollera att .NET 6.x är en av de tillgängliga versionerna.
  • Kör az --version (Azure CLI) eller Get-Module -ListAvailable AzureRM (Azure PowerShell) för att kontrollera att du har rätt Azure-kommandoradsverktyg installerade.

Konfigurera

Det här avsnittet beskriver hur du skapar ett Azure Cosmos DB-konto och konfigurerar ett projekt som använder MongoDB NuGet-paketen.

Skapa ett Azure Cosmos DB-konto

Den här snabbstarten skapar ett enda Azure Cosmos DB-konto med hjälp av API:et för MongoDB.

  1. Skapa gränssnittsvariabler för accountName, resourceGroupName och plats.

    # Variable for resource group name
    resourceGroupName="msdocs-cosmos-quickstart-rg"
    location="westus"
    
    # Variable for account name with a randomnly generated suffix
    let suffix=$RANDOM*$RANDOM
    accountName="msdocs-$suffix"
    
  2. Om du inte redan har gjort det loggar du in på Azure CLI med kommandot az login .

  3. az group create Använd kommandot för att skapa en ny resursgrupp i din prenumeration.

    az group create \
        --name $resourceGroupName \
        --location $location
    
  4. az cosmosdb create Använd kommandot för att skapa ett nytt Azure Cosmos DB för MongoDB-konto med standardinställningar.

    az cosmosdb create \
        --resource-group $resourceGroupName \
        --name $accountName \
        --locations regionName=$location
        --kind MongoDB
    

Hämta anslutningssträngen för MongoDB

  1. Leta upp API:et för MongoDB-anslutningssträng från listan över anslutningssträng för kontot med az cosmosdb keys list kommandot .

    az cosmosdb keys list --type connection-strings \
        --resource-group $resourceGroupName \
        --name $accountName 
    
  2. Registrera primärnyckelvärdena. Du använder dessa autentiseringsuppgifter senare.

Skapa en ny .NET-app

Skapa ett nytt .NET-program i en tom mapp med hjälp av önskad terminal. dotnet new console Använd för att skapa en ny konsolapp.

dotnet new console -o <app-name>

Installera NuGet-paketet

Lägg till NuGet-paketet MongoDB.Driver i det nya .NET-projektet. dotnet add package Använd kommandot som anger namnet på NuGet-paketet.

dotnet add package MongoDb.Driver

Konfigurera miljövariabler

Om du vill använda VÄRDENA FÖR ANSLUTNINGSSTRÄNG i koden anger du det här värdet i den lokala miljö som kör programmet. Om du vill ange miljövariabeln använder du önskad terminal för att köra följande kommandon:

$env:COSMOS_CONNECTION_STRING = "<cosmos-connection-string>"

Objektmodell

Innan du börjar skapa programmet ska vi titta på resurshierarkin i Azure Cosmos DB. Azure Cosmos DB har en specifik objektmodell som används för att skapa och komma åt resurser. Azure Cosmos DB skapar resurser i en hierarki som består av konton, databaser, samlingar och dokument.

Diagram of the Azure Cosmos DB hierarchy including accounts, databases, collections, and docs.

Hierarkiskt diagram som visar ett Azure Cosmos DB-konto högst upp. Kontot har två underordnade databasskärvor. En av databasskärvorna innehåller två underordnade samlingsshards. Den andra databassharden innehåller en enda underordnad samlingsshard. Den enda samlingssharden har tre underordnade dokumentskärvor.

Du använder följande MongoDB-klasser för att interagera med dessa resurser:

  • MongoClient – Den här klassen ger en logisk representation på klientsidan för API:et för MongoDB-lagret i Azure Cosmos DB. Klientobjektet används för att konfigurera och köra begäranden mot tjänsten.
  • MongoDatabase – Den här klassen är en referens till en databas som kanske, eller kanske inte finns i tjänsten ännu. Databasen verifieras på serversidan när du försöker komma åt den eller utföra en åtgärd mot den.
  • Collection – Den här klassen är en referens till en samling som kanske inte heller finns i tjänsten ännu. Samlingen verifieras på serversidan när du försöker arbeta med den.

Kodexempel

Exempelkoden som visas i den här artikeln skapar en databas med namnet adventureworks med en samling med namnet products. Samlingen products är utformad för att innehålla produktinformation som namn, kategori, kvantitet och en försäljningsindikator. Varje produkt innehåller också en unik identifierare.

Autentisera klienten

Öppna filen Program.cs från projektkatalogen. I redigeringsprogrammet lägger du till ett användningsdirektiv för MongoDB.Driver.

using MongoDB.Driver;

Definiera en ny instans av MongoClient klassen med konstruktorn och Environment.GetEnvironmentVariable för att läsa anslutningssträng du angav tidigare.

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

Skapa en -databas

MongoClient.GetDatabase Använd metoden för att skapa en ny databas om den inte redan finns. Den här metoden returnerar en referens till den befintliga eller nyligen skapade databasen.

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

Skapa en samling

Skapar MongoDatabase.GetCollection en ny samling om den inte redan finns och returnerar en referens till samlingen.

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

Skapa ett objekt

Det enklaste sättet att skapa ett nytt objekt i en samling är att skapa en C#- klass eller posttyp med alla medlemmar som du vill serialisera till JSON. I det här exemplet har C#-posten en unik identifierare, ett kategorifält för partitionsnyckeln och extra namn, kvantitet och försäljningsfält .

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

Skapa ett objekt i samlingen med posten Product genom att anropa 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
));

Hämta ett objekt

I Azure Cosmos DB kan du hämta objekt genom att skriva frågor med linq. I SDK anropar IMongoCollection.FindAsync<> och skickar du ett C#-uttryck för att filtrera resultatet.

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

Frågeobjekt

När du har infogat ett objekt kan du köra en fråga för att hämta alla objekt som matchar ett specifikt filter genom att behandla samlingen som en IQueryable. I det här exemplet används ett uttryck för att filtrera produkter efter kategori. När anropet till AsQueryable har gjorts anropar du MongoQueryable.Where för att hämta en uppsättning filtrerade objekt.

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

Kör koden

Den här appen skapar en Azure Cosmos DB MongoDb API-databas och samling. Exemplet skapar sedan ett objekt och läser sedan exakt samma objekt tillbaka. Slutligen skapar exemplet ett andra objekt och utför sedan en fråga som ska returnera flera objekt. Med varje steg matar exemplet ut metadata till konsolen om de steg som den har utfört.

Om du vill köra appen använder du en terminal för att navigera till programkatalogen och köra programmet.

dotnet run

Utdata från appen bör likna det här exemplet:

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

Rensa resurser

När du inte längre behöver Azure Cosmos DB för NoSQL-kontot kan du ta bort motsvarande resursgrupp.

az group delete Använd kommandot för att ta bort resursgruppen.

az group delete --name $resourceGroupName