共用方式為

使用 .NET 開發 Azure 檔案服務

瞭解如何開發使用 Azure 檔案記憶體來儲存資料的 .NET 應用程式。 Azure 檔案服務是雲端中的受控檔案共享服務。 它提供可透過業界標準伺服器消息塊 （SMB） 和網路文件系統 （NFS） 通訊協定存取的完整受控檔案共用。 Azure 檔案服務也提供 REST API，以程式設計方式存取檔案共用。

在本文中，您將瞭解在 .NET 中使用 Azure 檔案服務開發的不同方法，以及如何選擇最符合您應用程式需求的方法。 您也會瞭解如何建立與 Azure 檔案服務資源互動的基本控制台應用程式。

適用於

管理模型 計費模型 媒體層 冗餘 中小企業 網路檔案系統 (NFS)
Microsoft 儲存服務 已佈建的 v2 HDD （標準） 本地 (LRS) 是 否
Microsoft 儲存服務 已佈建的 v2 HDD （標準） 區域 (ZRS) 是 否
Microsoft 儲存服務 已佈建的 v2 HDD （標準） 異地 (GRS) 是 否
Microsoft 儲存服務 已佈建的 v2 HDD （標準） GeoZone （GZRS） 是 否
Microsoft 儲存服務 已佈建的 v1 SSD （進階版） 本地 (LRS) 是 否
Microsoft 儲存服務 已佈建的 v1 SSD （進階版） 區域 (ZRS) 是 否
Microsoft 儲存服務 隨用隨付 HDD （標準） 本地 (LRS) 是 否
Microsoft 儲存服務 隨用隨付 HDD （標準） 區域 (ZRS) 是 否
Microsoft 儲存服務 隨用隨付 HDD （標準） 異地 (GRS) 是 否
Microsoft 儲存服務 隨用隨付 HDD （標準） GeoZone （GZRS） 是 否

關於使用 Azure 檔案服務進行 .NET 應用程式開發

Azure 檔案服務提供數種方式，讓 .NET 開發人員存取數據及管理 Azure 檔案服務中的資源。 下表列出這些方法、摘要說明其運作方式，並提供使用每個方法時機的指引：

方法 運作方式 使用時機
標準檔案輸入/輸出函式庫 透過使用 SMB 或 NFS 掛載的 Azure 檔案共用使用作業系統層級的 API 呼叫。 使用 SMB/NFS 掛接檔案共用時，您可以將檔案 I/O 程式庫用於程式設計語言或架構，例如 System.IO 適用於 .NET。 您有具有使用標準檔案 I/O 之現有程式代碼的企業營運應用程式，而且您不想要重寫程式代碼，讓應用程式使用 Azure 檔案共用。
FileREST API 直接呼叫 HTTPS 端點，以與儲存在 Azure 檔案服務中的數據互動。 提供檔案共用資源的程序設計控制。 Azure SDK 提供以 FileREST API 為基礎的檔案共用用戶端連結庫 （Azure.Storage.Files.Shares），可讓您透過熟悉的 .NET 程式設計語言範例與 FileREST API 作業互動。 您正在為客戶建置增值的雲端服務和應用程式，而您想要使用無法透過 System.IO提供的進階功能。
記憶體資源提供者 REST API 使用 Azure Resource Manager （ARM） 來管理記憶體帳戶和檔案共用。 針對各種資源管理作業呼叫 REST API 端點。 您的應用程式或服務必須執行資源管理工作，例如建立、刪除或更新記憶體帳戶或檔案共用。

如需這些方法的一般資訊，請參閱 使用 Azure 檔案服務開發應用程式的概觀。

本文著重於使用下列方法使用 Azure 檔案服務資源：

先決條件

設定您的環境

本節將逐步引導您完成準備 .NET 控制台應用程式以使用 Azure 檔案服務的步驟。

建立專案

如果您還沒有 .NET 應用程式，請使用 Visual Studio 或 .NET CLI 建立一個。 在本文中，我們會為簡單起見建立控制台應用程式。

  1. 啟動 Visual Studio 並選取 [建立新專案]。 或者，如果您是在 Visual Studio 中，請流覽至 [ 檔案>新>專案]。
  2. 在對話框視窗中，選擇 [適用於 C# 的 控制台應用程式 ]，然後選取 [ 下一步]。
  3. 輸入項目的名稱、保留預設值，然後選取 [ 下一步]。
  4. 針對 [Framework]，選取最新安裝的 .NET 版本。 保留其他預設值，然後選取 [ 建立]。

安裝套件

如果您打算使用 System.IO 命名空間與 Azure 檔案服務互動，則不需要安裝任何其他套件。 命名空間 System.IO 隨附於 .NET SDK。 如果您打算使用適用於 .NET 的檔案共用用戶端連結庫或適用於 .NET 的 Azure 記憶體管理連結庫，請使用 NuGet 安裝套件。

  1. 在 [方案總管] 中，以滑鼠右鍵按一下您的專案並選擇 [管理 NuGet 套件]。

  2. 在 [NuGet 套件管理員] 中，選取 [瀏覽]。 然後搜尋並選擇適當的套件，然後選取 [ 安裝]。 針對 [檔案共用] 用戶端連結庫，選擇 [Azure.Storage.Files.Shares]。 針對 Azure 儲存管理庫，選擇 Azure.ResourceManager.Storage。 針對無密碼連線所需的 Azure 身分識別連結庫，請選擇 [Azure.Identity]。

    此步驟會安裝套件及其相依性。

新增 using 指示詞

如果您打算使用 System.IO 命名空間，請將下列 using 指示詞新增至 Program.cs 檔案頂端：

using System.IO;

如果您打算使用適用於 .NET 的檔案共享用戶端連結庫，請將下列 using 指示詞新增至 Program.cs 檔案頂端：

using Azure.Storage.Files.Shares;

如果您打算使用適用於 .NET 的 Azure 記憶體管理連結庫，請將下列 using 指示詞新增至 Program.cs 檔案頂端：

using Azure.ResourceManager;

若要使用 Azure 身分識別連結庫進行無密碼連線至 Azure 服務，請將下列 using 指示詞新增至 Program.cs 檔案頂端：

using Azure.Identity;

使用 System.IO 與 Azure 檔案服務搭配使用

標準檔案 I/O 連結庫是存取和使用 Azure 檔案資源最常見的方式。 當您使用 SMB 或 NFS 掛接檔案共用時，作業系統會重新導向對本機檔案系統的 API 要求。 此方法可讓您使用標準檔案 I/O 連結庫，例如 System.IO，與共用中的檔案和目錄互動。

當您的應用程式需要時，請考慮使用 System.IO ：

  • 應用程式相容性： 適用於已使用 System.IO的現有程式代碼的企業營運應用程式。 您不需要重寫程式代碼，應用程式即可使用 Azure 檔案共用。
  • 易於使用：System.IO 開發人員很熟悉，而且容易使用。 Azure 檔案服務的重要價值主張是，它會透過 SMB 和 NFS 公開原生文件系統 API。

在本節中，您將瞭解如何使用 System.IO 來處理 Azure 檔案服務資源。

如需詳細資訊和範例，請參閱下列資源：

掛接檔案共用

若要使用 System.IO，必須先掛接檔案共用。 如需如何使用SMB或NFS掛接檔案共用的指引，請參閱下列資源：

在本文中，我們會使用下列路徑指稱 Windows 上掛載的 SMB 檔案共用：

string fileSharePath = @"Z:\file-share";

範例：使用 System.IO 連線至檔案共享並列舉目錄

下列程式代碼範例示範如何連線到檔案共享，並列出共用中的目錄：

using System.IO;

string fileSharePath = @"Z:\file-share";

EnumerateDirectories(@"Z:\file-share");

static void EnumerateDirectories(string path)
{
    try
    {
        List<string> dirs = new List<string>(Directory.EnumerateDirectories(path));

        foreach (var dir in dirs)
        {
            Console.WriteLine($"{dir.Substring(dir.LastIndexOf(Path.DirectorySeparatorChar) + 1)}");
        }
        Console.WriteLine($"{dirs.Count} directories found.");
    }
    catch (UnauthorizedAccessException ex)
    {
        Console.WriteLine(ex.Message);
    }
    catch (PathTooLongException ex)
    {
        Console.WriteLine(ex.Message);
    }
}

範例：使用 System.IO 寫入檔案共用中的檔案

下列程式代碼範例示範如何使用 類別撰寫和附加文字 File ：

using System.IO;

string fileSharePath = @"Z:\file-share";

WriteToFile(fileSharePath, "test.txt");

static void WriteToFile(string fileSharePath, string fileName)
{
    string textToWrite = "First line" + Environment.NewLine;
    string filePath = Path.Combine(fileSharePath, fileName);
    
    File.WriteAllText(filePath, textToWrite);

    string[] textToAppend = { "Second line", "Third line" };
    File.AppendAllLines(filePath, textToAppend);
}

範例：使用 System.IO 鎖定檔案共用中的檔案

掛接檔案共用的SMB用戶端可以使用文件系統鎖定機制來管理共用檔案的存取權。

下列程式代碼範例示範如何在共用模式設定為 None的檔案共享中鎖定檔案。 此共用模式會拒絕共用目前檔案，直到檔案關閉為止。

using System.IO;

string fileSharePath = @"Z:\file-share";

LockFile(Path.Combine(fileSharePath, "test.txt"));

static void LockFile(string filePath)
{
    try
    {
        using (FileStream fs = new FileStream(filePath, FileMode.Open, FileAccess.ReadWrite, FileShare.None))
        {
            Console.WriteLine("File locked.");

            // Do something with file, press Enter to close the stream and release the lock
            Console.ReadLine();

            fs.Close();
            Console.WriteLine("File closed.");
        }
    }
    catch (IOException ex)
    {
        Console.WriteLine(ex.Message);
    }
}

同時使用SMB和FileREST API時，請記住FileREST API會使用 租用 來管理檔案鎖定，而SMB則使用由作系統管理的文件系統鎖定。 若要深入瞭解管理 SMB 與 FileREST API 之間的檔案鎖定互動，請參閱 管理檔案鎖定。

範例：使用 System.IO 列舉檔案 ACL

下列程式代碼範例示範如何列舉檔案的存取控制清單 （ACL）：

using System.IO;
using System.Security.AccessControl;

string fileSharePath = @"Z:\file-share";
string fileName = "test.txt";
string filePath = Path.Combine(fileSharePath, fileName);

EnumerateFileACLs(filePath);

static void EnumerateFileACLs(string filePath)
{
    FileInfo fileInfo = new FileInfo(filePath);

    // For directories, use DirectorySecurity instead of FileSecurity
    FileSecurity fSecurity = FileSystemAclExtensions.GetAccessControl(fileInfo);

    // List all access rules for the file
    foreach (FileSystemAccessRule rule in fSecurity.GetAccessRules(true, true, typeof(System.Security.Principal.NTAccount)))
    {
        Console.WriteLine($"Identity: {rule.IdentityReference.Value}");
        Console.WriteLine($"Access Control Type: {rule.AccessControlType}");
        Console.WriteLine($"File System Rights: {rule.FileSystemRights}");
        Console.WriteLine();
    }

}

使用適用於 .NET 的檔案共用用戶端程式庫處理 Azure 檔案儲存體資料

FileREST API 可讓您以程式設計方式存取 Azure 檔案服務。 它可讓您呼叫 HTTPS 端點，以在檔案共享、目錄和檔案上執行作業。 FileREST API 是針對可能無法透過原生通訊協定使用的高延展性和進階功能所設計。 Azure SDK 提供建置在 FileREST API 上的用戶端連結庫，例如適用於 .NET 的檔案共用用戶端連結庫。

如果您的應用程式需要，請考慮使用 FileREST API 和檔案共用用戶端連結庫：

  • 進階功能： 存取無法透過原生通訊協定使用的各項操作與功能。
  • 自定義雲端整合： 建置與 Azure 檔案服務直接互動的自定義增值服務，例如備份、防病毒軟體或數據管理。
  • 效能優化： 使用資料平面操作，在大規模情境中受益於效能優勢。

FileREST API 會將 Azure 檔案服務模型為資源階層，並建議用於在 目錄 或 檔案 層級執行的作業。 您應該偏好 記憶體資源提供者 REST API ，以用於在 檔案服務 或 檔案共用 層級執行的作業。

在本節中，您將瞭解如何使用檔案共用用戶端連結庫來處理 Azure 檔案服務資源。

如需詳細資訊和範例，請參閱下列資源：

授權存取並建立用戶端

若要將應用程式連線至 Azure 檔案服務，請建立 ShareClient 物件。 此物件是您使用 Azure 檔案服務資源的起點。 下列程式代碼範例示範如何使用不同的授權機制來建立 ShareClient 物件。

若要使用 Microsoft Entra ID 進行授權，您必須使用安全性主體。 您需要的安全性主體類型取決於您的應用程式執行位置。 請使用下表作為指南。

應用程式的執行位置 安全性主體 指導
本機電腦 (開發和測試) 服務主體 若要了解如何註冊應用程式、設定 Microsoft Entra 群組、指派角色及設定環境變數，請參閱 使用開發人員服務主體授權存取
本機電腦 (開發和測試) 使用者身分識別 若要了解如何設定 Microsoft Entra 群組、指派角色並登入 Azure，請參閱 使用開發人員認證授權存取
裝載於 Azure 中 受管理的識別 若要了解如何啟用受控識別並指派角色，請參閱 使用受控識別從 Azure 裝載的應用程式授權存取
託管在 Azure 外部 (例如內部部署的應用程式) 服務主體 若要了解如何註冊應用程式、指派角色及設定環境變數，請參閱 使用應用程式服務主體從内部部署應用程式授權存取

若要使用本文中的程式代碼範例，請將 Azure RBAC 內建角色 記憶體檔案數據特殊許可權參與者 指派給安全性主體。 不論已設定的檔案/目錄層級NTFS許可權為何，此角色都會針對所有已設定的記憶體帳戶，提供共用中所有資料的完整讀取、寫入、修改 ACL 和刪除存取權。 如需詳細資訊，請參閱 透過 REST 使用 Microsoft Entra ID 搭配 Azure 檔案記憶體 OAuth 存取 Azure 檔案共用。

使用 DefaultAzureCredential 授權存取

授權存取權並連線到 Azure 檔案服務的簡單且安全方式是建立 DefaultAzureCredential 實例來取得 OAuth 令牌。 然後，您可以使用該認證來建立 ShareClient 物件。

下列範例會首先建立一個經 ShareClient 授權的 DefaultAzureCredential 物件，然後再建立一個 ShareDirectoryClient 物件以處理共用中的目錄：

using Azure.Identity;
using Azure.Storage.Files.Shares;
using Azure.Storage.Files.Shares.Models;

// ...

string accountName = "<account-name>";
string shareName = "<share-name>";

ShareClientOptions options = new()
{
    AllowSourceTrailingDot = true,
    AllowTrailingDot = true,
    ShareTokenIntent = ShareTokenIntent.Backup,
};
ShareClient shareClient = new(
   new Uri($"https://{accountName}.file.core.windows.net/{shareName}"),
   new DefaultAzureCredential(),
   options);

ShareDirectoryClient directoryClient = shareClient.GetDirectoryClient("sample-directory");

如果您確切知道要用來驗證使用者的認證類型，則可使用適用於 .NET 的 Azure 身分識別用戶端程式庫中的其他類別來取得 OAuth 權杖。 這些類別衍生自 TokenCredential 類別。

若要深入瞭解每個授權機制，請參閱 選擇如何授權檔案數據的存取權。

範例：使用檔案共享用戶端連結庫複製檔案

您可以使用下列方法，在檔案共用內或檔案共享之間複製檔案：

您可以從 BlobClient 物件使用下列方法，將檔案複製到目的地 Blob：

下列程式代碼範例示範如何將檔案複製到另一個檔案共用中的檔案：

using Azure.Core;
using Azure.Identity;
using Azure.Storage.Files.Shares;
using Azure.Storage.Files.Shares.Models;

string accountName = "<account-name>";
string srcShareName = "src-file-share";
string destShareName = "dest-file-share";
string srcFilePath = "src/path/to/file";
string destFilePath = "dest/path/to/file";

TokenCredential tokenCredential = new DefaultAzureCredential();

ShareClientOptions options = new()
{
    ShareTokenIntent = ShareTokenIntent.Backup,
};

ShareFileClient srcShareFileClient = new(
    new Uri($"https://{accountName}.file.core.windows.net/{srcShareName}/{srcFilePath}"),
    tokenCredential,
    options);

ShareFileClient destShareFileClient = new(
    new Uri($"https://{accountName}.file.core.windows.net/{destShareName}/{destFilePath}"),
    tokenCredential,
    options);

// Copy the file from the source share to the destination share

await destShareFileClient.StartCopyAsync(srcShareFileClient.Uri);

範例：使用檔案共享用戶端連結庫租用檔案

租用會透過租用識別碼對 Azure 所管理的檔案建立鎖定。 租用提供一種機制，可協調存取分散式系統中多個客戶端的檔案。 檔案的租用會提供獨佔寫入和刪除存取權。 若要深入瞭解租用狀態和動作，請參閱 租用檔案。

下列程式代碼範例示範如何建立租用用戶端、取得檔案的無限持續時間租用，以及釋放租用：

using Azure.Core;
using Azure.Identity;
using Azure.Storage.Files.Shares;
using Azure.Storage.Files.Shares.Models;
using Azure.Storage.Files.Shares.Specialized;

string accountName = "<account-name>";
string shareName = "sample-file-share";
string filePath = "path/to/file";

TokenCredential tokenCredential = new DefaultAzureCredential();

ShareClientOptions options = new()
{
    ShareTokenIntent = ShareTokenIntent.Backup,
};

ShareFileClient fileClient = new(
    new Uri($"https://{accountName}.file.core.windows.net/{shareName}/{filePath}"),
    tokenCredential,
    options);

ShareLeaseClient leaseClient = fileClient.GetShareLeaseClient();

// Acquire a lease on the source file
await leaseClient.AcquireAsync(duration: ShareLeaseClient.InfiniteLeaseDuration);

// Do something with the file

// Release the lease
await leaseClient.ReleaseAsync();

同時使用SMB和FileREST API時，請記住FileREST API會使用 租用 來管理檔案鎖定，而SMB則使用由作系統管理的文件系統鎖定。 若要深入瞭解管理 SMB 與 FileREST API 之間的檔案鎖定互動，請參閱 管理檔案鎖定。

範例：使用檔案共享用戶端連結庫建立及列出共用快照集

共用快照集是檔案共用在某個時間點的唯讀複本。 您可以為檔案共用建立快照集，然後使用該快照集存取當時共用中的資料。 您也可以列出檔案共用中的所有快照集，以及刪除共用快照集。

下列程式代碼範例示範如何建立共用快照集、列出檔案共用中的快照集，以及周遊共用快照集中的目錄樹狀結構：

using Azure.Storage.Files.Shares;
using Azure.Storage.Files.Shares.Models;

string connectionString = "<connection-string>";

ShareServiceClient shareServiceClient = new ShareServiceClient(connectionString);
ShareClient shareClient = shareServiceClient.GetShareClient("sample-file-share");

// Create a snapshot

ShareSnapshotInfo snapshotInfo = await shareClient.CreateSnapshotAsync();
Console.WriteLine($"Snapshot created: {snapshotInfo.Snapshot}");

// List snapshots in a share

await foreach (ShareItem shareItem in shareServiceClient.GetSharesAsync(ShareTraits.All, ShareStates.Snapshots))
{
    if (shareItem.Snapshot != null)
    {
        Console.WriteLine($"Share: {shareItem.Name} (Snapshot: {shareItem.Snapshot})");
    }
}

// List directories and files in a share snapshot

string snapshotTimestamp = snapshotInfo.Snapshot.ToString();
ShareClient shareSnapshot = shareClient.WithSnapshot(snapshotTimestamp);
ShareDirectoryClient rootDir = shareSnapshot.GetRootDirectoryClient();

await ListDirectoryTreeAsync(rootDir);

static async Task ListDirectoryTreeAsync(ShareDirectoryClient directory)
{
    await foreach (ShareFileItem fileItem in directory.GetFilesAndDirectoriesAsync())
    {
        if (fileItem.IsDirectory)
        {
            Console.WriteLine($"Directory: {fileItem.Name}");
            await ListDirectoryTreeAsync(directory.GetSubdirectoryClient(fileItem.Name));
        }
        else
        {
            Console.WriteLine($"File: {fileItem.Name}");
        }
    }
}

附註

OAuth 令牌，例如使用 DefaultAzureCredential時取得的令牌，不允許在檔案共享層級進行數據平面作業。 若要使用共用快照集，用戶端對象必須使用帳戶密鑰獲得授權。 在此程式 ShareClient 代碼範例中建立的物件會使用連接字串，其中包含帳戶密鑰。

儲存帳戶金鑰或連接字串會產生安全性風險。 只有在無法使用 Microsoft Entra 驗證時，才應該使用它們。 若要深入瞭解如何在 Azure Key Vault 中安全地儲存帳戶密鑰，請參閱 關於 Azure Key Vault 受控記憶體帳戶密鑰。

使用 Azure 記憶體管理連結庫管理 Azure 檔案服務資源

Azure 記憶體管理連結庫建置在 Azure 記憶體資源提供者 REST API 上。 Azure 記憶體資源提供者是以 Azure Resource Manager 為基礎的服務，同時支援宣告式（範本）和命令式（API 呼叫）方法。 Azure 記憶體資源提供者 REST API 會以程式設計方式存取 Azure 記憶體資源，包括檔案共用。 Azure SDK 提供以 Azure 記憶體資源提供者 REST API 為基礎的管理連結庫。

建議管理連結庫用於在 檔案服務 或 檔案共享 層級執行的作業。 在本節中，您將瞭解如何使用 Azure 記憶體管理連結庫來管理 Azure 檔案服務資源。

範例：使用 Azure 記憶體管理連結庫建立檔案共用

下列程式代碼範例示範如何建立最上層 ArmClient 物件、向訂用帳戶註冊記憶體資源提供者，以及使用 Azure 記憶體管理連結庫建立檔案分享：

using Azure;
using Azure.Core;
using Azure.Identity;
using Azure.ResourceManager;
using Azure.ResourceManager.Resources;
using Azure.ResourceManager.Storage;

ArmClient armClient = new ArmClient(new DefaultAzureCredential());

// Create a resource identifier, then get the subscription resource
ResourceIdentifier resourceIdentifier = new($"/subscriptions/<subscription-id>");
SubscriptionResource subscription = armClient.GetSubscriptionResource(resourceIdentifier);

ResourceProviderResource resourceProvider =
    await subscription.GetResourceProviderAsync("Microsoft.Storage");

// Check the registration state of the resource provider and register, if needed
if (resourceProvider.Data.RegistrationState == "NotRegistered")
    resourceProvider.Register();

// Get a resource group
ResourceGroupResource resourceGroup = await subscription.GetResourceGroupAsync("<resource-group-name>");

// Get a collection of storage account resources
StorageAccountCollection accountCollection = resourceGroup.GetStorageAccounts();

// Get a specific storage account resource
StorageAccountResource storageAccount = await accountCollection.GetAsync("<storage-account-name>");

// Get a file service resource for the storage account
FileServiceResource fileService = storageAccount.GetFileService();

// Create a new file share (or update if it already exists)
ArmOperation <FileShareResource> fileShareOperation = await fileService
    .GetFileShares()
    .CreateOrUpdateAsync(WaitUntil.Completed, "sample-file-share", new FileShareData()
    {
        ShareQuota = 1024,
        // Add file share properties here
    });

// Get the file share resource
FileShareResource fileShare = fileShareOperation.Value;

您可以使用 FileShareData 類別來設定檔案共享屬性。 上一個範例示範如何設定 ShareQuota 屬性。

附註

若要執行註冊作業，您需要下列 Azure RBAC 動作的許可權：Microsoft.Storage/register/action。 此權限包含在參與者和擁有者內建角色中。

範例：使用 Azure 儲存體管理程式庫列出檔案共用和快照集

下列程式代碼範例示範如何在記憶體帳戶中列出檔案共用和快照集：

// Iterate over a collection of file shares and list them along with any snapshots
string expand = "snapshots";
await foreach (FileShareResource shareResource in fileService.GetFileShares().GetAllAsync(expand: expand))
{
    // Call operations on the file share resource

    // For this demo, print out the resource name and snapshot information
    FileShareData resourceData = shareResource.Data;
    Console.WriteLine($"Resource name: {resourceData.Name}");
    if (resourceData.SnapshotOn.HasValue)
    {
        Console.WriteLine($"Snapshot: {resourceData.SnapshotOn}");
    }
}

相關內容

如需使用 Azure 檔案服務開發的詳細資訊，請參閱下列資源：