使用英语阅读

通过


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

适用于 .NET 的 Azure 存储文件共享客户端库 - 版本 12.17.0

服务器版本:2021-02-12、2020-12-06、2020-10-02、 2020-08-04、2020-06-12、2020-04-08、2020-02-10、2019-12-12、2019-07-07 和 2019-02-02

Azure 文件共享在云中提供完全托管的文件共享,可通过行业标准的服务器消息块 (SMB) 协议进行访问。 Azure 文件共享可由云或者 Windows、Linux 和 macOS 的本地部署同时装载。 此外,可以使用 Azure 文件同步将 Azure 文件共享缓存在 Windows Server 上,以加快访问速度(与在数据使用位置进行访问的速度相当)。

源代码 | 包 (NuGet) | API 参考文档 | REST API 文档 | 产品文档

入门

安装包

使用 NuGet 安装适用于 .NET 的 Azure 存储文件共享客户端库:

dotnet add package Azure.Storage.Files.Shares

先决条件

需要 Azure 订阅存储帐户 才能使用此包。

若要创建新的存储帐户,可以使用 Azure 门户Azure PowerShellAzure CLI。 下面是使用 Azure CLI 的示例:

az storage account create --name MyStorageAccount --resource-group MyResourceGroup --location westus --sku Standard_LRS

关键概念

Azure 文件共享可用于:

  • 完全替换或补充传统的本地文件服务器或 NAS 设备。
  • 将应用程序“直接迁移”到需要文件共享存储文件应用程序或用户数据的云。
  • 使用共享应用程序设置、诊断共享和开发/测试/调试工具文件共享简化新的云开发项目。

线程安全

我们保证所有客户端实例方法都是线程安全的,并且相互独立, (准则) 。 这可确保重用客户端实例的建议始终是安全的,即使跨线程也是如此。

其他概念

客户端选项 | 访问响应 | 长时间运行的操作 | 处理失败 | 诊断 | 嘲笑 | 客户端生存期

示例

创建共享和上传文件

// Get a connection string to our Azure Storage account.  You can
// obtain your connection string from the Azure Portal (click
// Access Keys under Settings in the Portal Storage account blade)
// or using the Azure CLI with:
//
//     az storage account show-connection-string --name <account_name> --resource-group <resource_group>
//
// And you can provide the connection string to your application
// using an environment variable.
string connectionString = "<connection_string>";

// Name of the share, directory, and file we'll create
string shareName = "sample-share";
string dirName = "sample-dir";
string fileName = "sample-file";

// Path to the local file to upload
string localFilePath = @"<path_to_local_file>";

// Get a reference to a share and then create it
ShareClient share = new ShareClient(connectionString, shareName);
share.Create();

// Get a reference to a directory and create it
ShareDirectoryClient directory = share.GetDirectoryClient(dirName);
directory.Create();

// Get a reference to a file and upload it
ShareFileClient file = directory.GetFileClient(fileName);
using (FileStream stream = File.OpenRead(localFilePath))
{
    file.Create(stream.Length);
    file.UploadRange(
        new HttpRange(0, stream.Length),
        stream);
}

下载文件

string connectionString = "<connection_string>";

// Name of the share, directory, and file we'll download from
string shareName = "sample-share";
string dirName = "sample-dir";
string fileName = "sample-file";

// Path to the save the downloaded file
string localFilePath = @"<path_to_local_file>";

// Get a reference to the file
ShareClient share = new ShareClient(connectionString, shareName);
ShareDirectoryClient directory = share.GetDirectoryClient(dirName);
ShareFileClient file = directory.GetFileClient(fileName);

// Download the file
ShareFileDownloadInfo download = file.Download();
using (FileStream stream = File.OpenWrite(localFilePath))
{
    download.Content.CopyTo(stream);
}

遍历共享

// Connect to the share
string connectionString = "<connection_string>";
string shareName = "sample-share";
ShareClient share = new ShareClient(connectionString, shareName);

// Track the remaining directories to walk, starting from the root
var remaining = new Queue<ShareDirectoryClient>();
remaining.Enqueue(share.GetRootDirectoryClient());
while (remaining.Count > 0)
{
    // Get all of the next directory's files and subdirectories
    ShareDirectoryClient dir = remaining.Dequeue();
    foreach (ShareFileItem item in dir.GetFilesAndDirectories())
    {
        // Print the name of the item
        Console.WriteLine(item.Name);

        // Keep walking down directories
        if (item.IsDirectory)
        {
            remaining.Enqueue(dir.GetSubdirectoryClient(item.Name));
        }
    }
}

异步 API

我们完全支持同步 API 和异步 API。

string connectionString = "<connection_string>";

// Name of the share, directory, and file we'll download from
string shareName = "sample-share";
string dirName = "sample-dir";
string fileName = "sample-file";

// Path to the save the downloaded file
string localFilePath = @"<path_to_local_file>";

// Get a reference to the file
ShareClient share = new ShareClient(connectionString, shareName);
ShareDirectoryClient directory = share.GetDirectoryClient(dirName);
ShareFileClient file = directory.GetFileClient(fileName);

// Download the file
ShareFileDownloadInfo download = await file.DownloadAsync();
using (FileStream stream = File.OpenWrite(localFilePath))
{
    await download.Content.CopyToAsync(stream);
}

故障排除

所有 Azure 存储文件共享服务操作都会在失败时引发 RequestFailedException,并具有帮助ErrorCode 其中许多错误是可恢复的。

// Connect to the existing share
string connectionString = "<connection_string>";
string shareName = "sample-share";
ShareClient share = new ShareClient(connectionString, shareName);

try
{
    // Try to create the share again
    share.Create();
}
catch (RequestFailedException ex)
    when (ex.ErrorCode == ShareErrorCode.ShareAlreadyExists)
{
    // Ignore any errors if the share already exists
}

后续步骤

开始使用我们的文件示例

  1. Hello World: (或异步) 上传文件、下载文件和遍历共享
  2. 身份验证:使用连接字符串、共享密钥和共享访问签名进行身份验证。

贡献

有关生成、测试和参与此库的详细信息,请参阅 存储 CONTRIBUTING.md

本项目欢迎贡献和建议。 大多数贡献要求你同意贡献者许可协议 (CLA),并声明你有权(并且确实有权)授予我们使用你的贡献的权利。 有关详细信息,请访问 cla.microsoft.com

此项目采用了 Microsoft 开放源代码行为准则。 有关详细信息,请参阅行为准则常见问题解答,或如果有任何其他问题或意见,请与 联系。

曝光数