Tutorial: Erstellen einer .NET-Konsolen-App zum Verwalten von Daten in einem Azure Cosmos DB-SQL-API-KontoTutorial: Build a .NET console app to manage data in Azure Cosmos DB SQL API account

Willkommen zum Tutorial zu den ersten Schritten mit der SQL-API von Azure Cosmos DB.Welcome to the Azure Cosmos DB SQL API get started tutorial. Im Rahmen dieses Tutorials erstellen Sie eine Konsolenanwendung, mit der Azure Cosmos DB-Ressourcen erstellt und abgefragt werden können.After following this tutorial, you'll have a console application that creates and queries Azure Cosmos DB resources.

In diesem Tutorial wird Version 3.0 oder höher des Azure Cosmos DB .NET SDK verwendet.This tutorial uses version 3.0 or later of the Azure Cosmos DB .NET SDK. Sie können mit .NET Framework oder .NET Core arbeiten.You can work with .NET Framework or .NET Core.

In diesem Lernprogramm wird Folgendes behandelt:This tutorial covers:

  • Erstellen eines Azure Cosmos-Kontos und Herstellen der VerbindungCreating and connecting to an Azure Cosmos account
  • Konfigurieren Ihres Projekts in Visual StudioConfiguring your project in Visual Studio
  • Erstellen einer Datenbank und eines ContainersCreating a database and a container
  • Hinzufügen von Elementen zum ContainerAdding items to the container
  • Abfragen des ContainersQuerying the container
  • Durchführen von Erstellungs-, Lese-, Aktualisierungs- und Löschvorgängen (Create, Read, Update, Delete (CRUD)) für das ElementPerforming create, read, update, and delete (CRUD) operations on the item
  • Löschen der DatenbankDeleting the database

Sie haben nicht genügend Zeit?Don't have time? Keine Sorge!Don't worry! Die vollständige Lösung ist auf GitHubverfügbar.The complete solution is available on GitHub. Im Abschnitt Abrufen der vollständigen Projektmappe für das Tutorial finden Sie eine Kurzanleitung.Jump to the Get the complete tutorial solution section for quick instructions.

Lassen Sie uns anfangen.Now let's get started!

VoraussetzungenPrerequisites

Schritt 1: Erstellen eines Azure Cosmos DB-KontosStep 1: Create an Azure Cosmos DB account

Wir erstellen nun ein Azure Cosmos DB-Konto.Let's create an Azure Cosmos DB account. Überspringen Sie diesen Abschnitt, wenn Sie bereits über ein Konto verfügen, das Sie verwenden möchten.If you already have an account you want to use, skip this section. Führen Sie zum Verwenden des Azure Cosmos DB-Emulators die Schritte unter Azure Cosmos DB-Emulator aus, um den Emulator einzurichten.To use the Azure Cosmos DB Emulator, follow the steps at Azure Cosmos DB Emulator to set up the emulator. Fahren Sie anschließend mit Schritt 2: Einrichten Ihres Visual Studio-Projekts fort.Then skip ahead to Step 2: Set up your Visual Studio project.

  1. Wechseln Sie zum Azure-Portal, um ein Azure Cosmos DB-Konto zu erstellen.Go to the Azure portal to create an Azure Cosmos DB account. Suchen Sie nach Azure Cosmos DB, und wählen Sie die Option aus.Search for and select Azure Cosmos DB.

    Die Bereich „Datenbanken“ im Azure-Portal

  2. Wählen Sie Hinzufügen.Select Add.

  3. Geben Sie auf der Seite Azure Cosmos DB-Konto erstellen die grundlegenden Einstellungen für das neue Azure Cosmos-Konto ein.On the Create Azure Cosmos DB Account page, enter the basic settings for the new Azure Cosmos account.

    EinstellungSetting WertValue BESCHREIBUNGDescription
    SubscriptionSubscription AbonnementnameSubscription name Wählen Sie das Azure-Abonnement aus, das Sie für dieses Azure Cosmos-Konto verwenden möchten.Select the Azure subscription that you want to use for this Azure Cosmos account.
    RessourcengruppeResource Group RessourcengruppennameResource group name Wählen Sie eine Ressourcengruppe aus, oder wählen Sie Neu erstellen aus, und geben Sie einen eindeutigen Namen für die Ressourcengruppe ein.Select a resource group, or select Create new, then enter a unique name for the new resource group.
    KontonameAccount Name Ein eindeutiger NameA unique name Geben Sie einen Namen ein, der Ihr Azure Cosmos-Konto identifiziert.Enter a name to identify your Azure Cosmos account. Da documents.azure.com an den Namen angefügt wird, die Sie für die URI-Erstellung angeben, muss der Name eindeutig sein.Because documents.azure.com is appended to the name that you provide to create your URI, use a unique name.

    Der Name darf nur Kleinbuchstaben, Zahlen und den Bindestrich (-) enthalten.The name can only contain lowercase letters, numbers, and the hyphen (-) character. Sie muss zwischen drei und 31 Zeichen lang sein.It must be between 3-31 characters in length.
    APIAPI Der Typ des zu erstellenden KontosThe type of account to create Wählen Sie Core (SQL) aus, um eine Dokumentdatenbank und eine Abfrage mit SQL-Syntax zu erstellen.Select Core (SQL) to create a document database and query by using SQL syntax.

    Die API bestimmt den Typ des zu erstellenden Kontos.The API determines the type of account to create. Azure Cosmos DB stellt fünf APIs bereit: Core (SQL) und MongoDB für Dokumentdaten, Gremlin für Diagrammdaten sowie Azure Table und Cassandra.Azure Cosmos DB provides five APIs: Core (SQL) and MongoDB for document data, Gremlin for graph data, Azure Table, and Cassandra. Derzeit müssen Sie ein separates Konto für jede API erstellen.Currently, you must create a separate account for each API.

    Weitere Informationen zur SQL-APILearn more about the SQL API.
    Tarifspezifischen Rabatt für den Free-Tarif anwendenApply Free Tier Discount „Anwenden“ oder „Nicht anwenden“Apply or Do not apply Mit dem Azure Cosmos DB-Tarif „Free“ erhalten Sie die ersten 400 RUs/Sek. sowie 5 GB Speicher kostenlos in einem Konto.With Azure Cosmos DB free tier, you will get the first 400 RU/s and 5 GB of storage for free in an account. Weitere Informationen zum Tarif „Free“Learn more about free tier.
    PositionLocation Die Region, die Ihren Benutzern am nächsten liegtThe region closest to your users Wählen Sie einen geografischen Standort aus, an dem Ihr Azure Cosmos DB-Konto gehostet werden soll.Select a geographic location to host your Azure Cosmos DB account. Verwenden Sie den Standort, der Ihren Benutzern am nächsten ist, damit sie möglichst schnell auf die Daten zugreifen können.Use the location that is closest to your users to give them the fastest access to the data.
    KontotypAccount Type „Produktionsbezogen“ oder „Nicht produktionsbezogen“Production or Non-Production Wählen Sie Produktionsbezogen aus, wenn das Konto für eine Produktionsworkload verwendet wird.Select Production if the account will be used for a production workload. Wählen Sie Nicht produktionsbezogen aus, wenn das Konto nicht für die Produktion, sondern beispielsweise für Entwicklung, Tests, Qualitätssicherung oder Staging verwendet wird.Select Non-Production if the account will be used for non-production, e.g. development, testing, QA, or staging. Hierbei handelt es sich um eine Azure-Ressourcentageinstellung, die das Portal optimiert, aber keine Auswirkungen auf das zugrunde liegende Azure Cosmos DB-Konto hat.This is an Azure resource tag setting that tunes the Portal experience but does not affect the underlying Azure Cosmos DB account. Sie können diesen Wert jederzeit ändern.You can change this value anytime.

Hinweis

Sie können pro Azure-Abonnement maximal ein Azure Cosmos DB-Konto im Free-Tarif einrichten und müssen sich beim Erstellen des Kontos anmelden.You can have up to one free tier Azure Cosmos DB account per Azure subscription and must opt-in when creating the account. Wird die Option zum Anwenden des tarifspezifischen Rabatts für den Free-Tarif nicht angezeigt, bedeutet dies, dass bereits ein anderes Konto im Abonnement mit dem Free-Tarif aktiviert wurde.If you do not see the option to apply the free tier discount, this means another account in the subscription has already been enabled with free tier.

Die Seite „Neues Konto“ für Azure Cosmos DB

  1. Klicken Sie auf Überprüfen + erstellen.Select Review + create. Sie können die Abschnitte Netzwerk und Tags überspringen.You can skip the Network and Tags sections.

  2. Überprüfen Sie die Kontoeinstellungen, und wählen Sie anschließend Erstellen aus.Review the account settings, and then select Create. Die Erstellung des Kontos dauert einige Minuten.It takes a few minutes to create the account. Warten Sie, bis auf der Portalseite Ihre Bereitstellung wurde abgeschlossen. angezeigt wird.Wait for the portal page to display Your deployment is complete.

    Der Bereich „Benachrichtigungen“ im Azure-Portal

  3. Wählen Sie Zu Ressource wechseln aus, um zur Seite des Azure Cosmos DB-Kontos zu wechseln.Select Go to resource to go to the Azure Cosmos DB account page.

    Seite des Azure Cosmos DB-Kontos

Schritt 2: Einrichten Ihres Visual Studio-ProjektsStep 2: Set up your Visual Studio project

  1. Öffnen Sie Visual Studio, und wählen Sie Neues Projekt erstellen aus.Open Visual Studio and select Create a new project.

  2. Wählen Sie unter Neues Projekt erstellen die Option Konsolen-App (.NET Framework) für C# und dann Weiter aus.In Create a new project, choose Console App (.NET Framework) for C#, then select Next.

  3. Geben Sie Ihrem Projekt den Namen CosmosGettingStartedTutorial, und wählen Sie anschließend Erstellen aus.Name your project CosmosGettingStartedTutorial, and then select Create.

    Konfigurieren des Projekts

  4. Klicken Sie im Projektmappen-Explorer mit der rechten Maustaste auf die neue Konsolenanwendung, die sich unter Ihrer Visual Studio-Projektmappe befindet, und wählen Sie NuGet-Pakete verwalten aus.In the Solution Explorer, right-click your new console application, which is under your Visual Studio solution, and select Manage NuGet Packages.

  5. Wählen Sie im NuGet-Paket-Manager die Option Durchsuchen aus, und suchen Sie dann nach Microsoft.Azure.Cosmos.In the NuGet Package Manager, select Browse and search for Microsoft.Azure.Cosmos. Wählen Sie Microsoft.Azure.Cosmos und dann die Option Installieren aus.Choose Microsoft.Azure.Cosmos and select Install.

    Installieren von NuGet für Azure Cosmos DB-Client-SDK

    Die Paket-ID für die SQL-API-Clientbibliothek von Azure Cosmos DB lautet Microsoft Azure Cosmos DB Client Library.The package ID for the Azure Cosmos DB SQL API Client Library is Microsoft Azure Cosmos DB Client Library.

Prima.Great! Damit ist die Einrichtung abgeschlossen und wir können mit dem Schreiben von Code beginnen.Now that we finished the setup, let's start writing some code. Informationen zum abgeschlossenen Projekt dieses Tutorials finden Sie unter Developing a .NET console app using Azure Cosmos DB (Entwickeln einer .NET-Konsolen-App mit Azure Cosmos DB).For the completed project of this tutorial, see Developing a .NET console app using Azure Cosmos DB.

Schritt 3: Herstellen einer Verbindung mit einem Azure Cosmos DB-KontoStep 3: Connect to an Azure Cosmos DB account

  1. Ersetzen Sie in der Datei Program.cs die Verweise am Anfang der C#-Anwendung durch die folgenden Verweise:Replace the references at the beginning of your C# application in the Program.cs file with these references:

    using System;
    using System.Threading.Tasks;
    using System.Configuration;
    using System.Collections.Generic;
    using System.Net;
    using Microsoft.Azure.Cosmos;
    
  2. Fügen Sie in Ihrer Program-Klasse die folgenden Konstanten und Variablen hinzu.Add these constants and variables into your Program class.

    public class Program
    {
        // ADD THIS PART TO YOUR CODE
    
        // The Azure Cosmos DB endpoint for running this sample.
        private static readonly string EndpointUri = "<your endpoint here>";
        // The primary key for the Azure Cosmos account.
        private static readonly string PrimaryKey = "<your primary key>";
    
        // The Cosmos client instance
        private CosmosClient cosmosClient;
    
        // The database we will create
        private Database database;
    
        // The container we will create.
        private Container container;
    
        // The name of the database and container we will create
        private string databaseId = "FamilyDatabase";
        private string containerId = "FamilyContainer";
    }
    

    Hinweis

    Falls Sie mit der vorherigen Version des .NET SDK vertraut sind, kennen Sie unter Umständen bereits die Begriffe Sammlung und Dokument.If you're familiar with the previous version of the .NET SDK, you may be familiar with the terms collection and document. Azure Cosmos DB unterstützt mehrere API-Modelle. Daher werden in Version 3.0 des .NET SDK die generischen Begriffe Container und Element verwendet.Because Azure Cosmos DB supports multiple API models, version 3.0 of the .NET SDK uses the generic terms container and item. Ein Container kann eine Sammlung, ein Graph oder eine Tabelle sein.A container can be a collection, graph, or table. Ein Element kann ein Dokument, ein Edge/Vertex oder eine Zeile sein und stellt den Inhalt eines Containers dar.An item can be a document, edge/vertex, or row, and is the content inside a container. Weitere Informationen finden Sie unter Arbeiten mit Datenbanken, Containern und Elementen in Azure Cosmos DB.For more information, see Work with databases, containers, and items in Azure Cosmos DB.

  3. Öffnen Sie das Azure-Portal.Open the Azure portal. Suchen Sie nach Ihrem Azure Cosmos DB-Konto, und wählen Sie anschließend die Option Schlüssel aus.Find your Azure Cosmos DB account, and then select Keys.

    Abrufen der Azure Cosmos DB-Schlüssel über das Azure-Portal

  4. Ersetzen Sie in Program.cs die Zeichenfolge <your endpoint URL> durch den Wert von URI.In Program.cs, replace <your endpoint URL> with the value of URI. Ersetzen Sie <your primary key> durch den Wert von PRIMARY KEY (PRIMÄRSCHLÜSSEL).Replace <your primary key> with the value of PRIMARY KEY.

  5. Fügen Sie unterhalb der Main-Methode eine neue asynchrone Aufgabe mit der Bezeichnung GetStartedDemoAsync hinzu. Sie dient zum Instanziieren des neuen CosmosClient-Elements.Below the Main method, add a new asynchronous task called GetStartedDemoAsync, which instantiates our new CosmosClient.

    public static async Task Main(string[] args)
    {
    }
    
    // ADD THIS PART TO YOUR CODE
    /*
        Entry point to call methods that operate on Azure Cosmos DB resources in this sample
    */
    public async Task GetStartedDemoAsync()
    {
        // Create a new instance of the Cosmos Client
        this.cosmosClient = new CosmosClient(EndpointUri, PrimaryKey);
    }
    

    GetStartedDemoAsync wird als Einstiegspunkt verwendet, der Methoden für Azure Cosmos DB-Ressourcen aufruft.We use GetStartedDemoAsync as the entry point that calls methods that operate on Azure Cosmos DB resources.

  6. Fügen Sie den folgenden Code hinzu, um die asynchrone Aufgabe GetStartedDemoAsync über die Main-Methode auszuführen.Add the following code to run the GetStartedDemoAsync asynchronous task from your Main method. Die Main-Methode fängt Ausnahmen ab und gibt sie in der Konsole aus.The Main method catches exceptions and writes them to the console.

    public static async Task Main(string[] args)
    {
        try
        {
            Console.WriteLine("Beginning operations...\n");
            Program p = new Program();
            await p.GetStartedDemoAsync();
    
        }
        catch (CosmosException de)
        {
            Exception baseException = de.GetBaseException();
            Console.WriteLine("{0} error occurred: {1}", de.StatusCode, de);
        }
        catch (Exception e)
        {
            Console.WriteLine("Error: {0}", e);
        }
        finally
        {
            Console.WriteLine("End of demo, press any key to exit.");
            Console.ReadKey();
        }
    }
    
  7. Wählen Sie F5 aus, um die Anwendung auszuführen.Select F5 to run your application.

    Die Konsole zeigt die folgende Meldung an: End of demo, press any key to exit. (Ende der Demo. Zum Beenden beliebige Taste drücken.).The console displays the message: End of demo, press any key to exit. Mit dieser Meldung wird bestätigt, dass Ihre Anwendung eine Verbindung mit Azure Cosmos DB hergestellt hat.This message confirms that your application made a connection to Azure Cosmos DB. Das Konsolenfenster kann nun geschlossen werden.You can then close the console window.

Glückwunsch!Congratulations! Sie haben erfolgreich eine Verbindung mit einem Azure Cosmos DB-Konto hergestellt.You've successfully connected to an Azure Cosmos DB account.

Schritt 4: Erstellen einer DatenbankStep 4: Create a database

Eine Datenbank ist ein logischer Container für Elemente, die auf Container aufgeteilt sind.A database is the logical container of items partitioned across containers. Entweder mit der CreateDatabaseIfNotExistsAsync- oder der CreateDatabaseAsync-Methode der CosmosClient-Klasse kann eine Datenbank erstellt werden.Either the CreateDatabaseIfNotExistsAsync or CreateDatabaseAsync method of the CosmosClient class can create a database.

  1. Kopieren Sie die CreateDatabaseAsync-Methode, und fügen Sie sie unterhalb Ihrer GetStartedDemoAsync-Methode ein.Copy and paste the CreateDatabaseAsync method below your GetStartedDemoAsync method.

    /// <summary>
    /// Create the database if it does not exist
    /// </summary>
    private async Task CreateDatabaseAsync()
    {
        // Create a new database
        this.database = await this.cosmosClient.CreateDatabaseIfNotExistsAsync(databaseId);
        Console.WriteLine("Created Database: {0}\n", this.database.Id);
    }
    

    Falls noch nicht vorhanden, wird mit CreateDatabaseAsync eine neue Datenbank mit der ID FamilyDatabase erstellt, die die ID aus dem Feld databaseId enthält.CreateDatabaseAsync creates a new database with ID FamilyDatabase if it doesn't already exist, that has the ID specified from the databaseId field.

  2. Kopieren Sie den Code, und fügen Sie ihn unterhalb der Stelle ein, an der Sie CosmosClient zum Aufrufen der eben hinzugefügten CreateDatabaseAsync-Methode instanziieren.Copy and paste the code below where you instantiate the CosmosClient to call the CreateDatabaseAsync method you just added.

    public async Task GetStartedDemoAsync()
    {
        // Create a new instance of the Cosmos Client
        this.cosmosClient = new CosmosClient(EndpointUri, PrimaryKey);
    
        //ADD THIS PART TO YOUR CODE
        await this.CreateDatabaseAsync();
    }
    

    Die Datei Program.cs sollte nun wie der unten angegebene Code mit eingefügtem Endpunkt und Primärschlüssel aussehen.Your Program.cs should now look like this, with your endpoint and primary key filled in.

    using System;
    using System.Threading.Tasks;
    using System.Configuration;
    using System.Collections.Generic;
    using System.Net;
    using Microsoft.Azure.Cosmos;
    
    namespace CosmosGettingStartedTutorial
    {
        class Program
        {
            // The Azure Cosmos DB endpoint for running this sample.
            private static readonly string EndpointUri = "<your endpoint here>";
            // The primary key for the Azure Cosmos account.
            private static readonly string PrimaryKey = "<your primary key>";
    
            // The Cosmos client instance
            private CosmosClient cosmosClient;
    
            // The database we will create
            private Database database;
    
            // The container we will create.
            private Container container;
    
            // The name of the database and container we will create
            private string databaseId = "FamilyDatabase";
            private string containerId = "FamilyContainer";
    
            public static async Task Main(string[] args)
            {
                try
                {
                    Console.WriteLine("Beginning operations...");
                    Program p = new Program();
                    await p.GetStartedDemoAsync();
                }
                catch (CosmosException de)
                {
                    Exception baseException = de.GetBaseException();
                    Console.WriteLine("{0} error occurred: {1}\n", de.StatusCode, de);
                }
                catch (Exception e)
                {
                    Console.WriteLine("Error: {0}\n", e);
                }
                finally
                {
                    Console.WriteLine("End of demo, press any key to exit.");
                    Console.ReadKey();
                }
            }
    
            /// <summary>
            /// Entry point to call methods that operate on Azure Cosmos DB resources in this sample
            /// </summary>
            public async Task GetStartedDemoAsync()
            {
                // Create a new instance of the Cosmos Client
                this.cosmosClient = new CosmosClient(EndpointUri, PrimaryKey);
                await this.CreateDatabaseAsync();
            }
    
            /// <summary>
            /// Create the database if it does not exist
            /// </summary>
            private async Task CreateDatabaseAsync()
            {
                // Create a new database
                this.database = await this.cosmosClient.CreateDatabaseIfNotExistsAsync(databaseId);
                Console.WriteLine("Created Database: {0}\n", this.database.Id);
            }
        }
    }
    
  3. Wählen Sie F5 aus, um die Anwendung auszuführen.Select F5 to run your application.

    Hinweis

    Wird der Fehler „503 Dienst nicht verfügbar“ angezeigt, werden die erforderlichen Ports für den direkten Konnektivitätsmodus unter Umständen durch eine Firewall blockiert.If you get a "503 service unavailable exception" error, it's possible that the required ports for direct connectivity mode are blocked by a firewall. Öffnen Sie zum Beheben des Problems entweder die erforderlichen Ports, oder verwenden Sie die Gatewaymoduskonnektivität wie im folgenden Code gezeigt:To fix this issue, either open the required ports or use the gateway mode connectivity as shown in the following code:

      // Create a new instance of the Cosmos Client in Gateway mode
      this.cosmosClient = new CosmosClient(EndpointUri, PrimaryKey, new CosmosClientOptions()
             {
                 ConnectionMode = ConnectionMode.Gateway
             });
    

Glückwunsch!Congratulations! Sie haben erfolgreich eine Azure Cosmos-Datenbank erstellt.You've successfully created an Azure Cosmos database.

Schritt 5: Erstellen eines ContainersStep 5: Create a container

Warnung

Mit der CreateContainerIfNotExistsAsync-Methode wird ein neuer Container erstellt, und dies wirkt sich auf die Kosten aus.The method CreateContainerIfNotExistsAsync creates a new container, which has pricing implications. Weitere Informationen finden Sie auf unserer Preisseite.For more details, please visit our pricing page.

Ein Container kann mit der Funktion CreateContainerIfNotExistsAsync oder CreateContainerAsync in der CosmosDatabase-Klasse erstellt werden.A container can be created by using either the CreateContainerIfNotExistsAsync or CreateContainerAsync method in the CosmosDatabase class. Ein Container besteht aus Elementen (JSON-Dokumente im Falle der SQL-API) und zugeordneter serverseitiger Anwendungslogik in JavaScript. Dazu gehören beispielsweise gespeicherte Prozeduren, benutzerdefinierte Funktionen und Auslöser.A container consists of items (JSON documents if SQL API) and associated server-side application logic in JavaScript, for example, stored procedures, user-defined functions, and triggers.

  1. Kopieren Sie die CreateContainerAsync-Methode, und fügen Sie sie unterhalb Ihrer CreateDatabaseAsync-Methode ein.Copy and paste the CreateContainerAsync method below your CreateDatabaseAsync method. Mit CreateContainerAsync wird ein neuer Container mit der ID FamilyContainer erstellt, falls er nicht bereits vorhanden ist. Hierfür wird die ID verwendet, die im Feld containerId angegeben ist (partitioniert mit der LastName-Eigenschaft).CreateContainerAsync creates a new container with the ID FamilyContainer if it doesn't already exist, by using the ID specified from the containerId field partitioned by LastName property.

    /// <summary>
    /// Create the container if it does not exist. 
    /// Specifiy "/LastName" as the partition key since we're storing family information, to ensure good distribution of requests and storage.
    /// </summary>
    /// <returns></returns>
    private async Task CreateContainerAsync()
    {
        // Create a new container
        this.container = await this.database.CreateContainerIfNotExistsAsync(containerId, "/LastName");
        Console.WriteLine("Created Container: {0}\n", this.container.Id);
    }
    
  2. Kopieren Sie den Code, und fügen Sie ihn unterhalb der Stelle ein, an der Sie CosmosClient zum Aufrufen der eben hinzugefügten CreateContainer-Methode instanziiert haben.Copy and paste the code below where you instantiated the CosmosClient to call the CreateContainer method you just added.

    public async Task GetStartedDemoAsync()
    {
        // Create a new instance of the Cosmos Client
        this.cosmosClient = new CosmosClient(EndpointUri, PrimaryKey);
        await this.CreateDatabaseAsync();
    
        //ADD THIS PART TO YOUR CODE
        await this.CreateContainerAsync();
    }
    
  3. Wählen Sie F5 aus, um die Anwendung auszuführen.Select F5 to run your application.

Glückwunsch!Congratulations! Sie haben erfolgreich einen Azure Cosmos-Container erstellt.You've successfully created an Azure Cosmos container.

Schritt 6: Hinzufügen von Elementen zum ContainerStep 6: Add items to the container

Mit der CreateItemAsync-Methode der CosmosContainer-Klasse kann ein Element erstellt werden.The CreateItemAsync method of the CosmosContainer class can create an item. Bei Verwendung der SQL-API werden Elemente als Dokumente projiziert. Dabei handelt es sich um beliebigen benutzerdefinierten JSON-Inhalt.When using the SQL API, items are projected as documents, which are user-defined arbitrary JSON content. Sie können jetzt ein Element in Ihren Azure Cosmos-Container einfügen.You can now insert an item into your Azure Cosmos container.

Zunächst erstellen wir eine Family-Klasse, mit der in diesem Beispiel in Azure Cosmos DB gespeicherte Objekte dargestellt werden.First, let's create a Family class that represents objects stored within Azure Cosmos DB in this sample. Darüber hinaus erstellen wir die Unterklassen Parent, Child, Pet und Address, die in Family genutzt werden.We'll also create Parent, Child, Pet, Address subclasses that are used within Family. Das Element muss über eine Id-Eigenschaft verfügen, die in JSON-Code als id serialisiert ist.The item must have an Id property serialized as id in JSON.

  1. Drücken Sie STRG+UMSCHALT+A, um die Option Neues Element hinzufügen zu öffnen.Select Ctrl+Shift+A to open Add New Item. Fügen Sie Ihrem Projekt eine neue Family.cs-Klasse hinzu.Add a new class Family.cs to your project.

    Screenshot: Hinzufügen der neuen Klasse „Family.cs“ zum Projekt

  2. Kopieren Sie die Klassen Family, Parent, Child, Pet und Address, und fügen Sie sie in Family.cs ein.Copy and paste the Family, Parent, Child, Pet, and Address class into Family.cs.

    using Newtonsoft.Json;
    
    namespace CosmosGettingStartedTutorial
    {
        public class Family
        {
            [JsonProperty(PropertyName = "id")]
            public string Id { get; set; }
            public string LastName { get; set; }
            public Parent[] Parents { get; set; }
            public Child[] Children { get; set; }
            public Address Address { get; set; }
            public bool IsRegistered { get; set; }
            public override string ToString()
            {
                return JsonConvert.SerializeObject(this);
            }
        }
    
        public class Parent
        {
            public string FamilyName { get; set; }
            public string FirstName { get; set; }
        }
    
        public class Child
        {
            public string FamilyName { get; set; }
            public string FirstName { get; set; }
            public string Gender { get; set; }
            public int Grade { get; set; }
            public Pet[] Pets { get; set; }
        }
    
        public class Pet
        {
            public string GivenName { get; set; }
        }
    
        public class Address
        {
            public string State { get; set; }
            public string County { get; set; }
            public string City { get; set; }
        }
    }
    
  3. Wechseln Sie zurück zur Datei Program.cs, und fügen Sie nach Ihrer CreateContainerAsync-Methode die AddItemsToContainerAsync-Methode hinzu.Back in Program.cs, add the AddItemsToContainerAsync method after your CreateContainerAsync method.

    /// <summary>
    /// Add Family items to the container
    /// </summary>
    private async Task AddItemsToContainerAsync()
    {
        // Create a family object for the Andersen family
        Family andersenFamily = new Family
        {
            Id = "Andersen.1",
            LastName = "Andersen",
            Parents = new Parent[]
            {
                new Parent { FirstName = "Thomas" },
                new Parent { FirstName = "Mary Kay" }
            },
            Children = new Child[]
            {
                new Child
                {
                    FirstName = "Henriette Thaulow",
                    Gender = "female",
                    Grade = 5,
                    Pets = new Pet[]
                    {
                        new Pet { GivenName = "Fluffy" }
                    }
                }
            },
            Address = new Address { State = "WA", County = "King", City = "Seattle" },
            IsRegistered = false
        };
    
        try
        {
            // Read the item to see if it exists.  
            ItemResponse<Family> andersenFamilyResponse = await this.container.ReadItemAsync<Family>(andersenFamily.Id, new PartitionKey(andersenFamily.LastName));
            Console.WriteLine("Item in database with id: {0} already exists\n", andersenFamilyResponse.Resource.Id);
        }
        catch(CosmosException ex) when (ex.StatusCode == HttpStatusCode.NotFound)
        {
            // Create an item in the container representing the Andersen family. Note we provide the value of the partition key for this item, which is "Andersen"
            ItemResponse<Family> andersenFamilyResponse = await this.container.CreateItemAsync<Family>(andersenFamily, new PartitionKey(andersenFamily.LastName));
    
            // Note that after creating the item, we can access the body of the item with the Resource property off the ItemResponse. We can also access the RequestCharge property to see the amount of RUs consumed on this request.
            Console.WriteLine("Created item in database with id: {0} Operation consumed {1} RUs.\n", andersenFamilyResponse.Resource.Id, andersenFamilyResponse.RequestCharge);
        }
    
        // Create a family object for the Wakefield family
        Family wakefieldFamily = new Family
        {
            Id = "Wakefield.7",
            LastName = "Wakefield",
            Parents = new Parent[]
            {
                new Parent { FamilyName = "Wakefield", FirstName = "Robin" },
                new Parent { FamilyName = "Miller", FirstName = "Ben" }
            },
            Children = new Child[]
            {
                new Child
                {
                    FamilyName = "Merriam",
                    FirstName = "Jesse",
                    Gender = "female",
                    Grade = 8,
                    Pets = new Pet[]
                    {
                        new Pet { GivenName = "Goofy" },
                        new Pet { GivenName = "Shadow" }
                    }
                },
                new Child
                {
                    FamilyName = "Miller",
                    FirstName = "Lisa",
                    Gender = "female",
                    Grade = 1
                }
            },
            Address = new Address { State = "NY", County = "Manhattan", City = "NY" },
            IsRegistered = true
        };
    
        try
        {
            // Read the item to see if it exists
            ItemResponse<Family> wakefieldFamilyResponse = await this.container.ReadItemAsync<Family>(wakefieldFamily.Id, new PartitionKey(wakefieldFamily.LastName));
            Console.WriteLine("Item in database with id: {0} already exists\n", wakefieldFamilyResponse.Resource.Id);
        }
        catch(CosmosException ex) when (ex.StatusCode == HttpStatusCode.NotFound)
        {
            // Create an item in the container representing the Wakefield family. Note we provide the value of the partition key for this item, which is "Wakefield"
            ItemResponse<Family> wakefieldFamilyResponse = await this.container.CreateItemAsync<Family>(wakefieldFamily, new PartitionKey(wakefieldFamily.LastName));
    
            // Note that after creating the item, we can access the body of the item with the Resource property off the ItemResponse. We can also access the RequestCharge property to see the amount of RUs consumed on this request.
            Console.WriteLine("Created item in database with id: {0} Operation consumed {1} RUs.\n", wakefieldFamilyResponse.Resource.Id, wakefieldFamilyResponse.RequestCharge);
        }
    }
    

    Mit dem Code wird sichergestellt, dass noch kein Element mit der gleichen ID vorhanden ist.The code checks to make sure an item with the same ID doesn't already exist. Sie fügen zwei Elemente ein: eines für die Familie Andersen und eines für die Familie Wakefield.We'll insert two items, one each for the Andersen Family and the Wakefield Family.

  4. Fügen Sie in der GetStartedDemoAsync Methode einen Aufruf für AddItemsToContainerAsync hinzu.Add a call to AddItemsToContainerAsync in the GetStartedDemoAsync method.

    public async Task GetStartedDemoAsync()
    {
        // Create a new instance of the Cosmos Client
        this.cosmosClient = new CosmosClient(EndpointUri, PrimaryKey);
        await this.CreateDatabaseAsync();
        await this.CreateContainerAsync();
    
        //ADD THIS PART TO YOUR CODE
        await this.AddItemsToContainerAsync();
    }
    
  5. Wählen Sie F5 aus, um die Anwendung auszuführen.Select F5 to run your application.

Glückwunsch!Congratulations! Sie haben erfolgreich zwei Azure Cosmos-Elemente erstellt.You've successfully created two Azure Cosmos items.

Schritt 7: Abfragen von Azure Cosmos DB-RessourcenStep 7: Query Azure Cosmos DB resources

Azure Cosmos DB unterstützt umfassende Abfragen der in jedem Container gespeicherten JSON-Dokumente.Azure Cosmos DB supports rich queries against JSON documents stored in each container. Weitere Informationen finden Sie unter Erste Schritte mit SQL-Abfragen.For more information, see Getting started with SQL queries. Der folgende Beispielcode zeigt, wie Sie eine Abfrage für die im vorherigen Schritt eingefügten Elemente ausführen.The following sample code shows how to run a query against the items we inserted in the previous step.

  1. Kopieren Sie die QueryItemsAsync-Methode, und fügen Sie sie nach Ihrer AddItemsToContainerAsync-Methode ein.Copy and paste the QueryItemsAsync method after your AddItemsToContainerAsync method.

    /// <summary>
    /// Run a query (using Azure Cosmos DB SQL syntax) against the container
    /// </summary>
    private async Task QueryItemsAsync()
    {
        var sqlQueryText = "SELECT * FROM c WHERE c.LastName = 'Andersen'";
    
        Console.WriteLine("Running query: {0}\n", sqlQueryText);
    
        QueryDefinition queryDefinition = new QueryDefinition(sqlQueryText);
        FeedIterator<Family> queryResultSetIterator = this.container.GetItemQueryIterator<Family>(queryDefinition);
    
        List<Family> families = new List<Family>();
    
        while (queryResultSetIterator.HasMoreResults)
        {
            FeedResponse<Family> currentResultSet = await queryResultSetIterator.ReadNextAsync();
            foreach (Family family in currentResultSet)
            {
                families.Add(family);
                Console.WriteLine("\tRead {0}\n", family);
            }
        }
    }
    
  2. Fügen Sie in der GetStartedDemoAsync Methode einen Aufruf für QueryItemsAsync hinzu.Add a call to QueryItemsAsync in the GetStartedDemoAsync method.

    public async Task GetStartedDemoAsync()
    {
        // Create a new instance of the Cosmos Client
        this.cosmosClient = new CosmosClient(EndpointUri, PrimaryKey);
        await this.CreateDatabaseAsync();
        await this.CreateContainerAsync();
        await this.AddItemsToContainerAsync();
    
        //ADD THIS PART TO YOUR CODE
        await this.QueryItemsAsync();
    }
    
  3. Wählen Sie F5 aus, um die Anwendung auszuführen.Select F5 to run your application.

Glückwunsch!Congratulations! Sie haben erfolgreich einen Azure Cosmos-Container abgefragt.You've successfully queried an Azure Cosmos container.

Schritt 8: Ersetzen eines JSON-ElementsStep 8: Replace a JSON item

Sie aktualisieren nun ein Element in Azure Cosmos DB.Now, we'll update an item in Azure Cosmos DB. Sie ändern die IsRegistered-Eigenschaft des Family-Elements und des Grade-Elements von einem der Kinder.We'll change the IsRegistered property of the Family and the Grade of one of the children.

  1. Kopieren Sie die ReplaceFamilyItemAsync-Methode, und fügen Sie sie nach Ihrer QueryItemsAsync-Methode ein.Copy and paste the ReplaceFamilyItemAsync method after your QueryItemsAsync method.

    /// <summary>
    /// Replace an item in the container
    /// </summary>
    private async Task ReplaceFamilyItemAsync()
    {
        ItemResponse<Family> wakefieldFamilyResponse = await this.container.ReadItemAsync<Family>("Wakefield.7", new PartitionKey("Wakefield"));
        var itemBody = wakefieldFamilyResponse.Resource;
        
        // update registration status from false to true
        itemBody.IsRegistered = true;
        // update grade of child
        itemBody.Children[0].Grade = 6;
    
        // replace the item with the updated content
        wakefieldFamilyResponse = await this.container.ReplaceItemAsync<Family>(itemBody, itemBody.Id, new PartitionKey(itemBody.LastName));
        Console.WriteLine("Updated Family [{0},{1}].\n \tBody is now: {2}\n", itemBody.LastName, itemBody.Id, wakefieldFamilyResponse.Resource);
    }
    
  2. Fügen Sie in der GetStartedDemoAsync Methode einen Aufruf für ReplaceFamilyItemAsync hinzu.Add a call to ReplaceFamilyItemAsync in the GetStartedDemoAsync method.

    public async Task GetStartedDemoAsync()
    {
        // Create a new instance of the Cosmos Client
        this.cosmosClient = new CosmosClient(EndpointUri, PrimaryKey);
        await this.CreateDatabaseAsync();
        await this.CreateContainerAsync();
        await this.AddItemsToContainerAsync();
        await this.QueryItemsAsync();
    
        //ADD THIS PART TO YOUR CODE
        await this.ReplaceFamilyItemAsync();
    }
    
  3. Wählen Sie F5 aus, um die Anwendung auszuführen.Select F5 to run your application.

Glückwunsch!Congratulations! Sie haben erfolgreich ein Azure Cosmos-Element ersetzt.You've successfully replaced an Azure Cosmos item.

Schritt 9: Delete item (Element löschen)Step 9: Delete item

Als Nächstes löschen Sie ein Element in Azure Cosmos DB.Now, we'll delete an item in Azure Cosmos DB.

  1. Kopieren Sie die DeleteFamilyItemAsync-Methode, und fügen Sie sie nach Ihrer ReplaceFamilyItemAsync-Methode ein.Copy and paste the DeleteFamilyItemAsync method after your ReplaceFamilyItemAsync method.

    /// <summary>
    /// Delete an item in the container
    /// </summary>
    private async Task DeleteFamilyItemAsync()
    {
        var partitionKeyValue = "Wakefield";
        var familyId = "Wakefield.7";
    
        // Delete an item. Note we must provide the partition key value and id of the item to delete
        ItemResponse<Family> wakefieldFamilyResponse = await this.container.DeleteItemAsync<Family>(familyId,new PartitionKey(partitionKeyValue));
        Console.WriteLine("Deleted Family [{0},{1}]\n", partitionKeyValue, familyId);
    }
    
  2. Fügen Sie in der GetStartedDemoAsync Methode einen Aufruf für DeleteFamilyItemAsync hinzu.Add a call to DeleteFamilyItemAsync in the GetStartedDemoAsync method.

    public async Task GetStartedDemoAsync()
    {
        // Create a new instance of the Cosmos Client
        this.cosmosClient = new CosmosClient(EndpointUri, PrimaryKey);
        await this.CreateDatabaseAsync();
        await this.CreateContainerAsync();
        await this.AddItemsToContainerAsync();
        await this.QueryItemsAsync();
        await this.ReplaceFamilyItemAsync();
    
        //ADD THIS PART TO YOUR CODE
        await this.DeleteFamilyItemAsync();
    }
    
  3. Wählen Sie F5 aus, um die Anwendung auszuführen.Select F5 to run your application.

Glückwunsch!Congratulations! Sie haben erfolgreich ein Azure Cosmos-Element gelöscht.You've successfully deleted an Azure Cosmos item.

Schritt 10: Löschen der DatenbankStep 10: Delete the database

Im nächsten Schritt löschen Sie die Datenbank.Now we'll delete our database. Wenn Sie die erstellte Datenbank löschen, werden auch alle untergeordneten Ressourcen gelöscht.Deleting the created database removes the database and all children resources. Zu diesen Ressourcen zählen Container, Elemente sowie alle gespeicherten Prozeduren, benutzerdefinierten Funktionen und Trigger.The resources include containers, items, and any stored procedures, user-defined functions, and triggers. Außerdem löschen Sie die CosmosClient-Instanz.We also dispose of the CosmosClient instance.

  1. Kopieren Sie die DeleteDatabaseAndCleanupAsync-Methode, und fügen Sie sie nach Ihrer DeleteFamilyItemAsync-Methode ein.Copy and paste the DeleteDatabaseAndCleanupAsync method after your DeleteFamilyItemAsync method.

    /// <summary>
    /// Delete the database and dispose of the Cosmos Client instance
    /// </summary>
    private async Task DeleteDatabaseAndCleanupAsync()
    {
        DatabaseResponse databaseResourceResponse = await this.database.DeleteAsync();
        // Also valid: await this.cosmosClient.Databases["FamilyDatabase"].DeleteAsync();
    
        Console.WriteLine("Deleted Database: {0}\n", this.databaseId);
    
        //Dispose of CosmosClient
        this.cosmosClient.Dispose();
    }
    
  2. Fügen Sie in der GetStartedDemoAsync Methode einen Aufruf für DeleteDatabaseAndCleanupAsync hinzu.Add a call to DeleteDatabaseAndCleanupAsync in the GetStartedDemoAsync method.

    /// <summary>
    /// Entry point to call methods that operate on Azure Cosmos DB resources in this sample
    /// </summary>
    public async Task GetStartedDemoAsync()
    {
        // Create a new instance of the Cosmos Client
        this.cosmosClient = new CosmosClient(EndpointUri, PrimaryKey);
        await this.CreateDatabaseAsync();
        await this.CreateContainerAsync();
        await this.AddItemsToContainerAsync();
        await this.QueryItemsAsync();
        await this.ReplaceFamilyItemAsync();
        await this.DeleteFamilyItemAsync();
        await this.DeleteDatabaseAndCleanupAsync();
    }
    
  3. Wählen Sie F5 aus, um die Anwendung auszuführen.Select F5 to run your application.

Glückwunsch!Congratulations! Sie haben erfolgreich eine Azure Cosmos-Datenbank gelöscht.You've successfully deleted an Azure Cosmos database.

Schritt 11: Ausführen der gesamten C#-Konsolenanwendung!Step 11: Run your C# console application all together!

Drücken Sie in Visual Studio F5, um die Anwendung im Debugmodus zu erstellen und auszuführen.Select F5 in Visual Studio to build and run the application in debug mode.

Die Ausgabe der gesamten App sollte in einem Konsolenfenster angezeigt werden.You should see the output of your entire app in a console window. Die Ausgabe enthält die Ergebnisse der hinzugefügten Abfragen.The output shows the results of the queries we added. Sie sollte dem unten angegebenen Beispieltext entsprechen.It should match the example text below.

Beginning operations...

Created Database: FamilyDatabase

Created Container: FamilyContainer

Created item in database with id: Andersen.1 Operation consumed 11.43 RUs.

Created item in database with id: Wakefield.7 Operation consumed 14.29 RUs.

Running query: SELECT * FROM c WHERE c.LastName = 'Andersen'

        Read {"id":"Andersen.1","LastName":"Andersen","Parents":[{"FamilyName":null,"FirstName":"Thomas"},{"FamilyName":null,"FirstName":"Mary Kay"}],"Children":[{"FamilyName":null,"FirstName":"Henriette Thaulow","Gender":"female","Grade":5,"Pets":[{"GivenName":"Fluffy"}]}],"Address":{"State":"WA","County":"King","City":"Seattle"},"IsRegistered":false}

Updated Family [Wakefield,Wakefield.7].
        Body is now: {"id":"Wakefield.7","LastName":"Wakefield","Parents":[{"FamilyName":"Wakefield","FirstName":"Robin"},{"FamilyName":"Miller","FirstName":"Ben"}],"Children":[{"FamilyName":"Merriam","FirstName":"Jesse","Gender":"female","Grade":6,"Pets":[{"GivenName":"Goofy"},{"GivenName":"Shadow"}]},{"FamilyName":"Miller","FirstName":"Lisa","Gender":"female","Grade":1,"Pets":null}],"Address":{"State":"NY","County":"Manhattan","City":"NY"},"IsRegistered":true}

Deleted Family [Wakefield,Wakefield.7]

Deleted Database: FamilyDatabase

End of demo, press any key to exit.

Glückwunsch!Congratulations! Sie haben dieses Tutorial abgeschlossen und verfügen über eine funktionierende C#-Konsolenanwendung.You've completed the tutorial and have a working C# console application!

Herunterladen der vollständigen Projektmappe für das TutorialGet the complete tutorial solution

Falls Sie die Schritte in diesem Tutorial aus Zeitmangel nicht durchführen konnten oder nur die Codebeispiele herunterladen möchten, können Sie den Download durchführen.If you didn't have time to complete the steps in this tutorial, or just want to download the code samples, you can download it.

Für die Erstellung der Projektmappe GetStarted müssen die folgenden Voraussetzungen erfüllt sein:To build the GetStarted solution, you need the following prerequisites:

Um die Verweise auf das Azure Cosmos DB .NET SDK in Visual Studio wiederherzustellen, klicken Sie mit der rechten Maustaste im Projektmappen-Explorer auf die Projektmappe und wählen dann die Option NuGet-Pakete wiederherstellen aus.To restore the references to the Azure Cosmos DB .NET SDK in Visual Studio, right-click the solution in Solution Explorer, and then select Restore NuGet Packages. Aktualisieren Sie als Nächstes in der Datei App.config die Werte EndPointUri und PrimaryKey wie unter Schritt 3: Herstellen einer Verbindung mit einem Azure Cosmos DB-Konto beschrieben.Next, in the App.config file, update the EndPointUri and PrimaryKey values as described in Step 3: Connect to an Azure Cosmos DB account.

Das ist alles, nun müssen Sie nur noch die Erstellung durchführen.That's it, build it, and you're on your way!

Nächste SchritteNext steps