快速入門:建立 .NET 主控台應用程式來管理 Azure Cosmos DB SQL API 資源

適用于 :SQL API

開始使用 Azure 資料庫Cosmos .NET SQL API 用戶端庫。 請遵循本文中的步驟來安裝 .NET 套件、建立應用程式,並嘗試在 Azure Cosmos DB 中儲存的資料上執行基本 CRUD 操作Cosmos程式碼。

Azure Cosmos DB 是 Microsoft 的快速 NoSQL 資料庫,具有任何規模開啟的 API。 您可以使用 Azure Cosmos資料庫來快速建立和查詢鍵/值、檔及圖形資料庫。 使用 Azure Cosmos DB SQL API 用戶端庫來使用 .NET:

  • 建立 Azure Cosmos資料庫和容器
  • 新增範例資料至容器
  • 查詢資料
  • 刪除資料庫

API 參考檔文件庫原始程式碼套件 (NuGet)

先決條件

建立

本節將逐步引導您建立 Azure Cosmos帳戶,以及設定使用 Azure Cosmos DB SQL API 用戶端庫來管理資源的專案。 本文所述的範例程式碼會建立資料庫和家庭成員 (每個家庭成員都是該資料庫) FamilyDatabase 專案。 每個家庭成員都有屬性,例如 Id, FamilyName, FirstName, LastName, Parents, Children, Address,LastName屬性會用來做為容器的分區鍵。

建立 Azure Cosmos帳戶

如果您使用免費試用Azure Cosmos DB選項來建立 Azure Cosmos 帳戶,您必須建立 azure Cosmos DB 帳戶,SQL API。 已Cosmos Azure 資料庫測試帳戶。 您不需要明確建立帳戶,因此您可以略過此節並移至下一節。

如果您有自己的 Azure 訂閱或免費建立訂閱,您應該明確地建立 Azure Cosmos帳戶。 下列程式碼會建立具有會話Cosmos Azure 帳戶。 該帳戶會複製到 和 South Central USNorth Central US 中。

您可以使用 Azure Cloud Shell 建立 Azure Cosmos帳戶。 Azure Cloud Shell 是一種互動式、經過驗證且易於瀏覽器訪問的 shell,可管理 Azure 資源。 它提供選擇最適合您工作方式的 shell 體驗彈性,無論是 Bash 或 PowerShell。 針對此快速入門,選擇 Bash 模式。 Azure Cloud Shell 也需要儲存空間帳戶,當系統提示時,您可以建立帳戶。

選取下列 程式碼 旁的嘗試按鈕,選擇 Bash 模式,選取建立儲存空間 帳戶 並登入雲端 Shell。 下一步複製並貼上下列程式碼至 Azure Cloud Shell 並執行。 Azure Cosmos帳戶名稱必須全域唯一,請務必更新值,然後再 mysqlapicosmosdb 執行命令。


# Set variables for the new SQL API account, database, and container
resourceGroupName='myResourceGroup'
location='southcentralus'

# The Azure Cosmos account name must be globally unique, make sure to update the `mysqlapicosmosdb` value before you run the command
accountName='mysqlapicosmosdb'

# Create a resource group
az group create \
    --name $resourceGroupName \
    --location $location

# Create a SQL API Cosmos DB account with session consistency and multi-region writes enabled
az cosmosdb create \
    --resource-group $resourceGroupName \
    --name $accountName \
    --kind GlobalDocumentDB \
    --locations regionName="South Central US" failoverPriority=0 --locations regionName="North Central US" failoverPriority=1 \
    --default-consistency-level "Session" \
    --enable-multiple-write-locations true

建立 Azure Cosmos帳戶需要一段時間,一旦作業成功,您即會看到確認輸出。 命令成功完成之後,請登錄Azure入口網站,並Cosmos具有指定名稱的 Azure 帳戶。 建立資源之後,您可以關閉 Azure Cloud Shell 視窗。

建立新的 .NET 應用程式

在偏好的編輯器或 IDE 中建立新的 .NET 應用程式。 從您的Windows開啟命令提示或終端機視窗。 您將從命令提示符或終端機執行下一節中的所有命令。 執行下列 dotnet 新命令以使用名稱建立新應用程式 todo 。 --langVersion 參數會設定所建立專案檔案中的 LangVersion 屬性。

dotnet new console --langVersion 7.1 -n todo

將目錄變更為新建立的應用程式資料夾。 您可以使用以下功能來建立應用程式:

cd todo
dotnet build

來自建建的預期輸出看起來應該像這樣:

  Restore completed in 100.37 ms for C:\Users\user1\Downloads\CosmosDB_Samples\todo\todo.csproj.
  todo -> C:\Users\user1\Downloads\CosmosDB_Samples\todo\bin\Debug\netcoreapp2.2\todo.dll
  todo -> C:\Users\user1\Downloads\CosmosDB_Samples\todo\bin\Debug\netcoreapp2.2\todo.Views.dll

Build succeeded.
    0 Warning(s)
    0 Error(s)

Time Elapsed 00:00:34.17

安裝 Azure Cosmos DB 套件

在應用程式目錄中時,使用 dotnet add package 命令Cosmos .NET Core 的 Azure 資料庫用戶端庫。

dotnet add package Microsoft.Azure.Cosmos

從 Azure 入口Cosmos您的 Azure 帳號憑證

範例應用程式需要向 Azure 帳戶Cosmos驗證。 若要進行驗證,您應將 Azure Cosmos帳號憑證傳遞到應用程式。 請遵循下列Cosmos取得 Azure 帳號憑證:

  1. 請登錄 Azure 入口網站

  2. 流覽至您的 Azure Cosmos帳戶。

  3. 開啟金鑰 窗格 ,然後複製 您帳戶的 URIPRIMARY KEY。 您將在下一個步驟中新增 URI 和按鍵值至環境變數。

設定環境變數

複製帳戶 的 URIPRIMARY KEY 之後,將它們儲存到執行應用程式的本機電腦上的新環境變數。 若要設定環境變數,請開啟主控台視窗,然後執行下列命令。 請務必取代 <Your_Azure_Cosmos_account_URI><Your_Azure_Cosmos_account_PRIMARY_KEY> 值。

Windows

setx EndpointUrl "<Your_Azure_Cosmos_account_URI>"
setx PrimaryKey "<Your_Azure_Cosmos_account_PRIMARY_KEY>"

Linux

export EndpointUrl = "<Your_Azure_Cosmos_account_URI>"
export PrimaryKey = "<Your_Azure_Cosmos_account_PRIMARY_KEY>"

macOS

export EndpointUrl = "<Your_Azure_Cosmos_account_URI>"
export PrimaryKey = "<Your_Azure_Cosmos_account_PRIMARY_KEY>"

物件模型

開始建立應用程式之前,讓我們先瞭解 Azure Cosmos DB 中的資源階層,以及用來建立及存取這些資源的物件模型。 Azure Cosmos資料庫會按照下列順序建立資源:

  • Azure Cosmos帳戶
  • 資料庫
  • 容器
  • 專案

若要深入瞭解不同實體的階層,請參閱使用 Azure 中的資料庫、容器和專案Cosmos文章。 您將使用下列 .NET 類與這些資源互動:

  • CosmosClient - 此類別提供 Azure Cosmos DB 服務的用戶端邏輯表示。 用戶端物件是用來針對服務設定並執行要求。

  • CreateDatabaseIfNotExistsAsync - 此方法會建立 (如果不存在) ,或 (資料庫資源) 非同步作業。

  • CreateContainerIfNotExistsAsync- - 此方法會建立 (如果不存在) 或 (如果容器已經) 非同步作業。 您可以檢查回應的狀態碼,以判斷容器是新建立于 (201) 或現有容器是于 (200) 。

  • CreateItemAsync - 此方法在容器內建立專案。

  • UpsertItemAsync - 此方法在容器內建立專案 ,如果該專案不存在,或取代專案如果已存在。

  • GetItemQueryIterator - 此方法使用具有參數值的 SQL 語句,在 Azure Cosmos 資料庫中建立容器下專案的查詢。

  • DeleteAsync - 從 Azure 帳戶刪除Cosmos資料庫。 DeleteAsync 方法只會刪除資料庫。 處理實例應該與 Cosmosclient DeleteDatabase 和CleanupAsync 方法 (分開處理。

程式碼範例

本文所述的範例程式碼會建立 Azure Cosmos資料庫。 家庭資料庫包含家庭詳細資料,例如名稱、位址、位置、相關聯的家長、子女和寵物。 在將資料填至 Azure Cosmos帳戶之前,請定義家庭專案的屬性。 在範例應用程式的 Family.cs 根層級建立名為的新類別,並新增下列程式碼:

using Newtonsoft.Json;

namespace todo
{
    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; }
        // The ToString() method is used to format the output, it's used for demo purpose only. It's not required by Azure Cosmos DB
        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; }
    }
}

新增 using 指令 & 定義用戶端物件

從專案目錄,在編輯器中開啟檔案,然後使用應用程式頂端的指示新增 Program.cs 下列專案:


using System;
using System.Threading.Tasks;
using System.Configuration;
using System.Collections.Generic;
using System.Net;
using Microsoft.Azure.Cosmos;

Program.cs 檔案 中,新增程式碼以讀取您于上一個步驟中設定的環境變數。 定義 CosmosClientDatabaseContainer 物件。 接下來,在主方法中新增程式碼,以呼叫您管理 Azure Cosmos GetStartedDemoAsync 帳戶資源的方法。

namespace todo
{
public class Program
{

    /// The Azure Cosmos DB endpoint for running this GetStarted sample.
    private string EndpointUrl = Environment.GetEnvironmentVariable("EndpointUrl");

    /// The primary key for the Azure DocumentDB account.
    private string PrimaryKey = Environment.GetEnvironmentVariable("PrimaryKey");

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

建立資料庫

定義 CreateDatabaseAsync 類內 program.cs 的方法。 此方法會建立不存在的 FamilyDatabase

private async Task CreateDatabaseAsync()
{
    // Create a new database
    this.database = await this.cosmosClient.CreateDatabaseIfNotExistsAsync(databaseId);
    Console.WriteLine("Created Database: {0}\n", this.database.Id);
}

建立容器

定義 CreateContainerAsync 類內 program.cs 的方法。 此方法會建立不存在的 FamilyContainer

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

建立專案

使用下列程式碼新增 AddItemsToContainerAsync 方法以建立家庭專案。 您可以使用 或 CreateItemAsyncUpsertItemAsync 方法來建立專案:

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
    {
        // 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 of 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);
    }
    catch (CosmosException ex) when (ex.StatusCode == HttpStatusCode.Conflict)
    {
        Console.WriteLine("Item in database with id: {0} already exists\n", andersenFamily.Id);                
    }
}

查詢專案

插入專案之後,您可以執行查詢以取得 「Andersen」 家庭的詳細資訊。 下列程式碼顯示如何使用查詢直接執行SQL查詢。 若要SQL Anderson" 家庭詳細資料,其查詢為: SELECT * FROM c WHERE c.LastName = 'Andersen' 。 在 QueryItemsAsync 類中定義 program.cs 方法,並新增下列程式碼:

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

刪除資料庫

最後,您可以刪除使用下列程式碼 DeleteDatabaseAndCleanupAsync 新增方法的資料庫:

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

執行 CRUD 運算

定義所有所需方法之後,在方法中執行 GetStartedDemoAsync 這些方法。 此程式碼中注釋掉的方法,因為如果執行這個方法,您 DeleteDatabaseAndCleanupAsync 將不會看到任何資源。 驗證 Azure 資料庫資源是在 Azure 入口網站中建立Cosmos之後,您可以取消注釋。

public async Task GetStartedDemoAsync()
{
    // Create a new instance of the Cosmos Client
    this.cosmosClient = new CosmosClient(EndpointUrl, PrimaryKey);
    await this.CreateDatabaseAsync();
    await this.CreateContainerAsync();
    await this.AddItemsToContainerAsync();
    await this.QueryItemsAsync();
}

新增所有所需方法之後,請儲存 Program.cs 檔案。

執行程式碼

下一步建立並執行應用程式,以建立 Azure Cosmos資料庫資源。 請務必開啟新的命令提示視窗,請勿使用您用來設定環境變數的相同實例。 因為環境變數並未在目前的開啟視窗中設定。 您必須開啟新的命令提示,以查看更新。

dotnet build
dotnet run

當您執行應用程式時,會產生下列輸出。 您也可以登錄 Azure 入口網站,並驗證資源已建立:

Created Database: FamilyDatabase

Created Container: FamilyContainer

Created item in database with id: Andersen.1 Operation consumed 11.62 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}

End of demo, press any key to exit.

您可以驗證資料是否建立,請登錄 Azure 入口網站,並查看 Azure 帳戶Cosmos專案。

清理資源

不再需要時,您可以使用 Azure CLI 或 Azure PowerShell移除 Azure 帳戶Cosmos對應的資源群組。 下列命令顯示如何使用 Azure CLI 刪除資源群組:

az group delete -g "myResourceGroup"

下一個步驟

在這個快速入門中,您學到如何使用 .NET Core Cosmos建立 Azure 帳戶、建立資料庫和容器。 現在,您可以使用下列文章Cosmos將其他資料導入 Azure 帳戶。

嘗試針對移向 Azure 資料庫執行容量規劃Cosmos嗎? 您可以使用現有資料庫組的資訊進行容量規劃。

  • 如果您知道現有的資料庫群集中的 vcore 和伺服器數目,請閱讀使用vCores 或 vCPUs估算要求單位的資訊
  • 如果您知道目前資料庫工作負載的典型要求率,請參閱使用 Azure 或 DB 容量規劃器Cosmos要求單位