Ontwikkelen voor Azure Files met .NET

Meer informatie over het ontwikkelen van .NET-toepassingen die gebruikmaken van Azure Files om gegevens op te slaan. Azure Files is een beheerde bestandsshareservice in de cloud. Het biedt volledig beheerde bestandsshares die toegankelijk zijn via de industriestandaard SMB-protocollen (Server Message Block) en Network File System (NFS). Azure Files biedt ook een REST API voor programmatische toegang tot bestandsshares.

In dit artikel leert u meer over de verschillende benaderingen voor het ontwikkelen met Azure Files in .NET en hoe u de aanpak kiest die het beste past bij de behoeften van uw app. U leert ook hoe u een eenvoudige console-app maakt die communiceert met Azure Files-resources.

Van toepassing op

Beheermodel	Betaalmodel	Medianiveau	Redundantie	Kleine en Middelgrote Ondernemingen (SMB)	Network File System (NFS)
Microsoft.Opslag	Geconfigureerd v2	HDD (standaard)	Lokaal (LRS)
Microsoft.Opslag	Geconfigureerd v2	HDD (standaard)	Zone (ZRS)
Microsoft.Opslag	Geconfigureerd v2	HDD (standaard)	Aardrijkskunde (GRS)
Microsoft.Opslag	Geconfigureerd v2	HDD (standaard)	GeoZone (GZRS)
Microsoft.Opslag	Geconfigureerd v1	SSD (hoogwaardig)	Lokaal (LRS)
Microsoft.Opslag	Geconfigureerd v1	SSD (hoogwaardig)	Zone (ZRS)
Microsoft.Opslag	Betalen per gebruik	HDD (standaard)	Lokaal (LRS)
Microsoft.Opslag	Betalen per gebruik	HDD (standaard)	Zone (ZRS)
Microsoft.Opslag	Betalen per gebruik	HDD (standaard)	Aardrijkskunde (GRS)
Microsoft.Opslag	Betalen per gebruik	HDD (standaard)	GeoZone (GZRS)

Over .NET-app-ontwikkeling met Azure Files

Azure Files biedt verschillende manieren voor .NET-ontwikkelaars voor toegang tot gegevens en het beheren van resources in Azure Files. De volgende tabel bevat de benaderingen, geeft een overzicht van hoe ze werken en biedt richtlijnen voor het gebruik van elke benadering:

Zie Overzicht van de ontwikkeling van toepassingen met Azure Files voor algemene informatie over deze benaderingen.

Dit artikel is gericht op het werken met Azure Files-resources met behulp van de volgende methoden:

• Werk met Azure Files met behulp van System.IO: Koppel een bestandsshare met behulp van SMB of NFS en gebruik de System.IO naamruimte om te werken met bestanden en mappen in de share.
• Werk met Azure Files met behulp van de clientbibliotheek bestandsshares voor .NET: gebruik de Azure Storage-clientbibliotheek voor bestandsshares voor .NET om te werken met bestanden en mappen in een bestandsshare. Deze clientbibliotheek bouwt voort op de FileREST-API.
• Azure Files-resources beheren met behulp van de Azure Storage-beheerbibliotheken: gebruik de Azure Storage-beheerbibliotheken om bestandsshares en andere resources in uw opslagaccount te beheren. De beheerbibliotheken zijn gebaseerd op de REST API van de Azure Storage-resourceprovider.

Vereiste voorwaarden

• Azure-abonnement: u kunt een gratis abonnement nemen
• Azure Storage-account: maak een opslagaccount
• Nieuwste .NET SDK voor uw besturingssysteem (haal de SDK op en niet de runtime)

Uw omgeving instellen

In deze sectie wordt u stapsgewijs begeleid bij het voorbereiden van een .NET-console-app voor gebruik met Azure Files.

Het project maken

Als u nog geen .NET-app hebt, maakt u er een met Visual Studio of de .NET CLI. In dit artikel maken we een console-app voor het gemak.

Het pakket installeren

Als u van plan bent om te communiceren met Azure Files met behulp van de System.IO naamruimte, hoeft u geen extra pakketten te installeren. De System.IO naamruimte is opgenomen in de .NET SDK. Als u van plan bent om de clientbibliotheek voor bestandsshares voor .NET of de Azure Storage-beheerbibliotheek voor .NET te gebruiken, installeert u het pakket met nuGet.

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

Gebruiksrichtlijnen toevoegen

Als u van plan bent om de System.IO naamruimte te gebruiken, voegt u de volgende instructie toe aan het begin van uw Program.cs-bestand :

using System.IO;

Als u van plan bent om de clientbibliotheek voor bestandsdeling in .NET te gebruiken, voegt u de volgende instructie toe aan het begin van uw Program.cs-bestand:

using Azure.Storage.Files.Shares;

Als u van plan bent om de Azure Storage-beheerbibliotheek voor .NET te gebruiken, voegt u de volgende instructie toe aan het begin van uw Program.cs-bestand :

using Azure.ResourceManager;

Als u de Azure Identity-bibliotheek wilt gebruiken voor verbindingen zonder wachtwoord met Azure-services, voegt u de volgende instructie toe aan het begin van uw Program.cs-bestand :

using Azure.Identity;

Werken met Azure Files met behulp van System.IO

Standaard-I/O-bibliotheken voor bestanden zijn de meest voorkomende manier om azure Files-resources te openen en te gebruiken. Wanneer u een bestandsdeling koppelt met behulp van SMB of NFS, leidt uw besturingssysteem API-aanvragen om naar het lokale bestandssysteem. Met deze methode kunt u standaard I/O-bibliotheken voor bestanden gebruiken, zoals System.IO, om te communiceren met bestanden en mappen in de share.

Overweeg het gebruik van System.IO wanneer uw app het vereist.

• App-compatibiliteit: Ideaal voor Line-Of-Business-apps met bestaande code die al wordt gebruikt System.IO. U hoeft code niet opnieuw te schrijven om de app te laten werken met een Azure-bestandsshare.
• Gebruiksgemak:System.IO is bekend door ontwikkelaars en eenvoudig te gebruiken. Een belangrijke waardepropositie van Azure Files is dat het systeemeigen bestandssysteem-API's beschikbaar maakt via SMB en NFS.

In dit gedeelte leert u hoe u System.IO kunt gebruiken om te werken met Azure Files-resources.

Zie de volgende bronnen voor meer informatie en voorbeelden:

• Overzicht van bestands- en stream-I/O
• Algemene I/O-taken

Een bestandsshare koppelen

Als u wilt gebruiken System.IO, moet u eerst een bestandsshare koppelen. Zie de volgende bronnen voor hulp bij het koppelen van een bestandsshare met behulp van SMB of NFS:

• Een SMB-bestandsdeling koppelen op Windows
• Een SMB-bestandsdeling koppelen in Linux
• Een NFS-bestandsdeling koppelen op Linux

In dit artikel gebruiken we het volgende pad om te verwijzen naar een gekoppelde SMB-bestandsshare in Windows:

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

Voorbeeld: Verbinding maken met een bestandsshare en mappen inventariseren met behulp van System.IO

In het volgende codevoorbeeld ziet u hoe u verbinding maakt met een bestandsshare en hoe u de mappen in de share weergeeft:

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

Voorbeeld: Schrijven naar een bestand in een bestandsshare met behulp van System.IO

In het volgende codevoorbeeld ziet u hoe u tekst schrijft en toevoegt met de File klasse:

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

Voorbeeld: Een bestand in een bestandsshare vergrendelen met behulp van System.IO

SMB-clients die bestandsshares koppelen, kunnen gebruikmaken van mechanismen voor het vergrendelen van het bestandssysteem om de toegang tot gedeelde bestanden te beheren.

In het volgende codevoorbeeld ziet u hoe u een bestand in een bestandsshare vergrendelt met de modus Delen ingesteld op None. Deze sharemodus weigert het delen van het huidige bestand totdat het bestand is gesloten.

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

Wanneer u zowel SMB als de FileREST-API gebruikt, moet u er rekening mee houden dat de FileREST-API leases gebruikt om bestandsvergrendelingen te beheren, terwijl SMB gebruikmaakt van bestandssysteemvergrendelingen die worden beheerd door het besturingssysteem. Zie Bestandsvergrendelingen beheren voor meer informatie over het beheren van interacties tussen SMB en de FileREST-API.

Voorbeeld: ACL's voor bestanden inventariseren met behulp van System.IO

In het volgende codevoorbeeld ziet u hoe u toegangsbeheerlijsten (ACL's) voor een bestand opsommen:

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

}

Werken met Azure Files-gegevens met behulp van de clientbibliotheek voor bestandsshares voor .NET

De FileREST-API biedt programmatische toegang tot Azure Files. Hiermee kunt u HTTPS-eindpunten aanroepen om bewerkingen uit te voeren op bestandsshares, mappen en bestanden. De FileREST-API is ontworpen voor hoge schaalbaarheid en geavanceerde functies die mogelijk niet beschikbaar zijn via systeemeigen protocollen. De Azure SDK biedt clientbibliotheken, zoals de clientbibliotheek voor bestandsdeling in .NET, die zijn gebaseerd op de FileREST-API.

Overweeg het gebruik van de FileREST-API en de bestandsshare-clientbibliotheek als uw toepassing vereist:

• Geavanceerde functies: Toegang tot bewerkingen en functies die niet beschikbaar zijn via systeemeigen protocollen.
• Aangepaste cloudintegraties: Bouw aangepaste services met toegevoegde waarde, zoals back-up, antivirus of gegevensbeheer, die rechtstreeks met Azure Files communiceren.
• Optimalisatie van prestaties: Profiteer van prestatievoordelen in grootschalige scenario's met behulp van gegevensvlakbewerkingen.

De FileREST-API modelleert Azure Files als een hiërarchie van resources en wordt aanbevolen voor bewerkingen die worden uitgevoerd op map - of bestandsniveau . Geef de voorkeur aan de REST API van de opslagresourceprovider voor bewerkingen die worden uitgevoerd op het niveau van de bestandsservice of bestandsshare .

In deze sectie leert u hoe u de clientbibliotheek voor bestandsshares gebruikt om te werken met Azure Files-resources.

Zie de volgende bronnen voor meer informatie en voorbeelden:

• Clientbibliotheek voor Azure Storage-bestandsshares voor .NET
• Clientbibliotheek voor Azure Storage-bestandsshares voor .NET-voorbeelden

Toegang autoriseren en een client maken

Als u een app wilt verbinden met Azure Files, maakt u een ShareClient object. Dit object is het uitgangspunt voor het werken met Azure Files-resources. In de volgende codevoorbeelden ziet u hoe u een ShareClient object maakt met behulp van verschillende autorisatiemechanismen.

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

Zie Kiezen hoe u toegang tot bestandsgegevens kunt autoriseren voor meer informatie over elk van deze autorisatiemechanismen.

Voorbeeld: Bestanden kopiëren met behulp van de clientbibliotheek voor bestandsdeling

U kunt bestanden in een bestandsshare of tussen bestandsshares kopiëren met behulp van de volgende methode:

• StartCopyAsync

U kunt een bestand naar een doel-blob kopiëren met behulp van de volgende methode uit een BlobClient object:

• StartCopyFromUriAsync

In het volgende codevoorbeeld ziet u hoe u een bestand kopieert naar een bestand in een andere bestandsshare:

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

Voorbeeld: Een bestand leasen met behulp van de bibliotheek van de client voor bestandsdeling.

Een lease maakt een vergrendeling op een bestand dat wordt beheerd door Azure via een lease-id. De lease biedt een mechanisme voor het coördineren van de toegang tot bestanden op meerdere clients in een gedistribueerd systeem. Een lease op een bestand biedt exclusieve schrijf- en verwijdertoegang. Zie Leasebestand voor meer informatie over leasestatussen en acties.

In het volgende codevoorbeeld ziet u hoe u een leaseclient maakt, een oneindige duur lease op een bestand verkrijgt en de lease vrijgeeft:

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

Wanneer u zowel SMB als de FileREST-API gebruikt, moet u er rekening mee houden dat de FileREST-API leases gebruikt om bestandsvergrendelingen te beheren, terwijl SMB gebruikmaakt van bestandssysteemvergrendelingen die worden beheerd door het besturingssysteem. Zie Bestandsvergrendelingen beheren voor meer informatie over het beheren van interacties tussen SMB en de FileREST-API.

Voorbeeld: Momentopnamen van bestandsdelers maken en weergeven met behulp van de clientbibliotheek.

Momentopnamen van bestandsshares zijn alleen-lezen kopieën van een bestandsshare op een gegeven moment. U kunt een momentopname van een bestandsshare maken en vervolgens de momentopname gebruiken om toegang te krijgen tot de gegevens in de share op het moment dat de momentopname is gemaakt. U kunt ook alle momentopnamen in een gedeelde map weergeven en momentopnamen van gedeelde mappen verwijderen.

In het volgende codevoorbeeld ziet u hoe u een momentopname van een share maakt, de momentopnamen in een bestandsshare weergeeft en de mapstructuur doorkruist in een momentopname van een share:

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-resources beheren met behulp van de Azure Storage-beheerbibliotheken

De Azure Storage-beheerbibliotheken zijn gebaseerd op de REST API van de Azure Storage-resourceprovider. De Azure Storage-resourceprovider is een service op basis van Azure Resource Manager en ondersteunt zowel declaratieve (sjablonen) als imperatieve methoden (directe API-aanroep). De REST API van de Azure Storage-resourceprovider biedt programmatische toegang tot Azure Storage-resources, waaronder bestandsshares. De Azure SDK biedt beheerbibliotheken die zijn gebaseerd op de REST API van de Azure Storage-resourceprovider.

De beheerbibliotheken worden aanbevolen voor bewerkingen die worden uitgevoerd op bestandsservice - of bestandsshareniveau . In deze sectie leert u hoe u de Azure Storage-beheerbibliotheken gebruikt om Azure Files-resources te beheren.

Voorbeeld: Een bestandsshare maken met behulp van de Azure Storage-beheerbibliotheek

In het volgende codevoorbeeld ziet u hoe u een object op het hoogste niveau ArmClient maakt, de opslagresourceprovider registreert bij een abonnement en een bestandsshare maakt met behulp van de Azure Storage-beheerbibliotheek:

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;

U kunt de eigenschappen van de bestandsshare configureren met behulp van de klasse FileShareData . In het vorige voorbeeld ziet u hoe u de ShareQuota eigenschap instelt.

Voorbeeld: Bestandsshares en momentopnamen weergeven met behulp van de Azure Storage-beheerbibliotheek

In het volgende codevoorbeeld ziet u hoe u bestandsshares en momentopnamen in een opslagaccount weergeeft:

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

Verwante inhoud

Zie de volgende resources voor meer informatie over ontwikkelen met Azure Files:

• Overzicht van toepassingsontwikkeling met Azure Files
• Shares, mappen, bestanden en metagegevens een naam geven en hiernaar verwijzen
• Bestandsvergrendelingen beheren
• Bewerkingen op mappen
• bewerkingen voor bestanden