快速入門:適用於 .NET 的 Azure Cosmos DB 數據表連結庫
適用於: 資料表
此快速入門說明如何從 .NET 應用程式開始使用 Azure Cosmos DB for Table。 Azure Cosmos DB for Table 是無結構描述資料存放區,可讓應用程式將結構化的資料表資料儲存在雲端中。 您將瞭解如何使用適用於 .NET 的 Azure SDK,在 Azure Cosmos DB 資源內建立數據表、數據列及執行基本工作
API 參考文件 | 程式庫原始程式碼 | 套件 (NuGet) | Azure Developer CLI
必要條件
- 具有有效訂用帳戶的 Azure 帳戶。 免費建立帳戶。
- Azure Developer CLI
- Docker Desktop
- .NET 9.0
初始化專案
使用 Azure 開發人員 CLI (azd
) 建立適用於資料表帳戶的 Azure Cosmos DB,並部署容器化範例應用程式。 應用程式範例使用用戶端程式庫管理、建立、讀取和查詢樣本資料。
在空的目錄中開啟終端機。
如果您尚未通過驗證,請使用
azd auth login
向 Azure 開發人員 CLI 進行驗證。 依照工具指定的步驟,使用您慣用的 Azure 認證向 CLI 進行驗證。azd auth login
使用
azd init
來初始化專案。azd init --template cosmos-db-table-dotnet-quickstart
在初始化期間,請設定唯一的環境名稱。
使用
azd up
部署 Azure Cosmos DB 帳戶。 Bicep 範本也會部署範例 Web 應用程式。azd up
在布建程式期間,選取您的訂用帳戶、所需的位置和目標資源群組。 等候佈建程序完成。 此流程「大約需要五分鐘」的時間。
Azure 資源佈建完成後,輸出將包含正在執行的 Web 應用程式的 URL。
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.
請使用主控台中的 URL,以在瀏覽器中導覽至您的 Web 應用程式。 觀察執行中應用程式的輸出。
安裝用戶端程式庫
用戶端程式庫可透過 NuGet 以 Azure.Data.Tables
套件形式提供。
開啟終端機,然後導覽至
/src/web
資料夾。cd ./src/web
如果尚未安裝,則請使用
dotnet add package
來安裝Azure.Data.Tables
套件。dotnet add package Azure.Data.Tables
開啟並檢閱 src/web/Microsoft.Samples.Cosmos.Table.Quickstart.Web.csproj 檔案,以驗證
Azure.Data.Tables
專案是否存在。
物件模型
名稱 | 描述 |
---|---|
TableServiceClient | 此類別是主要用戶端類別,並且用來管理全帳戶中繼資料或資料庫。 |
TableClient | 這個類別代表帳戶內數據表的用戶端。 |
程式碼範例
範本中的範例程式代碼會使用名為 的 cosmicworks-products
數據表。 數據表 cosmicworks-products
包含詳細數據,例如名稱、類別、數量、價格、唯一標識碼,以及每個產品的銷售旗標。 容器會使用唯一 標識符* 作為數據列索引鍵,而 類別目錄 則作為分割區索引鍵。
驗證用戶端
此範例會建立 類別的新實例 TableServiceClient
。
TableServiceClient serviceClient = new(
endpoint: new Uri("<azure-cosmos-db-table-account-endpoint>"),
credential
);
取得數據表
此範例會使用 GetTableClient
類別的 TableClient
方法,建立 類別的TableServiceClient
實例。
TableClient client = serviceClient.GetTableClient(
tableName: "<azure-cosmos-db-table-name>"
);
建立項目
在資料表中建立新項目最簡單的方式,就是建立實作 ITableEntity
介面的類別。 接著,您可以將自己的屬性新增至 類別,以填入該資料表資料列中的資料行。
public record Product : ITableEntity
{
public string RowKey { get; set; } = $"{Guid.NewGuid()}";
public string PartitionKey { get; set; } = String.Empty;
public string Name { get; set; } = String.Empty;
public int Quantity { get; set; } = 0;
public decimal Price { get; set; } = 0.0m;
public bool Clearance { get; set; } = false;
public ETag ETag { get; set; } = ETag.All;
public DateTimeOffset? Timestamp { get; set; }
};
藉由呼叫 TableClient.AddEntityAsync<T>
並使用 Product
類別在集合中建立項目。
Product entity = new()
{
RowKey = "68719518391",
PartitionKey = "gear-surf-surfboards",
Name = "Surfboard",
Quantity = 10,
Price = 300.00m,
Clearance = true
};
Response response = await client.UpsertEntityAsync<Product>(
entity: entity,
mode: TableUpdateMode.Replace
);
取得項目
您可以使用 TableClient.GetEntityAsync<T>
方法,從資料表擷取特定項目。 提供用來識別正確資料列的 partitionKey
和 rowKey
作為參數,以執行該項目的快速點讀取。
Response<Product> response = await client.GetEntityAsync<Product>(
rowKey: "68719518391",
partitionKey: "gear-surf-surfboards"
);
查詢項目
插入項目之後,您也可以使用 TableClient.Query<T>
方法,執行查詢來取得符合特定篩選的所有項目。 此範例會使用 Linq 語法依類別篩選產品,這是使用類似 Product
類別的 ITableEntity
型別模型的優點。
string category = "gear-surf-surfboards";
AsyncPageable<Product> results = client.QueryAsync<Product>(
product => product.PartitionKey == category
);
使用異步迴圈迴圈逐一查看結果的每個頁面,以剖析查詢的分頁結果。
List<Product> entities = new();
await foreach (Product product in results)
{
entities.Add(product);
}
清除資源
當您不再需要範例應用程式或資源時,請移除對應的部署和所有資源。
azd down