Kom igång med Azure Cosmos DB för NoSQL med hjälp av .NET

GÄLLER FÖR: NoSQL

Den här artikeln visar hur du ansluter till Azure Cosmos DB för NoSQL med hjälp av .NET SDK. När du är ansluten kan du utföra åtgärder på databaser, containrar och objekt.

Package (NuGet)Samples API reference Library source code Give Feedback (Paket (NuGet) | Samples | API reference | Library source code | Give Feedback

Förutsättningar

• Ett Azure-konto med en aktiv prenumeration. Skapa ett konto utan kostnad.
• Azure Cosmos DB för NoSQL-konto. Skapa ett API för NoSQL-konto.
• .NET 6.0 eller senare
• Azures kommandoradsgränssnitt (CLI) eller Azure PowerShell

Konfigurera projektet

Skapa .NET-konsolprogrammet

Skapa ett nytt .NET-program med hjälp dotnet new av kommandot med konsolmallen.

dotnet new console

Importera NuGet-paketet Microsoft.Azure.Cosmos med kommandot dotnet add package .

dotnet add package Microsoft.Azure.Cosmos

Skapa projektet med dotnet build kommandot .

dotnet build

Anslut till Azure Cosmos DB för NoSQL

Om du vill ansluta till API:et för NoSQL för Azure Cosmos DB skapar du en instans av CosmosClient klassen. Den här klassen är utgångspunkten för att utföra alla åtgärder mot databaser. Det finns tre huvudsakliga sätt att ansluta till ett API för NoSQL-konto med klassen CosmosClient :

• Anslut med ett API för NoSQL-slutpunkt och läs-/skrivnyckel
• Anslut med ett API för NoSQL-anslutningssträng
• Anslut med Microsoft Entra-ID

Anslut med en slutpunkt och nyckel

Den vanligaste konstruktorn för CosmosClient har två parametrar:

Parameter	Exempelvärde	Description
accountEndpoint	COSMOS_ENDPOINT miljövariabel	API för NoSQL-slutpunkt som ska användas för alla begäranden
authKeyOrResourceToken	COSMOS_KEY miljövariabel	Kontonyckel eller resurstoken som ska användas vid autentisering

Hämta din kontoslutpunkt och nyckel

Azure CLI

1. Skapa en gränssnittsvariabel för resourceGroupName.

   # Variable for resource group name
   resourceGroupName="msdocs-cosmos-dotnet-howto-rg"
   

2. az cosmosdb list Använd kommandot för att hämta namnet på det första Azure Cosmos DB-kontot i resursgruppen och lagra det i variabeln accountName-gränssnittet.

   # Retrieve most recently created account name
   accountName=$(
       az cosmosdb list \
           --resource-group $resourceGroupName \
           --query "[0].name" \
           --output tsv
   )
   

3. Hämta API:et för NoSQL-slutpunkts-URI för kontot med kommandot az cosmosdb show .

   az cosmosdb show \
       --resource-group $resourceGroupName \
       --name $accountName \
       --query "documentEndpoint"
   

4. Leta reda på PRIMÄRNYCKEL i listan över nycklar för kontot med az-cosmosdb-keys-list kommandot .

   az cosmosdb keys list \
       --resource-group $resourceGroupName \
       --name $accountName \
       --type "keys" \
       --query "primaryMasterKey"
   

5. Registrera värdena för URI och PRIMÄRNYCKEL . Du använder dessa autentiseringsuppgifter senare.

PowerShell

1. Skapa en gränssnittsvariabel för RESOURCE_GROUP_NAME.

   # Variable for resource group name
   $RESOURCE_GROUP_NAME = "msdocs-cosmos-dotnet-howto-rg"
   

2. Använd cmdleten Get-AzCosmosDBAccount för att hämta namnet på det första Azure Cosmos DB-kontot i resursgruppen och lagra det i variabeln ACCOUNT_NAME shell.

   # Retrieve most recently created account name
   $parameters = @{
       ResourceGroupName = $RESOURCE_GROUP_NAME
   }
   $ACCOUNT_NAME = (
       Get-AzCosmosDBAccount @parameters |
           Select-Object -Property Name -First 1
   ).Name
   

3. Hämta API:et för NoSQL-slutpunkts-URI för kontot med hjälp av cmdletenGet-AzCosmosDBAccount.

   $parameters = @{
       ResourceGroupName = $RESOURCE_GROUP_NAME
       Name = $ACCOUNT_NAME
   }
   Get-AzCosmosDBAccount @parameters |
       Select-Object -Property "DocumentEndpoint"
   

4. Leta reda på PRIMÄRNYCKEL i listan över nycklar för kontot med cmdletenGet-AzCosmosDBAccountKey.

   $parameters = @{
       ResourceGroupName = $RESOURCE_GROUP_NAME
       Name = $ACCOUNT_NAME
       Type = "Keys"
   }    
   Get-AzCosmosDBAccountKey @parameters |
       Select-Object -Property "PrimaryMasterKey"    
   

5. Registrera värdena för URI och PRIMÄRNYCKEL . Du använder dessa autentiseringsuppgifter senare.

Portal

Dricks

För den här guiden rekommenderar vi att du använder resursgruppens namn msdocs-cosmos-dotnet-howto-rg.

1. Logga in på Azure-portalen.

2. Gå till den befintliga kontosidan för Azure Cosmos DB för NoSQL.

3. På sidan Azure Cosmos DB för NoSQL-konto väljer du menyalternativet Nycklar i navigeringsmenyn.

   

4. Registrera värdena från fälten URI och PRIMÄRNYCKEL . Du använder dessa värden i ett senare steg.

   

Om du vill använda värdena för URI och PRIMÄRNYCKEL i .NET-koden sparar du dem i nya miljövariabler på den lokala dator som kör programmet.

Windows

$env:COSMOS_ENDPOINT = "<cosmos-account-URI>"
$env:COSMOS_KEY = "<cosmos-account-PRIMARY-KEY>"

Linux/macOS

export COSMOS_ENDPOINT="<cosmos-account-URI>"
export COSMOS_KEY="<cosmos-account-PRIMARY-KEY>"

Skapa CosmosClient med kontoslutpunkt och nyckel

Skapa en ny instans av klassen CosmosClient med COSMOS_ENDPOINT miljövariablerna och COSMOS_KEY som parametrar.

// New instance of CosmosClient class using an endpoint and key string
using CosmosClient client = new(
    accountEndpoint: Environment.GetEnvironmentVariable("COSMOS_ENDPOINT")!,
    authKeyOrResourceToken: Environment.GetEnvironmentVariable("COSMOS_KEY")!
);

Anslut med en anslutningssträng

En annan konstruktor för CosmosClient innehåller bara en enda parameter:

Parameter	Exempelvärde	Description
accountEndpoint	COSMOS_ENDPOINT miljövariabel	API för NoSQL-slutpunkt som ska användas för alla begäranden
connectionString	COSMOS_CONNECTION_STRING miljövariabel	Anslut ionssträng till API:et för NoSQL-kontot

Hämta ditt konto anslutningssträng

Azure CLI

1. az cosmosdb list Använd kommandot för att hämta namnet på det första Azure Cosmos DB-kontot i resursgruppen och lagra det i variabeln accountName-gränssnittet.

   # Retrieve most recently created account name
   accountName=$(
       az cosmosdb list \
           --resource-group $resourceGroupName \
           --query "[0].name" \
           --output tsv
   )
   

2. Leta upp DEN PRIMÄRA ANSLUTNINGSSTRÄNGen i listan över anslutningssträng för kontot med az-cosmosdb-keys-list kommandot .

   az cosmosdb keys list \
       --resource-group $resourceGroupName \
       --name $accountName \
       --type "connection-strings" \
       --query "connectionStrings[?description == \`Primary SQL Connection String\`] | [0].connectionString"
   

PowerShell

1. Använd cmdleten Get-AzCosmosDBAccount för att hämta namnet på det första Azure Cosmos DB-kontot i resursgruppen och lagra det i variabeln ACCOUNT_NAME shell.

   # Retrieve most recently created account name
   $parameters = @{
       ResourceGroupName = $RESOURCE_GROUP_NAME
   }
   $ACCOUNT_NAME = (
       Get-AzCosmosDBAccount @parameters |
           Select-Object -Property Name -First 1
   ).Name
   

2. Leta upp DEN PRIMÄRA ANSLUTNINGSSTRÄNGen i listan över anslutningssträng för kontot med cmdletenGet-AzCosmosDBAccountKey.

   $parameters = @{
       ResourceGroupName = $RESOURCE_GROUP_NAME
       Name = $ACCOUNT_NAME
       Type = "ConnectionStrings"
   }    
   Get-AzCosmosDBAccountKey @parameters |
       Select-Object -Property "Primary SQL Connection String" -First 1    
   

Portal

Dricks

För den här guiden rekommenderar vi att du använder resursgruppens namn msdocs-cosmos-dotnet-howto-rg.

1. Logga in på Azure-portalen.

2. Gå till den befintliga kontosidan för Azure Cosmos DB för NoSQL.

3. På sidan Azure Cosmos DB för NoSQL-konto väljer du menyalternativet Nycklar i navigeringsmenyn.

4. Registrera värdet från fältet PRIMÄR ANSLUTNINGSSTRÄNG .

Om du vill använda värdet PRIMÄR ANSLUTNINGSSTRÄNG i .NET-koden bevarar du det till en ny miljövariabel på den lokala dator som kör programmet.

Windows

$env:COSMOS_CONNECTION_STRING = "<cosmos-account-PRIMARY-CONNECTION-STRING>"

Linux/macOS

export COSMOS_CONNECTION_STRING="<cosmos-account-PRIMARY-CONNECTION-STRING>"

Skapa CosmosClient med anslutningssträng

Skapa en ny instans av klassen CosmosClient med COSMOS_CONNECTION_STRING miljövariabeln som den enda parametern.

// New instance of CosmosClient class using a connection string
using CosmosClient client = new(
    connectionString: Environment.GetEnvironmentVariable("COSMOS_CONNECTION_STRING")!
);

Anslut med hjälp av Microsofts identitetsplattform

Om du vill ansluta till ditt API för NoSQL-konto med hjälp av Microsofts identitetsplattform och Microsoft Entra-ID använder du ett säkerhetsobjekt. Den exakta typen av huvudnamn beror på var du är värd för programkoden. Tabellen nedan fungerar som en snabbreferensguide.

Där programmet körs	Säkerhetsobjekt
Lokal dator (utveckla och testa)	Användaridentitet eller tjänstens huvudnamn
Azure	Hanterad identitet
Servrar eller klienter utanför Azure	Tjänstens huvudnamn

Importera Azure.Identity

NuGet-paketet Azure.Identity innehåller grundläggande autentiseringsfunktioner som delas mellan alla Azure SDK-bibliotek.

Importera Azure.Identity NuGet-paketet med kommandot dotnet add package .

dotnet add package Azure.Identity

Återskapa projektet med dotnet build kommandot .

dotnet build

I kodredigeraren lägger du till med hjälp av direktiv för Azure.Core och Azure.Identity namnområden.

using Azure.Core;
using Azure.Identity;

Skapa CosmosClient med standardimplementering av autentiseringsuppgifter

Om du testar på en lokal dator, eller om programmet körs på Azure-tjänster med direkt stöd för hanterade identiteter, hämtar du en OAuth-token genom att skapa en DefaultAzureCredential instans.

I det här exemplet sparade vi instansen i en variabel av typen TokenCredential eftersom det är en mer allmän typ som kan återanvändas mellan SDK:er.

// Credential class for testing on a local machine or Azure services
TokenCredential credential = new DefaultAzureCredential();

Skapa en ny instans av klassen CosmosClient med COSMOS_ENDPOINT miljövariabeln och TokenCredential-objektet som parametrar.

// New instance of CosmosClient class using a connection string
using CosmosClient client = new(
    accountEndpoint: Environment.GetEnvironmentVariable("COSMOS_ENDPOINT")!,
    tokenCredential: credential
);

Skapa CosmosClient med en anpassad implementering av autentiseringsuppgifter

Om du planerar att distribuera programmet från Azure kan du hämta en OAuth-token med hjälp av andra klasser i Azure.Identity-klientbiblioteket för .NET. Dessa andra klasser härleds också från TokenCredential klassen.

I det här exemplet skapar vi en ClientSecretCredential instans med hjälp av klient- och klientidentifierare, tillsammans med en klienthemlighet.

// Custom credential class for servers and clients outside of Azure
TokenCredential credential = new ClientSecretCredential(
    tenantId: Environment.GetEnvironmentVariable("AAD_TENANT_ID")!,
    clientId: Environment.GetEnvironmentVariable("AAD_CLIENT_ID")!,
    clientSecret: Environment.GetEnvironmentVariable("AAD_CLIENT_SECRET")!,
    options: new TokenCredentialOptions()
);

Du kan hämta klient-ID, klient-ID och klienthemlighet när du registrerar ett program i Microsoft Entra-ID. Mer information om hur du registrerar Microsoft Entra-program finns i Registrera ett program med Microsofts identitetsplattform.

Skapa en ny instans av klassen CosmosClient med COSMOS_ENDPOINT miljövariabeln och TokenCredential-objektet som parametrar.

// New instance of CosmosClient class using a connection string
using CosmosClient client = new(
    accountEndpoint: Environment.GetEnvironmentVariable("COSMOS_ENDPOINT")!,
    tokenCredential: credential
);

Skapa ditt program

När du skapar ditt program interagerar koden främst med fyra typer av resurser:

• API:et för NoSQL-kontot, som är det unika toppnivånamnområdet för dina Azure Cosmos DB-data.

• Databaser som organiserar containrarna i ditt konto.

• Containrar som innehåller en uppsättning enskilda objekt i databasen.

• Objekt som representerar ett JSON-dokument i containern.

Följande diagram visar relationen mellan de här resurserna.

Hierarkiskt diagram som visar ett Azure Cosmos DB-konto högst upp. Kontot har två underordnade databasnoder. En av databasnoderna innehåller två underordnade containernoder. Den andra databasnoden innehåller en enda underordnad containernod. Den enda containernoden har tre underordnade objektnoder.

Varje typ av resurs representeras av en eller flera associerade .NET-klasser. Här är en lista över de vanligaste klasserna:

Klass	Description
CosmosClient	Den här klassen tillhandahåller en logisk representation på klientsidan för Azure Cosmos DB-tjänsten. Klientobjektet används för att konfigurera och köra begäranden mot tjänsten.
Database	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.
Container	Den här klassen är en referens till en container som inte heller finns i tjänsten ännu. Containern verifieras på serversidan när du försöker arbeta med den.

Följande guider visar hur du använder var och en av dessa klasser för att skapa ditt program.

Guide	Description
Skapa en databas	Skapa databaser
Skapa en container	Skapa containrar
Läsa ett objekt	Punktläsning av ett specifikt objekt
Frågeobjekt	Fråga efter flera objekt

Se även

• Paket (NuGet)
• Exempel
• API-referens
• Källkod för bibliotek
• Ge feedback

Nästa steg

Nu när du har anslutit till ett API för NoSQL-konto använder du nästa guide för att skapa och hantera databaser.

Skapa en databas i Azure Cosmos DB för NoSQL med hjälp av .NET