Snabbstart: Azure Cosmos DB för NoSQL-bibliotek för .NET

GÄLLER FÖR: NoSQL

Kom igång med Azure Cosmos DB for NoSQL-klientbiblioteket för .NET för att fråga efter data i dina containrar och utföra vanliga åtgärder på enskilda objekt. Följ de här stegen för att distribuera en minimal lösning till din miljö med hjälp av Azure Developer CLI.

API-referensdokumentation Bibliotek källkodspaket | (NuGet) | Azure Developer CLI |

Förutsättningar

Konfigurera

Distribuera projektets utvecklingscontainer till din miljö. Använd sedan Azure Developer CLI (azd) för att skapa ett Azure Cosmos DB för NoSQL-konto och distribuera ett containerbaserat exempelprogram. Exempelprogrammet använder klientbiblioteket för att hantera, skapa, läsa och fråga efter exempeldata.

1. Öppna en terminal i projektets rotkatalog.

2. Autentisera till Azure Developer CLI med .azd auth login Följ stegen som anges av verktyget för att autentisera till CLI med dina önskade Azure-autentiseringsuppgifter.

   azd auth login
   

3. Använd azd init för att initiera projektet.

   azd init --template cosmos-db-nosql-dotnet-quickstart
   

   Kommentar

   Den här snabbstarten använder GitHub-lagringsplatsen azure-samples/cosmos-db-nosql-dotnet-quickstart . Azure Developer CLI klonar automatiskt det här projektet till datorn om det inte redan finns där.

4. Under initieringen konfigurerar du ett unikt miljönamn.

   Dricks

   Miljönamnet används också som målresursgruppnamn. För den här snabbstarten bör du överväga att använda msdocs-cosmos-db.

5. Distribuera Azure Cosmos DB-kontot med .azd up Bicep-mallarna distribuerar också ett exempelwebbprogram.

   azd up
   

6. Under etableringsprocessen väljer du din prenumeration och önskad plats. Vänta tills etableringsprocessen har slutförts. Processen kan ta ungefär fem minuter.

7. När etableringen av dina Azure-resurser är klar inkluderas en URL till det webbprogram som körs i utdata.

   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.
   

8. Använd URL:en i konsolen för att navigera till webbprogrammet i webbläsaren. Observera utdata från appen som körs.

   

Installera klientbiblioteket

Klientbiblioteket är tillgängligt via NuGet som Microsoft.Azure.Cosmos paket.

1. Öppna en terminal och navigera till /src/web mappen.

   cd ./src/web
   

2. Om det inte redan är installerat installerar du Microsoft.Azure.Cosmos paketet med .dotnet add package

   dotnet add package Microsoft.Azure.Cosmos --version 3.*
   

3. Installera även paketet om det Azure.Identity inte redan är installerat.

   dotnet add package Azure.Identity --version 1.12.*
   

4. Öppna och granska filen src/web/Cosmos.Samples.NoSQL.Quickstart.Web.csproj för att verifiera att Microsoft.Azure.Cosmos båda posterna och Azure.Identity finns.

Objektmodell

Kodexempel

• Autentisera klienten
• Hämta en databas
• Hämta en container
• Skapa ett objekt
• Hämta ett objekt
• Frågeobjekt

Exempelkoden i mallen använder en databas med namnet cosmicworks och containern med namnet products. Containern products innehåller information som namn, kategori, kvantitet, en unik identifierare och en försäljningsflagga för varje produkt. Containern använder egenskapen /category som en logisk partitionsnyckel.

Autentisera klienten

Programbegäranden till de flesta Azure-tjänster måste auktoriseras. Använd typen DefaultAzureCredential som det bästa sättet att implementera en lösenordslös anslutning mellan dina program och Azure Cosmos DB för NoSQL. DefaultAzureCredential stöder flera autentiseringsmetoder och avgör vilken metod som ska användas vid körning.

Det här exemplet skapar en ny instans av klassen och autentiserar CosmosClient med hjälp av en DefaultAzureCredential instans.

DefaultAzureCredential credential = new();

CosmosClient client = new(
    accountEndpoint: "<azure-cosmos-db-nosql-account-endpoint>",
    tokenCredential: new DefaultAzureCredential()
);

Hämta en databas

Använd client.GetDatabase för att hämta den befintliga databasen med namnet cosmicworks.

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

Hämta en container

Hämta den befintliga products containern med .database.GetContainer

Container container = database.GetContainer("products");

Skapa ett objekt

Skapa en C#-posttyp med alla medlemmar som du vill serialisera till JSON. I det här exemplet har typen en unik identifierare och fält för kategori, namn, kvantitet, pris och försäljning.

public record Product(
    string id,
    string category,
    string name,
    int quantity,
    decimal price,
    bool clearance
);

Skapa ett objekt i containern med .container.UpsertItem Den här metoden "upserts" objektet ersätter objektet effektivt om det redan finns.

Product item = new(
    id: "68719518391",
    category: "gear-surf-surfboards",
    name: "Yamba Surfboard",
    quantity: 12,
    price: 850.00m,
    clearance: false
);

ItemResponse<Product> response = await container.UpsertItemAsync<Product>(
    item: item,
    partitionKey: new PartitionKey("gear-surf-surfboards")
);

Läsa ett objekt

Utför en punktläsningsåtgärd med hjälp av både de unika identifierarna (id) och partitionsnyckelfälten. Använd container.ReadItem för att effektivt hämta det specifika objektet.

ItemResponse<Product> response = await container.ReadItemAsync<Product>(
    id: "68719518391",
    partitionKey: new PartitionKey("gear-surf-surfboards")
);

Frågeobjekt

Utför en fråga över flera objekt i en container med hjälp av container.GetItemQueryIterator. Hitta alla objekt i en angiven kategori med den här parameteriserade frågan:

SELECT * FROM products p WHERE p.category = @category

string query = "SELECT * FROM products p WHERE p.category = @category"

var query = new QueryDefinition(query)
  .WithParameter("@category", "gear-surf-surfboards");

using FeedIterator<Product> feed = container.GetItemQueryIterator<Product>(
    queryDefinition: query
);

Parsa de sidnumrerade resultaten av frågan genom att loopa igenom varje sida med resultat med hjälp feed.ReadNextAsyncav . Använd feed.HasMoreResults för att avgöra om det finns några resultat kvar i början av varje loop.

List<Product> items = new();
while (feed.HasMoreResults)
{
    FeedResponse<Product> response = await feed.ReadNextAsync();
    foreach (Product item in response)
    {
        items.Add(item);
    }
}

Rensa resurser

azd down

Relaterat innehåll

• Node.js snabbstart
• Snabbstart för Python
• Snabbstart för Java
• Snabbstart för Go