有效的 Azure 帐户。如果您还没有帐户，可以注册一个免费帐户。

您可以免费试用 Azure Cosmos DB，无需 Azure 订阅，免费且无承诺。或者，您可以使用 Azure Cosmos DB 模拟器，其 URI 为 https://:8081。主密钥在身份验证请求中提供。
如果您还没有安装 Visual Studio 2017，可以下载并使用 **免费** 的 Visual Studio 2017 社区版。请确保在 Visual Studio 设置过程中启用 **Azure 开发** 工作负载。

步骤 1：创建 Azure Cosmos DB 帐户

让我们创建一个 Azure Cosmos DB 帐户。如果您已经有一个要使用的帐户，可以跳到设置您的 Visual Studio 解决方案。如果您正在使用 Azure Cosmos DB 模拟器，请按照 Azure Cosmos DB 模拟器中的步骤设置模拟器，然后跳到设置您的 Visual Studio 解决方案。

在新浏览器窗口中，登录 Azure 门户。
选择创建资源 > 数据库 > Azure Cosmos DB。

在创建 Azure Cosmos DB 帐户页面上，输入新的 Azure Cosmos DB 帐户的基本设置。

设置	值	描述
订阅	您的订阅	选择要用于此 Azure Cosmos DB 帐户的 Azure 订阅。
资源组	新建然后输入与 ID 中提供的相同的唯一名称	选择新建。然后为您的帐户输入新的资源组名称。为简单起见，请使用与您的 ID 相同的名称。
科目名称	输入唯一名称	输入一个唯一名称来标识您的 Azure Cosmos DB 帐户。由于 documents.azure.com 会附加到您提供的 ID 以创建 URI，因此请使用唯一 ID。 ID 只能包含小写字母、数字和连字符 (-) 字符。其长度必须在 3 到 31 个字符之间。
API	Core(SQL)	API 决定了要创建的帐户类型。Azure Cosmos DB 提供五种 API：文档数据库的核心 (SQL) API、图数据库的 Gremlin API、文档数据库的 MongoDB API、Azure 表存储和 Cassandra。目前，您必须为每种 API 创建一个单独的帐户。选择Core(SQL)，因为在本文中您将创建一个文档数据库并使用 SQL 语法进行查询。详细了解 SQL API.
Location	选择离您的用户最近的区域	选择一个托管您的 Azure Cosmos DB 帐户的地理位置。使用离您的用户最近的位置，以便他们能最快地访问数据。

选择审查+创建。您可以跳过网络和标记部分。

帐户创建需要几分钟时间。等待门户显示恭喜！您的 Azure Cosmos DB 帐户已创建页面。

步骤 2：设置您的 Visual Studio 解决方案

在您的计算机上打开 **Visual Studio 2017**。
在 **文件** 菜单上，选择 **新建**，然后选择 **项目**。
在 **新建项目** 对话框中，选择 **模板** / **Visual C#** / **控制台应用程序**，为您的项目命名，然后单击 **确定**。
在 **解决方案资源管理器** 中，右键单击您的新控制台应用程序（位于您的 Visual Studio 解决方案下），然后单击 **管理 NuGet 程序包...**
在 **NuGet** 选项卡中，单击 **浏览**，然后在搜索框中键入 **azure documentdb**。
在结果中，找到 **Microsoft.Azure.DocumentDB** 并单击 **安装**。Azure Cosmos DB SQL API 客户端库的程序包 ID 是 Microsoft Azure Cosmos DB 客户端库。

如果出现有关查看解决方案更改的消息，请单击 **确定**。如果出现有关接受许可协议的消息，请单击 **我接受**。

太棒了！设置完成，现在让我们开始编写代码。您可以在 GitHub 上找到本教程的完整代码项目。

步骤 3：连接到 Azure Cosmos DB 帐户

首先，将这些引用添加到 C# 应用程序的开头，在 i 文件中

using System;
using System.Linq;
using System.Threading.Tasks;

// ADD THIS PART TO YOUR CODE
using System.Net;
using Microsoft.Azure.Documents;
using Microsoft.Azure.Documents.Client;
using Newtonsoft.Json;

重要

要完成本教程，请确保添加上述依赖项。

现在，在您的 public class Program 下方添加这两个常量和您的 client 变量。

public class Program
{
    // ADD THIS PART TO YOUR CODE
    private const string EndpointUrl = "<your endpoint URL>";
    private const string PrimaryKey = "<your primary key>";
    private DocumentClient client;

接下来，回到 Azure 门户获取您的终结点 URL 和主密钥。终结点 URL 和主密钥对于您的应用程序了解连接到哪里至关重要，也让 Azure Cosmos DB 信任您应用程序的连接。

在 Azure 门户中，导航到您的 Azure Cosmos DB 帐户，然后单击 **密钥**。

将门户中的 URI 复制并粘贴到 program.cs 文件中的 <your endpoint URL>。然后复制门户中的 PRIMARY KEY 并粘贴到 <your primary key>。

接下来，我们将通过创建 DocumentClient 的新实例来启动应用程序。

在 Main 方法下方，添加这个名为 GetStartedDemo 的新异步任务，它将实例化我们的新 DocumentClient。

static void Main(string[] args)
{
}

// ADD THIS PART TO YOUR CODE
private async Task GetStartedDemo()
{
    this.client = new DocumentClient(new Uri(EndpointUrl), PrimaryKey);
}

将以下代码添加到您的 Main 方法以运行异步任务。Main 方法将捕获异常并将其写入控制台。

static void Main(string[] args)
{
        // ADD THIS PART TO YOUR CODE
        try
        {
                Program p = new Program();
                p.GetStartedDemo().Wait();
        }
        catch (DocumentClientException de)
        {
                Exception baseException = de.GetBaseException();
                Console.WriteLine("{0} error occurred: {1}, Message: {2}", de.StatusCode, de.Message, baseException.Message);
        }
        catch (Exception e)
        {
                Exception baseException = e.GetBaseException();
                Console.WriteLine("Error: {0}, Message: {1}", e.Message, baseException.Message);
        }
        finally
        {
                Console.WriteLine("End of demo, press any key to exit.");
                Console.ReadKey();
        }

按 **F5** 运行应用程序。控制台窗口输出显示“演示结束，按任意键退出。”消息，确认连接已建立。然后您可以关闭控制台窗口。

恭喜！您已成功连接到 Azure Cosmos DB 帐户，现在让我们看看如何使用 Azure Cosmos DB 资源。

步骤 4：创建数据库

在添加创建数据库的代码之前，添加一个用于写入控制台的辅助方法。

将 WriteToConsoleAndPromptToContinue 方法复制并粘贴到 GetStartedDemo 方法之后。

// ADD THIS PART TO YOUR CODE
private void WriteToConsoleAndPromptToContinue(string format, params object[] args)
{
        Console.WriteLine(format, args);
        Console.WriteLine("Press any key to continue ...");
        Console.ReadKey();
}

您可以使用 DocumentClient 类的 CreateDatabaseIfNotExistsAsync 方法创建您的 Azure Cosmos DB 数据库。数据库是分区到集合中的 JSON 文档存储的逻辑容器。

复制并粘贴以下代码到您的 GetStartedDemo 方法中，放在客户端创建之后。这将创建一个名为 FamilyDB 的数据库。

private async Task GetStartedDemo()
{
    this.client = new DocumentClient(new Uri(EndpointUrl), PrimaryKey);

    // ADD THIS PART TO YOUR CODE
    await this.client.CreateDatabaseIfNotExistsAsync(new Database { Id = "FamilyDB" });

按 **F5** 运行应用程序。

恭喜！您已成功创建了一个 Azure Cosmos DB 数据库。

步骤 5：创建集合

警告

CreateDocumentCollectionIfNotExistsAsync 将创建具有预留吞吐量的新集合，这会影响定价。有关更多详细信息，请访问我们的定价页面。

可以使用 DocumentClient 类的 CreateDocumentCollectionIfNotExistsAsync 方法创建集合。集合是 JSON 文档和关联的 JavaScript 应用程序逻辑的容器。

复制并粘贴以下代码到您的 GetStartedDemo 方法中，放在数据库创建之后。这将创建一个名为 FamilyCollection 的文档集合。

    this.client = new DocumentClient(new Uri(EndpointUrl), PrimaryKey);

    await this.client.CreateDatabaseIfNotExistsAsync(new Database { Id = "FamilyDB" });

    // ADD THIS PART TO YOUR CODE
     await this.client.CreateDocumentCollectionIfNotExistsAsync(UriFactory.CreateDatabaseUri("FamilyDB"), new DocumentCollection { Id = "FamilyCollection" });

按 **F5** 运行应用程序。

恭喜！您已成功创建了一个 Azure Cosmos DB 文档集合。

步骤 6：创建 JSON 文档

可以使用 DocumentClient 类的 CreateDocumentAsync 方法创建文档。文档是用户定义的（任意）JSON 内容。我们现在可以插入一个或多个文档。如果您已经有要存储在数据库中的数据，可以使用 Azure Cosmos DB 数据迁移工具将数据导入数据库。

首先，我们需要创建一个 Family 类，它将代表本示例中存储在 Azure Cosmos DB 中的对象。我们还将创建在 Family 中使用的 Parent、Child、Pet、Address 子类。请注意，文档必须有一个 Id 属性，在 JSON 中序列化为 id。通过在 GetStartedDemo 方法之后添加以下内部子类来创建这些类。

将 Family、Parent、Child、Pet 和 Address 类复制并粘贴到 WriteToConsoleAndPromptToContinue 方法之后。

private void WriteToConsoleAndPromptToContinue(string format, params object[] args)
{
    Console.WriteLine(format, args);
    Console.WriteLine("Press any key to continue ...");
    Console.ReadKey();
}

// ADD THIS PART TO YOUR CODE
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; }
}

将 CreateFamilyDocumentIfNotExists 方法复制并粘贴到 Address 类下方。

// ADD THIS PART TO YOUR CODE
private async Task CreateFamilyDocumentIfNotExists(string databaseName, string collectionName, Family family)
{
    try
    {
        await this.client.ReadDocumentAsync(UriFactory.CreateDocumentUri(databaseName, collectionName, family.Id));
        this.WriteToConsoleAndPromptToContinue("Found {0}", family.Id);
    }
    catch (DocumentClientException de)
    {
        if (de.StatusCode == HttpStatusCode.NotFound)
        {
            await this.client.CreateDocumentAsync(UriFactory.CreateDocumentCollectionUri(databaseName, collectionName), family);
            this.WriteToConsoleAndPromptToContinue("Created Family {0}", family.Id);
        }
        else
        {
            throw;
        }
    }
}

并插入两个文档，分别代表 Andersen 家庭和 Wakefield 家庭。

复制并粘贴以下代码到您的 GetStartedDemo 方法中，放在文档集合创建之后。

await this.client.CreateDatabaseIfNotExistsAsync(new Database { Id = "FamilyDB" });

await this.client.CreateDocumentCollectionIfNotExistsAsync(UriFactory.CreateDatabaseUri("FamilyDB"), new DocumentCollection { Id = "FamilyCollection" });


// ADD THIS PART TO YOUR CODE
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 = true
};

await this.CreateFamilyDocumentIfNotExists("FamilyDB", "FamilyCollection", andersenFamily);

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 = false
};

await this.CreateFamilyDocumentIfNotExists("FamilyDB", "FamilyCollection", wakefieldFamily);

按 **F5** 运行应用程序。

恭喜！您已成功创建了两个 Azure Cosmos DB 文档。

步骤 7：查询 Azure Cosmos DB 资源

Azure Cosmos DB 支持对集合中存储的 JSON 文档进行丰富的查询。以下示例代码显示了各种查询 - 使用 Azure Cosmos DB SQL 语法和 LINQ - 我们可以对上一步插入的文档运行这些查询。

将 ExecuteSimpleQuery 方法复制并粘贴到 CreateFamilyDocumentIfNotExists 方法之后。

// ADD THIS PART TO YOUR CODE
private void ExecuteSimpleQuery(string databaseName, string collectionName)
{
    // Set some common query options
    FeedOptions queryOptions = new FeedOptions { MaxItemCount = -1 };

        // Here we find the Andersen family via its LastName
        IQueryable<Family> familyQuery = this.client.CreateDocumentQuery<Family>(
                UriFactory.CreateDocumentCollectionUri(databaseName, collectionName), queryOptions)
                .Where(f => f.LastName == "Andersen");

        // The query is executed synchronously here, but can also be executed asynchronously via the IDocumentQuery<T> interface
        Console.WriteLine("Running LINQ query...");
        foreach (Family family in familyQuery)
        {
                Console.WriteLine("\tRead {0}", family);
        }

        // Now execute the same query via direct SQL
        IQueryable<Family> familyQueryInSql = this.client.CreateDocumentQuery<Family>(
                UriFactory.CreateDocumentCollectionUri(databaseName, collectionName),
                "SELECT * FROM Family WHERE Family.LastName = 'Andersen'",
                queryOptions);

        Console.WriteLine("Running direct SQL query...");
        foreach (Family family in familyQueryInSql)
        {
                Console.WriteLine("\tRead {0}", family);
        }

        Console.WriteLine("Press any key to continue ...");
        Console.ReadKey();
}

复制并粘贴以下代码到您的 GetStartedDemo 方法中，放在第二个文档创建之后。

await this.CreateFamilyDocumentIfNotExists("FamilyDB", "FamilyCollection", wakefieldFamily);

// ADD THIS PART TO YOUR CODE
this.ExecuteSimpleQuery("FamilyDB", "FamilyCollection");

按 **F5** 运行应用程序。

恭喜！您已成功查询了 Azure Cosmos DB 集合。

下图说明了 Azure Cosmos DB SQL 查询语法如何针对您创建的集合进行调用，LINQ 查询也适用相同的逻辑。

查询中的 FROM 关键字是可选的，因为 Azure Cosmos DB 查询已经限定在单个集合的范围内。因此，“FROM Families f”可以替换为“FROM root r”或您选择的任何其他变量名。Azure Cosmos DB 将默认推断 Families、root 或您选择的变量名引用当前集合。

步骤 8：替换 JSON 文档

Azure Cosmos DB 支持替换 JSON 文档。

将 ReplaceFamilyDocument 方法复制并粘贴到 ExecuteSimpleQuery 方法之后。

// ADD THIS PART TO YOUR CODE
private async Task ReplaceFamilyDocument(string databaseName, string collectionName, string familyName, Family updatedFamily)
{
     await this.client.ReplaceDocumentAsync(UriFactory.CreateDocumentUri(databaseName, collectionName, familyName), updatedFamily);
     this.WriteToConsoleAndPromptToContinue("Replaced Family {0}", familyName);
}

复制并粘贴以下代码到您的 GetStartedDemo 方法中，放在查询执行之后，位于方法末尾。替换文档后，将再次运行相同的查询以查看已更改的文档。

await this.CreateFamilyDocumentIfNotExists("FamilyDB", "FamilyCollection", wakefieldFamily);

this.ExecuteSimpleQuery("FamilyDB", "FamilyCollection");

// ADD THIS PART TO YOUR CODE
// Update the Grade of the Andersen Family child
andersenFamily.Children[0].Grade = 6;

await this.ReplaceFamilyDocument("FamilyDB", "FamilyCollection", "Andersen.1", andersenFamily);

this.ExecuteSimpleQuery("FamilyDB", "FamilyCollection");

按 **F5** 运行应用程序。

恭喜！您已成功替换了一个 Azure Cosmos DB 文档。

步骤 9：删除 JSON 文档

Azure Cosmos DB 支持删除 JSON 文档。

将 DeleteFamilyDocument 方法复制并粘贴到 ReplaceFamilyDocument 方法之后。

// ADD THIS PART TO YOUR CODE
private async Task DeleteFamilyDocument(string databaseName, string collectionName, string documentName)
{
     await this.client.DeleteDocumentAsync(UriFactory.CreateDocumentUri(databaseName, collectionName, documentName));
     Console.WriteLine("Deleted Family {0}", documentName);
}

复制并粘贴以下代码到您的 GetStartedDemo 方法中，放在第二次查询执行之后，位于方法末尾。

await this.ReplaceFamilyDocument("FamilyDB", "FamilyCollection", "Andersen.1", andersenFamily);

this.ExecuteSimpleQuery("FamilyDB", "FamilyCollection");

// ADD THIS PART TO CODE
await this.DeleteFamilyDocument("FamilyDB", "FamilyCollection", "Andersen.1");

按 **F5** 运行应用程序。

恭喜！您已成功删除了一个 Azure Cosmos DB 文档。

步骤 10：删除数据库

删除已创建的数据库将删除数据库及其所有子资源（集合、文档等）。

复制并粘贴以下代码到您的 GetStartedDemo 方法中，放在文档删除之后，以删除整个数据库及其所有子资源。

this.ExecuteSimpleQuery("FamilyDB", "FamilyCollection");

await this.DeleteFamilyDocument("FamilyDB", "FamilyCollection", "Andersen.1");

// ADD THIS PART TO CODE
// Clean up/delete the database
await this.client.DeleteDatabaseAsync(UriFactory.CreateDatabaseUri("FamilyDB"));

按 **F5** 运行应用程序。

恭喜！您已成功删除了一个 Azure Cosmos DB 数据库。

步骤 11：一起运行您的 C# 控制台应用程序！

在 Visual Studio 中按 F5 以调试模式生成应用程序。

您应该会在控制台窗口中看到入门应用程序的输出。输出将显示我们添加的查询结果，并且应与下面的示例文本匹配。

Created FamilyDB
Press any key to continue ...
Created FamilyCollection
Press any key to continue ...
Created Family Andersen.1
Press any key to continue ...
Created Family Wakefield.7
Press any key to continue ...
Running LINQ query...
    Read {"id":"Andersen.1","LastName":"Andersen","District":"WA5","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":true}
Running direct SQL query...
    Read {"id":"Andersen.1","LastName":"Andersen","District":"WA5","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":true}
Replaced Family Andersen.1
Press any key to continue ...
Running LINQ query...
    Read {"id":"Andersen.1","LastName":"Andersen","District":"WA5","Parents":[{"FamilyName":null,"FirstName":"Thomas"},{"FamilyName":null,"FirstName":"Mary Kay"}],"Children":[{"FamilyName":null,"FirstName":"Henriette Thaulow","Gender":"female","Grade":6,"Pets":[{"GivenName":"Fluffy"}]}],"Address":{"State":"WA","County":"King","City":"Seattle"},"IsRegistered":true}
Running direct SQL query...
    Read {"id":"Andersen.1","LastName":"Andersen","District":"WA5","Parents":[{"FamilyName":null,"FirstName":"Thomas"},{"FamilyName":null,"FirstName":"Mary Kay"}],"Children":[{"FamilyName":null,"FirstName":"Henriette Thaulow","Gender":"female","Grade":6,"Pets":[{"GivenName":"Fluffy"}]}],"Address":{"State":"WA","County":"King","City":"Seattle"},"IsRegistered":true}
Deleted Family Andersen.1
End of demo, press any key to exit.

恭喜！您已完成本教程，并拥有一个可正常工作的 C# 控制台应用程序！

获取完整的教程解决方案

如果您没有时间完成本教程中的步骤，或者只想下载代码示例，您可以从 GitHub 获取。

要生成 GetStarted 解决方案，您需要以下内容

有效的 Azure 帐户。如果您还没有帐户，可以注册一个免费帐户。
一个 Azure Cosmos DB 帐户。
GitHub 上提供的 GetStarted 解决方案。

要在 Visual Studio 中恢复对 Azure Cosmos DB .NET SDK 的引用，请在解决方案资源管理器中右键单击 **GetStarted** 解决方案，然后单击 **启用 NuGet 程序包还原**。接下来，在 App.config 文件中，按照连接到 Azure Cosmos DB 帐户中的说明更新 EndpointUrl 和 AuthorizationKey 值。

就是这样，生成它，您就可以开始了！

后续步骤

想要一个更复杂的 ASP.NET MVC 教程？请参阅 ASP.NET MVC 教程：使用 Azure Cosmos DB 进行 Web 应用程序开发。
想要使用 Azure Cosmos DB 进行规模和性能测试？请参阅 Azure Cosmos DB 的性能和规模测试
了解如何监视 Azure Cosmos DB 请求、使用情况和存储。
在查询游乐场中针对我们的示例数据集运行查询。
要了解有关 Azure Cosmos DB 的更多信息，请参阅欢迎使用 Azure Cosmos DB。