通过

你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

快速入门：适用于 .NET 的 Azure Blob 存储客户端库

  • 项目

注意

“从头开始生成”选项将引导你逐步完成创建新项目、安装包、编写代码和运行基本控制台应用的过程。 若要了解创建连接到 Azure Blob 存储的应用所涉及的所有详细信息，建议使用此方法。 如果希望自动执行部署任务并从已完成的项目开始，请选择“从模板开始”。

注意

“从模板开始”选项使用 Azure Developer CLI 自动执行部署任务，并从已完成的项目开始。 若要尽快浏览代码而不完成设置任务，建议使用此方法。 如果希望使用逐步说明生成应用，请选择“从头开始生成”。

适用于 .NET 的 Azure Blob 存储客户端库入门。 Azure Blob 存储是 Microsoft 经过优化的适用于云的对象存储解决方案，用于存储巨量的非结构化数据。

在本文中，你将按照步骤安装软件包，并试用基本任务的示例代码。

本文使用 Azure Developer CLI 部署 Azure 资源，只需几个命令即可运行完整的控制台应用。

API 参考文档 | 库源代码 | 包 (NuGet) | 示例

此视频演示如何开始使用适用于 .NET 的 Azure Blob 存储客户端库。

视频中的步骤也在以下部分进行了介绍。

先决条件

设置

本部分逐步指导如何准备一个项目，使其与适用于 .NET 的 Azure Blob 存储客户端库配合使用。

创建项目

使用 .NET CLI 或 Visual Studio 2022 创建 .NET 控制台应用。

  1. 在 Visual Studio 顶部，导航到“文件”>“新建”>“项目”。

  2. 在对话框窗口中，在项目模板搜索框中输入“控制台应用”，然后选择第一个结果。 选择对话框底部的“下一步”。

    显示如何使用 Visual Studio 创建新项目的屏幕截图。

  3. 对于“项目名称”，请输入“BlobQuickstart”。 保留其余字段的默认值，然后选择“下一步”。

  4. 对于 Framework，请确保已选择最新安装版本的 .NET。 然后选择“创建”。 此时新项目在 Visual Studio 环境中打开。

安装包

若要与 Azure Blob 存储交互，请安装适用于 .NET 的 Azure Blob 存储客户端库。

  1. 在解决方案资源管理器中，右键单击项目的“依赖项”节点。 选择“管理 NuGet 包”。

  2. 在出现的窗口中，搜索 Azure.Storage.Blob。 选择相应的结果，然后选择“安装”。

    显示如何使用 Visual Studio 添加新包的屏幕截图。

设置应用代码

替换 Program.cs 文件中的起始代码，使其与以下示例匹配，其中包括本练习所需的 using 语句。

using Azure.Storage.Blobs;
using Azure.Storage.Blobs.Models;
using System;
using System.IO;

// See https://aka.ms/new-console-template for more information
Console.WriteLine("Hello, World!");

安装 Azure Developer CLI 后，只需几个命令即可创建存储帐户并运行示例代码。 可以在本地开发环境中运行项目，也可以在 DevContainer 中运行项目。

初始化 Azure Developer CLI 模板并部署资源

在空目录中，按照以下步骤初始化 azd 模板、预配 Azure 资源并开始使用代码：

  • 从 GitHub 克隆快速入门存储库资产并在本地初始化模板：

    azd init --template blob-storage-quickstart-dotnet

    系统将提示输入以下信息：

    • 环境名称：此值用作 Azure Developer CLI 创建的所有 Azure 资源的前缀。 该名称在所有 Azure 订阅中必须唯一，并且长度必须介于 3 到 24 个字符之间。 名称只能包含数字和小写字母。

  • 登录到 Azure：

    azd auth login

  • 预配资源并将其部署到 Azure：

    azd up

    系统将提示输入以下信息：

    • 订阅：资源部署到的 Azure 订阅。
    • 位置 - 部署资源的 Azure 区域。

    部署可能需要几分钟时间才能完成。 azd up 命令的输出包括新创建的存储帐户的名称，稍后将需要该名称来运行代码。

运行示例代码

此时，资源将部署到 Azure，项目已准备好运行。 按照以下步骤更新代码中的存储帐户名称并运行示例控制台应用：

  • 更新存储帐户名称：导航到 src 目录并编辑 Program.cs。 查找 <storage-account-name> 占位符，并将其替换为 azd up 命令创建的存储帐户的实际名称。 保存更改。
  • 运行项目：如果使用 Visual Studio，请按 F5 生成并运行代码，并与控制台应用交互。 如果使用的是 .NET CLI，请导航到应用程序目录，使用 dotnet build 生成项目，然后使用 dotnet run 运行应用程序。
  • 观察输出：此应用在本地 data 文件夹中创建测试文件，并将其上传到存储帐户中的容器。 然后，该示例会列出容器中的 blob，并使用新名称下载文件，这样便可对新旧文件进行对比。

若要详细了解示例代码的工作原理，请参阅代码示例。

测试完代码后，请参阅清理资源部分以删除 azd up 命令创建的资源。

对象模型

Azure Blob 存储最适合存储巨量的非结构化数据。 非结构化数据并不遵循特定数据模型或定义（如文本或二进制数据）。 Blob 存储提供了三种类型的资源：

  • 存储帐户
  • 存储帐户中的容器
  • 容器中的 blob

以下图示显示了这些资源之间的关系。

Blob 存储体系结构的图示。

使用以下 .NET 类与这些资源进行交互：

  • BlobServiceClient：BlobServiceClient 类可用于操纵 Azure 存储资源和 blob 容器。
  • BlobContainerClient：BlobContainerClient 类可用于操纵 Azure 存储容器及其 blob。
  • BlobClient：BlobClient 类可用于操纵 Azure 存储 blob。

代码示例

以下部分中的示例代码片段演示如何使用适用于 .NET 的 Azure Blob 存储客户端库执行以下任务：

重要

如设置部分所述，请确保已安装正确的 NuGet 包并添加了必要的 using 语句以使代码示例能够正常工作。

注意

Azure Developer CLI 模板包含一个项目，其中包含已经存在的示例代码。 以下示例提供了示例代码的每个部分的详细信息。 该模板实现了推荐的无密码身份验证方法，如向 Azure 进行身份验证部分中所述。 连接字符串方法显示为备用方法，但未在模板中使用，也不建议用于生产代码。

向 Azure 进行身份验证并授权访问 Blob 数据

对 Azure Blob 存储的应用程序请求必须获得授权。 要在代码中实现与 Azure 服务（包括 Blob 存储）的无密码连接，推荐使用 azure-identity 客户端库提供的 DefaultAzureCredential 类。

你还可以使用帐户访问密钥授权对 Azure Blob 存储的请求。 但是，应谨慎使用此方法。 开发人员必须尽量避免在不安全的位置公开访问密钥。 具有访问密钥的任何人都可以授权针对存储帐户的请求，并且实际上有权访问所有数据。 DefaultAzureCredential 提供比帐户密钥更好的管理和安全优势，来实现无密码身份验证。 以下示例演示了这两个选项。

DefaultAzureCredential 是适用于 .NET 的 Azure 标识客户端库提供的类，可在 DefaultAzureCredential 概述中了解有关该类的详细信息。 DefaultAzureCredential 支持多种身份验证方法，并确定应在运行时使用哪种方法。 通过这种方法，你的应用可在不同环境（本地与生产）中使用不同的身份验证方法，而无需实现特定于环境的代码。

有关 DefaultAzureCredential 查找凭据的顺序和位置，可查看 Azure 标识库概述。

例如，应用可在本地开发时使用 Visual Studio 登录凭据进行身份验证。 应用在部署到 Azure 后就可以使用托管标识。 此转换不需要进行任何代码更改。

将角色分配至 Microsoft Entra 用户帐户

在本地开发时，请确保访问 Blob 数据的用户帐户具有正确的权限。 需有“存储 Blob 数据参与者”角色才能读取和写入 Blob 数据。 若要为你自己分配此角色，需要具有“用户访问管理员”角色，或者具有包含 Microsoft.Authorization/roleAssignments/write 操作的其他角色。 可使用 Azure 门户、Azure CLI 或 Azure PowerShell 向用户分配 Azure RBAC 角色。 可以在范围概述页上详细了解角色分配的可用范围。

在此方案中，你将为用户帐户分配权限（范围为存储帐户）以遵循最低权限原则。 这种做法仅为用户提供所需的最低权限，并创建更安全的生产环境。

以下示例将“存储 Blob 数据参与者”角色分配给用户帐户，该角色提供对存储帐户中 Blob 数据的读取和写入访问权限。

重要

在大多数情况下，角色分配在 Azure 中传播需要一两分钟的时间，但极少数情况下最多可能需要 8 分钟。 如果在首次运行代码时收到身份验证错误，请稍等片刻再试。

  1. 在 Azure 门户中，使用主搜索栏或左侧导航找到存储帐户。

  2. 在存储帐户概述页的左侧菜单中选择“访问控制 (IAM)”。

  3. 在“访问控制 (IAM)”页上，选择“角色分配”选项卡。

  4. 从顶部菜单中选择“+ 添加”，然后从出现的下拉菜单中选择“添加角色分配”。

    显示如何分配角色的屏幕截图。

  5. 使用搜索框将结果筛选为所需角色。 在此示例中，搜索“存储 Blob 数据参与者”并选择匹配的结果，然后选择“下一步”。

  6. 在“访问权限分配对象”下，选择“用户、组或服务主体”，然后选择“+ 选择成员”。

  7. 在对话框中，搜索 Microsoft Entra ID 用户名（通常是 user@domain 电子邮件地址），然后选中对话框底部的“选择”。

  8. 选择“查看 + 分配”转到最后一页，然后再次选择“查看 + 分配”完成该过程。

使用 DefaultAzureCredential 登录并将应用代码连接到 Azure

可按照以下步骤授权访问存储帐户中的数据：

  1. 对于本地开发，请确保使用分配了该角色的同一 Microsoft Entra 帐户进行身份验证。 可以通过常用的开发工具（如 Azure CLI 或 Azure PowerShell）进行身份验证。 可用于进行身份验证的开发工具因语言而异。

    使用以下命令通过 Azure CLI 登录到 Azure：

    az login

  2. 若要使用 DefaultAzureCredential，请将 Azure.Identity 包添加到应用程序。

    1. 在解决方案资源管理器中，右键单击项目的“依赖项”节点。 选择“管理 NuGet 包”。

    2. 在出现的窗口中，搜索 Azure.Identity。 选择相应的结果，然后选择“安装”。

      显示如何添加标识包的屏幕截图。

  3. 更新 Program.cs 代码以匹配以下示例。 在开发期间，当代码在本地工作站上运行时，它将使用已登录的优先工具的开发人员凭据向 Azure 进行身份验证，例如 Azure CLI 或 Visual Studio。

    using Azure.Storage.Blobs;
using Azure.Storage.Blobs.Models;
using System;
using System.IO;
using Azure.Identity;

// TODO: Replace <storage-account-name> with your actual storage account name
var blobServiceClient = new BlobServiceClient(
        new Uri("https://<storage-account-name>.blob.core.windows.net"),
        new DefaultAzureCredential());

  4. 请确保在 BlobServiceClient 的 URI 中更新存储帐户名称。 可以在 Azure 门户的概述页上找到存储帐户名称。

    显示如何查找存储帐户名称的屏幕截图。

    注意

    部署到 Azure 时，同样的代码可用于授权从 Azure 中运行的应用程序对 Azure 存储的请求。 但是，需要在 Azure 中的应用上启用托管标识。 然后，配置你的存储帐户以允许该托管标识进行连接。 有关在 Azure 服务之间配置此连接的详细说明，请参阅 Azure 托管应用中的身份验证教程。

创建容器

通过在 blobServiceClient 对象上调用 CreateBlobContainerAsync 方法，在存储帐户中创建新容器。 在此示例中，代码将 GUID 值追加到容器名称，以确保它是唯一的。

在 Program.cs 文件的末尾添加以下代码：

// TODO: Replace <storage-account-name> with your actual storage account name
var blobServiceClient = new BlobServiceClient(
        new Uri("https://<storage-account-name>.blob.core.windows.net"),
        new DefaultAzureCredential());

//Create a unique name for the container
string containerName = "quickstartblobs" + Guid.NewGuid().ToString();

// Create the container and return a container client object
BlobContainerClient containerClient = await blobServiceClient.CreateBlobContainerAsync(containerName);

若要详细了解如何创建容器并浏览更多代码示例，请参阅使用 .NET 创建 Blob 容器。

重要

容器名称必须为小写。 有关命名容器和 Blob 的详细信息，请参阅命名和引用容器、Blob 和元数据。

将 Blob 上传到容器中

使用 UploadAsync 将 blob 上传到容器。 示例代码将在本地数据目录中创建文本文件以上传到容器。

在 Program.cs 文件的末尾添加以下代码：

// Create a local file in the ./data/ directory for uploading and downloading
string localPath = "data";
Directory.CreateDirectory(localPath);
string fileName = "quickstart" + Guid.NewGuid().ToString() + ".txt";
string localFilePath = Path.Combine(localPath, fileName);

// Write text to the file
await File.WriteAllTextAsync(localFilePath, "Hello, World!");

// Get a reference to a blob
BlobClient blobClient = containerClient.GetBlobClient(fileName);

Console.WriteLine("Uploading to Blob storage as blob:\n\t {0}\n", blobClient.Uri);

// Upload data from the local file, overwrite the blob if it already exists
await blobClient.UploadAsync(localFilePath, true);

若要详细了解如何上传 Blob 并浏览更多代码示例，请参阅使用 .NET 上传 Blob。

列出容器中的 Blob

通过调用 GetBlobsAsync 方法，列出容器中的 blob。

在 Program.cs 文件的末尾添加以下代码：

Console.WriteLine("Listing blobs...");

// List all blobs in the container
await foreach (BlobItem blobItem in containerClient.GetBlobsAsync())
{
    Console.WriteLine("\t" + blobItem.Name);
}

若要详细了解如何列出 Blob 并浏览更多代码示例，请参阅使用 .NET 列出 Blob。

下载 blob

通过调用 DownloadToAsync 方法下载之前创建的 blob。 示例代码会将字符串“DOWNLOADED”追加到文件名，以便你可以在本地文件系统中看到这两个文件。

在 Program.cs 文件的末尾添加以下代码：

// Download the blob to a local file
// Append the string "DOWNLOADED" before the .txt extension 
// so you can compare the files in the data directory
string downloadFilePath = localFilePath.Replace(".txt", "DOWNLOADED.txt");

Console.WriteLine("\nDownloading blob to\n\t{0}\n", downloadFilePath);

// Download the blob's contents and save it to a file
await blobClient.DownloadToAsync(downloadFilePath);

若要详细了解如何下载 Blob 并浏览更多代码示例，请参阅使用 .NET 下载 Blob。

删除容器

以下代码将使用 DeleteAsync 来删除容器，以清理应用创建的资源。 该代码示例还会删除应用创建的本地文件。

在删除 blob、容器和本地文件之前，应用会调用 Console.ReadLine 以暂停并等待用户输入。 可以通过此机会验证是否已正确创建资源，然后再删除这些资源。

在 Program.cs 文件的末尾添加以下代码：

// Clean up
Console.Write("Press any key to begin clean up");
Console.ReadLine();

Console.WriteLine("Deleting blob container...");
await containerClient.DeleteAsync();

Console.WriteLine("Deleting the local source and downloaded files...");
File.Delete(localFilePath);
File.Delete(downloadFilePath);

Console.WriteLine("Done");

若要详细了解如何删除容器并浏览更多代码示例，请参阅使用 .NET 删除和还原 Blob 容器。

完成的代码

完成这些步骤后，Program.cs 文件中的代码现在应如下所示：

using Azure.Storage.Blobs;
using Azure.Storage.Blobs.Models;
using Azure.Identity;

// TODO: Replace <storage-account-name> with your actual storage account name
var blobServiceClient = new BlobServiceClient(
        new Uri("https://<storage-account-name>.blob.core.windows.net"),
        new DefaultAzureCredential());

//Create a unique name for the container
string containerName = "quickstartblobs" + Guid.NewGuid().ToString();

// Create the container and return a container client object
BlobContainerClient containerClient = await blobServiceClient.CreateBlobContainerAsync(containerName);

// Create a local file in the ./data/ directory for uploading and downloading
string localPath = "data";
Directory.CreateDirectory(localPath);
string fileName = "quickstart" + Guid.NewGuid().ToString() + ".txt";
string localFilePath = Path.Combine(localPath, fileName);

// Write text to the file
await File.WriteAllTextAsync(localFilePath, "Hello, World!");

// Get a reference to a blob
BlobClient blobClient = containerClient.GetBlobClient(fileName);

Console.WriteLine("Uploading to Blob storage as blob:\n\t {0}\n", blobClient.Uri);

// Upload data from the local file
await blobClient.UploadAsync(localFilePath, true);

Console.WriteLine("Listing blobs...");

// List all blobs in the container
await foreach (BlobItem blobItem in containerClient.GetBlobsAsync())
{
    Console.WriteLine("\t" + blobItem.Name);
}

// Download the blob to a local file
// Append the string "DOWNLOADED" before the .txt extension 
// so you can compare the files in the data directory
string downloadFilePath = localFilePath.Replace(".txt", "DOWNLOADED.txt");

Console.WriteLine("\nDownloading blob to\n\t{0}\n", downloadFilePath);

// Download the blob's contents and save it to a file
await blobClient.DownloadToAsync(downloadFilePath);

// Clean up
Console.Write("Press any key to begin clean up");
Console.ReadLine();

Console.WriteLine("Deleting blob container...");
await containerClient.DeleteAsync();

Console.WriteLine("Deleting the local source and downloaded files...");
File.Delete(localFilePath);
File.Delete(downloadFilePath);

Console.WriteLine("Done");

运行代码

此应用在本地 data 文件夹中创建测试文件，并将其上传到 Blob 存储。 然后，该示例会列出容器中的 blob，并使用新名称下载文件，这样便可对新旧文件进行对比。

如果使用 Visual Studio，请按 F5 生成并运行代码，并与控制台应用交互。 如果使用的是 .NET CLI，请导航到应用程序目录，然后生成并运行该应用程序。

dotnet build

dotnet run

应用的输出类似于以下示例（为便于阅读，省略了 GUID 值）：

Azure Blob Storage - .NET quickstart sample

Uploading to Blob storage as blob:
         https://mystorageacct.blob.core.windows.net/quickstartblobsGUID/quickstartGUID.txt

Listing blobs...
        quickstartGUID.txt

Downloading blob to
        ./data/quickstartGUIDDOWNLOADED.txt

Press any key to begin clean up
Deleting blob container...
Deleting the local source and downloaded files...
Done

在开始清理过程之前，请在“data”文件夹中查看这两个文件。 可打开它们，然后就会看到它们完全相同。

清理资源

验证文件并完成测试后，请按 Enter 键删除测试文件以及在存储帐户中创建的容器。 还可以使用 Azure CLI 来删除资源。

完成快速入门后，可以通过运行以下命令来清理已创建的资源：

azd down

系统会提示确认是否删除该资源。 输入 y 以确认。

下一步

适用于 .NET 的 Azure 存储示例和开发人员指南