在中使用 Azure Cosmos DB 檔資料庫 Xamarin.Forms
Azure Cosmos DB 檔案資料庫是 NoSQL 資料庫，可為需要無縫調整和全域複寫的應用程式提供快速、高可用性、可調整的資料庫服務，以提供低延遲的 JSON 檔存取。 本文說明如何使用 Azure Cosmos DB .NET Standard 用戶端連結庫，將 Azure Cosmos DB 檔案資料庫 Xamarin.Forms 整合到應用程式中。
Microsoft Azure Cosmos DB 影片
您可以使用 Azure 訂用帳戶來布建 Azure Cosmos DB 檔資料庫帳戶。 每個資料庫帳戶可以有零個或多個資料庫。 Azure Cosmos DB 中的文件資料庫是檔集合和用戶的邏輯容器。
Azure Cosmos DB 檔案資料庫可能包含零個或多個檔集合。 每個檔集合可以有不同的效能等級，允許針對經常存取的集合指定更多輸送量，以及不常存取集合的輸送量較少。
每個檔集合都包含零個或多個 JSON 檔。 集合中的檔是無架構的，因此不需要共用相同的結構或欄位。 當檔新增至檔集合時，Azure Cosmos DB 會自動為其編製索引，並可供查詢。
為了開發目的，文件資料庫也可以透過模擬器取用。 您可以使用模擬器，在本機開發及測試應用程式，而不需要建立 Azure 訂用帳戶或產生任何成本。 如需模擬器的詳細資訊，請參閱 使用 Azure Cosmos DB 模擬器在本機開發。
本文和隨附的範例應用程式會示範Todo清單應用程式，其中工作會儲存在 Azure Cosmos DB 檔案資料庫中。 如需範例應用程式的詳細資訊，請參閱 瞭解範例。
如需 Azure Cosmos DB 的詳細資訊，請參閱 Azure Cosmos DB 檔。
注意
如果您沒有 Azure 訂用帳戶，請在開始前建立免費帳戶。
設定
將 Azure Cosmos DB 檔案資料庫 Xamarin.Forms 整合到應用程式中的程式如下：
- 建立 Azure Cosmos DB 帳戶。 如需詳細資訊，請參閱 建立 Azure Cosmos DB 帳戶。
- 將 Azure Cosmos DB .NET Standard 用戶端連結庫 NuGet 套件新增至解決方案中的 Xamarin.Forms 平台專案。
- 將、
Microsoft.Azure.Documents.Client和Microsoft.Azure.Documents.Linq命名空間的指示詞Microsoft.Azure.Documents新增using至將存取 Azure Cosmos DB 帳戶的類別。
執行這些步驟之後，Azure Cosmos DB .NET Standard 用戶端連結庫可用來設定和執行對文件資料庫的要求。
注意
Azure Cosmos DB .NET Standard 用戶端連結庫只能安裝到平台專案中，而不能安裝到可攜式類別庫 （PCL） 專案中。 因此，範例應用程式是共用存取專案 （SAP），以避免程式代碼重複。 不過，類別 DependencyService 可用於 PCL 專案中，以叫用平臺特定專案中所包含的 Azure Cosmos DB .NET Standard 用戶端連結庫程式碼。
使用 Azure Cosmos DB 帳戶
此 DocumentClient 類型會封裝用來存取 Azure Cosmos DB 帳戶的端點、認證和連線原則，並用來設定和執行對帳戶的要求。 下列程式代碼範例示範如何建立這個類別的實例：
DocumentClient client = new DocumentClient(new Uri(Constants.EndpointUri), Constants.PrimaryKey);
Azure Cosmos DB URI 和主鍵必須提供給建 DocumentClient 構函式。 您可以從 Azure 入口網站取得這些專案。 如需詳細資訊，請參閱 連線 至 Azure Cosmos DB 帳戶。
建立資料庫
檔案資料庫是檔集合和用戶的邏輯容器，而且可以在 Azure 入口網站中建立，或使用 方法以程式設計方式 DocumentClient.CreateDatabaseIfNotExistsAsync 建立：
public async Task CreateDatabase(string databaseName)
{
...
await client.CreateDatabaseIfNotExistsAsync(new Database
{
Id = databaseName
});
...
}
方法 CreateDatabaseIfNotExistsAsync 會將 Database 物件指定為自變數，而 Database 物件會將資料庫名稱指定為其 Id 屬性。 如果資料庫不存在，方法 CreateDatabaseIfNotExistsAsync 會建立資料庫，或如果資料庫已經存在，則會傳回資料庫。 不過，範例應用程式會忽略 方法傳 CreateDatabaseIfNotExistsAsync 回的任何數據。
注意
CreateDatabaseIfNotExistsAsync方法會Task<ResourceResponse<Database>>傳回 物件，而且可以檢查回應的狀態代碼，以判斷是否已建立資料庫或傳回現有的資料庫。
建立文件集合
檔集合是 JSON 檔的容器，可以在 Azure 入口網站中建立，或使用 方法以程式設計方式 DocumentClient.CreateDocumentCollectionIfNotExistsAsync 建立：
public async Task CreateDocumentCollection(string databaseName, string collectionName)
{
...
// Create collection with 400 RU/s
await client.CreateDocumentCollectionIfNotExistsAsync(
UriFactory.CreateDatabaseUri(databaseName),
new DocumentCollection
{
Id = collectionName
},
new RequestOptions
{
OfferThroughput = 400
});
...
}
方法 CreateDocumentCollectionIfNotExistsAsync 需要兩個強制自變數 – 指定為 Uri的資料庫名稱，以及 DocumentCollection 物件。 物件 DocumentCollection 代表使用 屬性指定 Id 名稱的檔集合。 如果檔集合不存在，方法 CreateDocumentCollectionIfNotExistsAsync 會建立檔集合，或如果檔集合已經存在，則會傳回檔集合。 不過，範例應用程式會忽略 方法傳 CreateDocumentCollectionIfNotExistsAsync 回的任何數據。
注意
CreateDocumentCollectionIfNotExistsAsync方法會Task<ResourceResponse<DocumentCollection>>傳回 物件，而且可以檢查回應的狀態代碼，以判斷是否已建立檔集合，或傳回現有的檔集合。
或者， CreateDocumentCollectionIfNotExistsAsync 方法也可以指定 RequestOptions 物件，其會封裝可針對向 Azure Cosmos DB 帳戶發出的要求指定的選項。 屬性 RequestOptions.OfferThroughput 是用來定義檔集合的效能等級，而且在範例應用程式中，會設定為每秒 400 個要求單位。 此值應該根據集合經常或不常存取而增加或減少。
重要
請注意， CreateDocumentCollectionIfNotExistsAsync 此方法會建立具有保留輸送量的新集合，其具有定價含意。
擷取檔集合檔
您可以藉由建立和執行文件查詢來擷取檔集合的內容。 使用 方法建立 DocumentClient.CreateDocumentQuery 檔案查詢：
public async Task<List<TodoItem>> GetTodoItemsAsync()
{
...
var query = client.CreateDocumentQuery<TodoItem>(collectionLink)
.AsDocumentQuery();
while (query.HasMoreResults)
{
Items.AddRange(await query.ExecuteNextAsync<TodoItem>());
}
...
}
此查詢會以異步方式從指定的集合擷取所有檔，並將檔放在集合中 List<TodoItem> 以供顯示。
方法 CreateDocumentQuery<T> 會指定自 Uri 變數，代表應該查詢檔的集合。 在這裡範例中 collectionLink ，變數是類別層級欄位，指定要 Uri 從中擷取檔之檔案集合的 。
Uri collectionLink = UriFactory.CreateDocumentCollectionUri(Constants.DatabaseName, Constants.CollectionName);
方法 CreateDocumentQuery<T> 會建立同步執行的查詢，並傳 IQueryable<T> 回 物件。 不過，方法會將 AsDocumentQueryIQueryable<T> 物件 IDocumentQuery<T> 轉換成可以異步執行的物件。 異步查詢會使用 IDocumentQuery<T>.ExecuteNextAsync 方法執行，此方法會從檔資料庫擷取下一頁的結果，屬性 IDocumentQuery<T>.HasMoreResults 表示是否要從查詢傳回其他結果。
檔可以藉由 Where 在查詢中包含 子句來篩選伺服器端，這會對檔集合套用篩選述詞至查詢：
var query = client.CreateDocumentQuery<TodoItem>(collectionLink)
.Where(f => f.Done != true)
.AsDocumentQuery();
此查詢會從 屬性等於 false的集合Done中擷取所有檔。
將檔案插入檔集合
檔案是使用者定義的 JSON 內容，而且可以使用 方法插入檔集合 DocumentClient.CreateDocumentAsync ：
public async Task SaveTodoItemAsync(TodoItem item, bool isNewItem = false)
{
...
await client.CreateDocumentAsync(collectionLink, item);
...
}
方法 CreateDocumentAsync 會 Uri 指定自變數，代表應該插入檔的集合，以及 object 代表要插入之檔的自變數。
取代檔集合中的檔
檔案集合 DocumentClient.ReplaceDocumentAsync 中可以使用 方法取代檔案：
public async Task SaveTodoItemAsync(TodoItem item, bool isNewItem = false)
{
...
await client.ReplaceDocumentAsync(UriFactory.CreateDocumentUri(Constants.DatabaseName, Constants.CollectionName, item.Id), item);
...
}
方法 ReplaceDocumentAsync 會指定自 Uri 變數，代表應該取代之集合中的檔，以及 object 代表已更新之文件數據的自變數。
從檔案集合中刪除檔
您可以使用 方法，從檔案集合 DocumentClient.DeleteDocumentAsync 中移除檔案：
public async Task DeleteTodoItemAsync(string id)
{
...
await client.DeleteDocumentAsync(UriFactory.CreateDocumentUri(Constants.DatabaseName, Constants.CollectionName, id));
...
}
方法 DeleteDocumentAsync 會指定自 Uri 變數，代表應該刪除之集合中的檔。
刪除檔集合
您可以使用 方法，從資料庫 DocumentClient.DeleteDocumentCollectionAsync 刪除檔案集合：
await client.DeleteDocumentCollectionAsync(collectionLink);
方法 DeleteDocumentCollectionAsync 會 Uri 指定要刪除之檔集合的自變數。 請注意，叫用此方法也會刪除儲存在集合中的檔。
刪除資料庫
您可以使用 方法，從 Azure Cosmos DB 資料庫帳戶 DocumentClient.DeleteDatabaesAsync 中移除資料庫：
await client.DeleteDatabaseAsync(UriFactory.CreateDatabaseUri(Constants.DatabaseName));
方法 DeleteDatabaseAsync 會 Uri 指定要刪除之資料庫的自變數。 請注意，叫用此方法也會刪除儲存在資料庫中的檔集合，以及儲存在檔集合中的檔。
摘要
本文說明如何使用 Azure Cosmos DB .NET Standard 用戶端連結庫，將 Azure Cosmos DB 檔案資料庫 Xamarin.Forms 整合到應用程式中。 Azure Cosmos DB 檔案資料庫是 NoSQL 資料庫，可為需要無縫調整和全域複寫的應用程式提供快速、高可用性、可調整的資料庫服務，以提供低延遲的 JSON 檔存取。