Разработка для службы файлов Azure с помощью .NET

Узнайте, как разрабатывать приложения .NET, использующие файлы Azure для хранения данных. Azure Files — это управляемый сервис для совместного использования файлов в облаке. Он обеспечивает полностью управляемые файловые ресурсы, доступные через протоколы, соответствующие отраслевому стандарту, такие как блок сообщений сервера (SMB) и система сетевых файлов (NFS). Azure Files также предоставляет REST API для программного доступа к файловым ресурсам.

В этой статье вы узнаете о различных подходах к разработке с помощью файлов Azure в .NET и о том, как выбрать подход, который лучше всего подходит для вашего приложения. Вы также узнаете, как создать базовое консольное приложение, которое взаимодействует с ресурсами Azure Files.

Применяется к

Модель управления	Модель выставления счетов	Уровень медиа	Избыточность	SMB	NFS
Microsoft.Storage	Настроенная версия 2	HDD (стандартный)	Локальное (LRS)
Microsoft.Storage	Настроенная версия 2	HDD (стандартный)	Зона (ZRS)
Microsoft.Storage	Настроенная версия 2	HDD (стандартный)	Гео (GRS)
Microsoft.Storage	Настроенная версия 2	HDD (стандартный)	GeoZone (GZRS)
Microsoft.Storage	Настроенная версия v1	SSD (премиум)	Локальное (LRS)
Microsoft.Storage	Настроенная версия v1	SSD (премиум)	Зона (ZRS)
Microsoft.Storage	Оплата по мере использования	HDD (стандартный)	Локальное (LRS)
Microsoft.Storage	Оплата по мере использования	HDD (стандартный)	Зона (ZRS)
Microsoft.Storage	Оплата по мере использования	HDD (стандартный)	Гео (GRS)
Microsoft.Storage	Оплата по мере использования	HDD (стандартный)	GeoZone (GZRS)

Сведения о разработке приложений .NET с помощью файлов Azure

Файлы Azure предлагают несколько способов для разработчиков .NET для доступа к данным и управления ресурсами в файлах Azure. В следующей таблице перечислены подходы, суммируется их работа и предоставляются рекомендации, когда использовать каждый из них.

Для получения общей информации об этих подходах см. Обзор разработки приложений с Azure Files.

This article focuses on working with Azure Files resources using the following approaches:

• Работа с файлами Azure с помощью System.IO: Монтирование общей папки с помощью SMB или NFS и использование пространства имен System.IO для работы с файлами и каталогами в общей папке.
• Работа с Azure Files с помощью клиентской библиотеки файловых ресурсов для .NET. Используйте клиентскую библиотеку файловых ресурсов хранилища Azure для .NET для работы с файлами и каталогами в файловом ресурсе. Эта клиентская библиотека базируется на API FileREST.
• Управление ресурсами Azure Files с помощью библиотек управления Azure Storage: Используйте библиотеки управления Azure Storage для управления файловыми ресурсами и другими ресурсами в вашем учетной записи хранения. Библиотеки управления построены на REST API поставщика ресурсов Azure Storage.

Предпосылки

• Подписка Azure — создайте бесплатную учетную запись.
• Учетная запись хранения Azure — создайте такую учетную запись.
• Последний пакет SDK для .NET для операционной системы (получение пакета SDK и не среды выполнения)

Настройка среды

В этом разделе описаны действия по подготовке консольного приложения .NET для работы с файлами Azure.

Создание проекта

Если у вас еще нет приложения .NET, создайте его с помощью Visual Studio или .NET CLI. В этой статье мы создадим консольное приложение для простоты.

Установка пакета

Если вы планируете взаимодействовать с файлами Azure с помощью System.IO пространства имен, вам не нужно устанавливать дополнительные пакеты. Пространство имен System.IO включено в состав SDK для .NET. Если вы планируете использовать клиентную библиотеку общих папок для .NET или библиотеку управления службами хранилища Azure для .NET, установите пакет с помощью NuGet.

dotnet add package Azure.Storage.Files.Shares
dotnet add package Azure.ResourceManager.Storage
dotnet add package Azure.Identity

Добавьте директивы using.

Если вы планируете использовать System.IO пространство имен, добавьте следующую директиву using в начало файла Program.cs :

using System.IO;

Если вы планируете использовать клиентскую библиотеку для работы с файловыми хранилищами для .NET, добавьте следующую директиву using в начало файла Program.cs:

using Azure.Storage.Files.Shares;

Если вы планируете использовать библиотеку управления хранилищем Azure для .NET, добавьте следующую директиву using в начало Program.cs файла:

using Azure.ResourceManager;

Чтобы использовать библиотеку удостоверений Azure для безпарольных подключений к службам Azure, добавьте следующую директиву using в начало файла Program.cs:

using Azure.Identity;

Работа с файлами Azure с помощью System.IO

Стандартные библиотеки ввода/вывода (I/O) файлов – это наиболее распространённый способ доступа и работы с ресурсами Azure Files. Когда вы монтируете общий ресурс, используя SMB или NFS, ваша операционная система перенаправляет запросы API для локальной файловой системы. Этот подход позволяет использовать стандартные библиотеки ввода-вывода файлов, например System.IO, для взаимодействия с файлами и каталогами в общей папке.

Рассмотрите возможность использования System.IO, если вашему приложению требуется:

• Совместимость приложений: Идеально подходит для бизнес-приложений с существующим кодом, который уже используется System.IO. Вам не нужно переписывать код, чтобы приложение работало с файловым хранилищем Azure.
• Простота использования:System.IO хорошо известен разработчиками и легко использовать. A key value proposition of Azure Files is that it exposes native file system APIs through SMB and NFS.

В этом разделе описано, как работать System.IO с ресурсами службы "Файлы Azure".

Для получения дополнительной информации и примеров, обратитесь к следующим ресурсам:

• Общие сведения о файлах и потоках ввода-вывода
• Распространенные задачи ввода-вывода

Mount a file share

Чтобы использовать System.IO, необходимо сначала подключить общую папку. Смотрите следующие ресурсы, чтобы получить руководство по подключению файловой системы с использованием SMB или NFS.

• Подключить общий ресурс SMB на Windows
• Монтирование SMB файлового ресурса в Linux
• Подключение NFS файлового обмена в Linux

В этой статье мы используем следующий каталог для ссылки на примонтированную SMB файловую шару в системе Windows.

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

Пример. Подключение к общей папке и перечисление каталогов с помощью System.IO

The following code example shows how to connect to a file share and list the directories in the share:

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) для файла:

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();
    }

}

Работа с данными файлов Azure с помощью клиентской библиотеки общих папок для .NET

API FileREST предоставляет программный доступ к Azure Files. Он позволяет вызывать конечные точки HTTPS для выполнения операций с файловыми хранилищами, каталогами и файлами. API FileREST разработан для обеспечения высокой масштабируемости и доступа к расширенным функциям, которые могут быть недоступны через родные протоколы. Пакет SDK Azure предоставляет клиентские библиотеки, такие как клиентская библиотека общих папок для .NET, которая основана на API FileREST.

Рассмотрите возможность использования FileREST API и клиентской библиотеки File Share, если вашему приложению требуется:

• Advanced features: Access operations and features that aren't available through native protocols.
• Настраиваемые облачные интеграции: Создавайте настраиваемые услуги с добавленной стоимостью, такие как резервное копирование, антивирус или управление данными, которые взаимодействуют непосредственно с Azure Files.
• Оптимизация производительности: Получите преимущества в производительности в сценариях с высокой нагрузкой, используя операции плоскости данных.

API FileREST представляет Azure Files как иерархию ресурсов и рекомендуется для операций, выполняемых на уровне каталога или файла. Следует отдавать предпочтение REST API поставщика ресурсного хранилища для операций, выполняемых на уровне файлового сервиса или файлового ресурса.

В этом разделе описано, как использовать клиентская библиотека общих папок для работы с ресурсами файлов Azure.

Для получения дополнительной информации и примеров, обратитесь к следующим ресурсам:

• Клиентская библиотека общих папок службы хранилища Azure для .NET
• Клиентская библиотека общих папок службы хранилища Azure для примеров .NET

Авторизация доступа и создание клиента

Чтобы подключить приложение к Azure Files, создайте объект ShareClient. Этот объект является вашей отправной точкой для работы с ресурсами Azure Files. Приведенные ниже примеры кода показывают, как создать объект ShareClient, используя различные механизмы авторизации.

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");

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

StorageSharedKeyCredential sharedKeyCredential = 
    new StorageSharedKeyCredential(accountName, accountKey);

ShareClient shareClient = new ShareClient(
    new Uri($"https://{accountName}.file.core.windows.net/{shareName}"),
    sharedKeyCredential);

string connectionString = "<connection-string>";
string shareName = "<share-name>";

ShareClient shareClient = new ShareClient(connectionString, shareName);

Чтобы узнать больше о каждом из этих механизмов авторизации, см. Выберите, как авторизовать доступ к данным файла.

Пример: Копирование файлов с использованием клиентской библиотеки File Shares

You can copy files within a file share or between file shares by using the following method:

• StartCopyAsync

Вы можете скопировать файл в конечный блоб, используя следующий метод из объекта BlobClient.

• StartCopyFromUriAsync

Следующий пример кода показывает, как скопировать файл в файл в другой файловой области:

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);

Пример: Аренда файла с использованием клиентской библиотеки File Shares

Аренда создает блокировку файла, который управляется 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, так и API FileREST, помните, что API FileREST использует лизинг для управления блокировками файлов, в то время как SMB использует блокировки файловой системы, управляемые операционной системой. Чтобы узнать больше о том, как управлять взаимодействием блокировки файлов между SMB и FileREST API, см. Управление блокировками файлов.

Пример: Создание и перечисление снимков общего доступа с использованием библиотеки клиента File Shares

Снимки общего доступа — это копии общего ресурса файла в определенный момент времени только для чтения. Вы можете создать снимок общего файлового ресурса, а затем использовать этот снимок для доступа к данным в общем ресурсе на момент создания снимка. Вы также можете перечислить все снимки в общем доступе к файлам и удалить снимки общего ресурса.

Пример кода ниже демонстрирует, как создавать снимок общего ресурса, перечислять снимки в файловом общем ресурсе и перемещаться по древу каталогов в снимке общего ресурса.

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}");
        }
    }
}

Управление ресурсами Azure Files с использованием библиотек управления Azure Storage

The Azure Storage management libraries are built on the Azure Storage resource provider REST API. Поставщик ресурсов Azure Storage — это служба на основе Azure Resource Manager, поддерживающая как декларативные (шаблоны), так и императивные (непосредственный вызов API) методы. API REST-провайдера ресурсов Azure Storage обеспечивает программный доступ к ресурсам Azure Storage, включая файловые общие ресурсы. SDK Azure предоставляет библиотеки управления, которые базируются на REST API поставщика ресурсов Azure Storage.

Рекомендуется использовать библиотеки управления для операций, выполняемых на уровне файлового сервиса или файлового обмена. В этом разделе вы узнаете, как использовать библиотеки для управления хранилищем Azure для управления ресурсами Azure Files.

Пример: Создайте файловое хранилище, используя библиотеку управления Azure Storage

Следующий пример кода показывает, как создать объект верхнего уровня ArmClient, зарегистрировать провайдера ресурсов хранилища в подписке и создать файловую шару с использованием библиотеки управления Azure Storage.

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 Storage

Приведенный ниже пример кода показывает, как перечислить файловые ресурсы и снимки в учетной записи хранения.

// 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 Files, ознакомьтесь со следующими ресурсами:

• Обзор разработки приложений с использованием Azure Files
• Именование и ссылка на ресурсы, каталоги, файлы и метаданные
• Управление блокировками файлов
• Операции с каталогами
• Операции с файлами