Utveckla för Azure Files med .NET

Artikel
05/06/2023

Lär dig grunderna i att utveckla .NET-program som använder Azure Files för att lagra data. Den här artikeln visar hur du skapar ett enkelt konsolprogram för att göra följande med .NET och Azure Files:

Hämta innehållet i en fil.
Ange maximal storlek eller kvot för en filresurs.
Skapa en signatur för delad åtkomst (SAS) för en fil.
Kopiera en fil till en annan fil i samma lagringskonto.
Kopiera en fil till en blobb i samma lagringskonto.
Skapa en ögonblicksbild av en filresurs.
Återställa en fil från en resursögonblicksbild.
Använd Azure Storage Metrics för felsökning.

Mer information om Azure Files finns i Vad är Azure Files?

Tips

Ta en titt på databasen med Azure Storage-kodexempel

Lättanvända Azure Storage-kodexempel från slutpunkt till slutpunkt som du kan ladda ned och köra finns i vår lista med Azure Storage-exempel.

Gäller för

Typ av filresurs	SMB	NFS
Standardfilresurser (GPv2), LRS/ZRS
Standardfilresurser (GPv2), GRS/GZRS
Premiumfilresurser (FileStorage), LRS/ZRS

Förstå .NET-API: er

Azure Files tillhandahåller två breda metoder för klientprogram: Server Message Block (SMB) och REST. I .NET abstraherar API:erna System.IO och Azure.Storage.Files.Shares dessa metoder.

API	När du ska använda detta	Anteckningar
System.IO	Ditt program: Behöver läsa/skriva filer med hjälp av SMB Körs på en enhet som har åtkomst via port 445 till ditt Azure Files-konto Behöver inte hantera några av de administrativa inställningarna för filresursen	Fil-I/O som implementeras med Azure Files över SMB är vanligtvis samma som I/O med alla nätverksfilresurser eller lokala lagringsenheter. En introduktion till ett antal funktioner i .NET, inklusive fil-I/O, finns i självstudien konsolprogram .
Azure.Storage.Files.Shares	Ditt program: Det går inte att komma åt Azure Files med hjälp av SMB på port 445 på grund av brandväggs- eller INTERNET-begränsningar Kräver administrativa funktioner, som möjligheten att ställa in en filresurs kvot eller skapa en signatur för delad åtkomst	Den här artikeln visar användningen av `Azure.Storage.Files.Shares` för fil-I/O med HJÄLP av REST i stället för SMB och hantering av filresursen.

Skapa konsolprogrammet och hämta monteringen

Du kan använda Azure Files-klientbiblioteket i valfri typ av .NET-app. Dessa appar omfattar Azure-moln, webb, skrivbord och mobilappar. I den här guiden skapar vi ett konsolprogram för enkelhetens skull.

Skapa ett nytt Windows-konsolprogram i Visual Studio. Följande steg visar hur du skapar ett konsolprogram i Visual Studio 2019. Stegen är ungefär som i andra versioner av Visual Studio.

Starta Visual Studio och välj Skapa ett nytt projekt.
I Skapa ett nytt projekt väljer du Konsolapp (.NET Framework) för C#och väljer sedan Nästa.
I Konfigurera det nya projektet anger du ett namn för appen och väljer Skapa.

Lägg till alla kodexempel i den Program här artikeln i klassen i filen Program.cs .

Använd NuGet för att installera de paket som behövs

Se de här paketen i projektet:

Azure Core-biblioteket för .NET: Det här paketet är implementeringen av Azure-klientpipelinen.
Azure Storage Blob-klientbibliotek för .NET: Det här paketet ger programmatisk åtkomst till blobresurser i ditt lagringskonto.
Azure Storage Files-klientbibliotek för .NET: Det här paketet ger programmatisk åtkomst till filresurser i ditt lagringskonto.
System Configuration Manager-bibliotek för .NET: Det här paketet innehåller en klass som lagrar och hämtar värden i en konfigurationsfil.

Du kan använda NuGet för att hämta paketen. Gör så här:

I Solution Explorer högerklickar du på projektet och väljer Hantera NuGet-paket.
I NuGet Package Manager väljer du Bläddra. Sök sedan efter och välj Azure.Core och välj sedan Installera.

Det här steget installerar paketet och dess beroenden.
Sök efter och installera följande paket:
- Azure.Storage.Blobs
- Azure.Storage.Files.Shares
- System.Configuration.ConfigurationManager

Spara dina autentiseringsuppgifter för lagringskontot i App.config-filen

Spara sedan dina autentiseringsuppgifter i projektets App.config-fil . I Solution Explorer dubbelklickar du på App.config och redigerar filen så att den liknar följande exempel.

Ersätt myaccount med lagringskontots namn och mykey med lagringskontonyckeln.

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <appSettings>
    <add key="StorageConnectionString" 
      value="DefaultEndpointsProtocol=https;AccountName=myaccount;AccountKey=mykey;EndpointSuffix=core.windows.net" />
    <add key="StorageAccountName" value="myaccount" />
    <add key="StorageAccountKey" value="mykey" />
  </appSettings>
</configuration>

Anteckning

Azurite Storage-emulatorn stöder för närvarande inte Azure Files. Anslutningssträngen måste rikta in sig på ett Azure Storage-konto i molnet för att fungera med Azure Files.

Lägga till med hjälp av direktiv

Öppna filen Program.csi Solution Explorer och lägg till följande med hjälp av direktiv överst i filen.

using System;
using System.Configuration;
using System.IO;
using System.Threading.Tasks;
using Azure;
using Azure.Storage;
using Azure.Storage.Blobs;
using Azure.Storage.Files.Shares;
using Azure.Storage.Files.Shares.Models;
using Azure.Storage.Sas;

I filen Program.cs lägger du till följande kod för att komma åt filresursen programmatiskt.

Följande metod skapar en filresurs om den inte redan finns. Metoden börjar med att skapa ett ShareClient-objekt från en anslutningssträng. Exemplet försöker sedan ladda ned en fil som vi skapade tidigare. Anropa den här metoden från Main().

//-------------------------------------------------
// Create a file share
//-------------------------------------------------
public async Task CreateShareAsync(string shareName)
{
    // Get the connection string from app settings
    string connectionString = ConfigurationManager.AppSettings["StorageConnectionString"];

    // Instantiate a ShareClient which will be used to create and manipulate the file share
    ShareClient share = new ShareClient(connectionString, shareName);

    // Create the share if it doesn't already exist
    await share.CreateIfNotExistsAsync();

    // Ensure that the share exists
    if (await share.ExistsAsync())
    {
        Console.WriteLine($"Share created: {share.Name}");

        // Get a reference to the sample directory
        ShareDirectoryClient directory = share.GetDirectoryClient("CustomLogs");

        // Create the directory if it doesn't already exist
        await directory.CreateIfNotExistsAsync();

        // Ensure that the directory exists
        if (await directory.ExistsAsync())
        {
            // Get a reference to a file object
            ShareFileClient file = directory.GetFileClient("Log1.txt");

            // Ensure that the file exists
            if (await file.ExistsAsync())
            {
                Console.WriteLine($"File exists: {file.Name}");

                // Download the file
                ShareFileDownloadInfo download = await file.DownloadAsync();

                // Save the data to a local file, overwrite if the file already exists
                using (FileStream stream = File.OpenWrite(@"downloadedLog1.txt"))
                {
                    await download.Content.CopyToAsync(stream);
                    await stream.FlushAsync();
                    stream.Close();

                    // Display where the file was saved
                    Console.WriteLine($"File downloaded: {stream.Name}");
                }
            }
        }
    }
    else
    {
        Console.WriteLine($"CreateShareAsync failed");
    }
}

Från och med version 5.x av Azure Files-klientbiblioteket kan du ange kvoten (maximal storlek) för en filresurs. Du kan också kontrollera hur mycket data som lagras på resursen för närvarande.

Om du anger kvoten för en resurs begränsas den totala storleken på filerna som lagras på resursen. Om den totala storleken på filer på resursen överskrider kvoten kan klienterna inte öka storleken på befintliga filer. Klienter kan inte heller skapa nya filer, såvida inte dessa filer är tomma.

Exemplet nedan visar hur du kontrollerar användningen av en resurs och hur du ställer in kvoten för resursen.

//-------------------------------------------------
// Set the maximum size of a share
//-------------------------------------------------
public async Task SetMaxShareSizeAsync(string shareName, int increaseSizeInGiB)
{
    const long ONE_GIBIBYTE = 10737420000; // Number of bytes in 1 gibibyte

    // Get the connection string from app settings
    string connectionString = ConfigurationManager.AppSettings["StorageConnectionString"];

    // Instantiate a ShareClient which will be used to access the file share
    ShareClient share = new ShareClient(connectionString, shareName);

    // Create the share if it doesn't already exist
    await share.CreateIfNotExistsAsync();

    // Ensure that the share exists
    if (await share.ExistsAsync())
    {
        // Get and display current share quota
        ShareProperties properties = await share.GetPropertiesAsync();
        Console.WriteLine($"Current share quota: {properties.QuotaInGB} GiB");

        // Get and display current usage stats for the share
        ShareStatistics stats = await share.GetStatisticsAsync();
        Console.WriteLine($"Current share usage: {stats.ShareUsageInBytes} bytes");

        // Convert current usage from bytes into GiB
        int currentGiB = (int)(stats.ShareUsageInBytes / ONE_GIBIBYTE);

        // This line sets the quota to be the current 
        // usage of the share plus the increase amount
        await share.SetQuotaAsync(currentGiB + increaseSizeInGiB);

        // Get the new quota and display it
        properties = await share.GetPropertiesAsync();
        Console.WriteLine($"New share quota: {properties.QuotaInGB} GiB");
    }
}

Från och med version 5.x av Azure Files-klientbiblioteket kan du generera en signatur för delad åtkomst (SAS) för en filresurs eller för en enskild fil.

Följande exempelmetod returnerar en SAS på en fil i den angivna resursen.

//-------------------------------------------------
// Create a SAS URI for a file
//-------------------------------------------------
public Uri GetFileSasUri(string shareName, string filePath, DateTime expiration, ShareFileSasPermissions permissions)
{
    // Get the account details from app settings
    string accountName = ConfigurationManager.AppSettings["StorageAccountName"];
    string accountKey = ConfigurationManager.AppSettings["StorageAccountKey"];

    ShareSasBuilder fileSAS = new ShareSasBuilder()
    {
        ShareName = shareName,
        FilePath = filePath,

        // Specify an Azure file resource
        Resource = "f",

        // Expires in 24 hours
        ExpiresOn = expiration
    };

    // Set the permissions for the SAS
    fileSAS.SetPermissions(permissions);

    // Create a SharedKeyCredential that we can use to sign the SAS token
    StorageSharedKeyCredential credential = new StorageSharedKeyCredential(accountName, accountKey);

    // Build a SAS URI
    UriBuilder fileSasUri = new UriBuilder($"https://{accountName}.file.core.windows.net/{fileSAS.ShareName}/{fileSAS.FilePath}");
    fileSasUri.Query = fileSAS.ToSasQueryParameters(credential).ToString();

    // Return the URI
    return fileSasUri.Uri;
}

Mer information om hur du skapar och använder signaturer för delad åtkomst finns i Så här fungerar en signatur för delad åtkomst.

Kopiera filer

Från och med version 5.x av Azure Files-klientbiblioteket kan du kopiera en fil till en annan fil, en fil till en blob eller en blob till en fil.

Du kan också använda AzCopy för att kopiera en fil till en annan eller för att kopiera en blob till en fil eller tvärtom. Se Kom igång med AzCopy.

Anteckning

Om du kopierar en blobb till en fil eller en fil till en blobb måste du använda en signatur för delad åtkomst (SAS) för att auktorisera åtkomst till källobjektet, även om du kopierar inom samma lagringskonto.

Kopiera en fil till en annan fil

I följande exempel kopierar vi en fil till en annan fil i samma resurs. Du kan använda autentisering med delad nyckel för att göra kopian eftersom den här åtgärden kopierar filer inom samma lagringskonto.

//-------------------------------------------------
// Copy file within a directory
//-------------------------------------------------
public async Task CopyFileAsync(string shareName, string sourceFilePath, string destFilePath)
{
    // Get the connection string from app settings
    string connectionString = ConfigurationManager.AppSettings["StorageConnectionString"];

    // Get a reference to the file we created previously
    ShareFileClient sourceFile = new ShareFileClient(connectionString, shareName, sourceFilePath);

    // Ensure that the source file exists
    if (await sourceFile.ExistsAsync())
    {
        // Get a reference to the destination file
        ShareFileClient destFile = new ShareFileClient(connectionString, shareName, destFilePath);

        // Start the copy operation
        await destFile.StartCopyAsync(sourceFile.Uri);

        if (await destFile.ExistsAsync())
        {
            Console.WriteLine($"{sourceFile.Uri} copied to {destFile.Uri}");
        }
    }
}

Kopiera en fil till en blobb

I följande exempel skapar vi en fil och kopierar den till en blobb inom samma lagringskonto. I exemplet skapas en SAS för källfilen, som tjänsten använder för att auktorisera åtkomsten till källfilen under kopieringen.

//-------------------------------------------------
// Copy a file from a share to a blob
//-------------------------------------------------
public async Task CopyFileToBlobAsync(string shareName, string sourceFilePath, string containerName, string blobName)
{
    // Get a file SAS from the method created ealier
    Uri fileSasUri = GetFileSasUri(shareName, sourceFilePath, DateTime.UtcNow.AddHours(24), ShareFileSasPermissions.Read);

    // Get a reference to the file we created previously
    ShareFileClient sourceFile = new ShareFileClient(fileSasUri);

    // Ensure that the source file exists
    if (await sourceFile.ExistsAsync())
    {
        // Get the connection string from app settings
        string connectionString = ConfigurationManager.AppSettings["StorageConnectionString"];

        // Get a reference to the destination container
        BlobContainerClient container = new BlobContainerClient(connectionString, containerName);

        // Create the container if it doesn't already exist
        await container.CreateIfNotExistsAsync();

        BlobClient destBlob = container.GetBlobClient(blobName);

        await destBlob.StartCopyFromUriAsync(sourceFile.Uri);

        if (await destBlob.ExistsAsync())
        {
            Console.WriteLine($"File {sourceFile.Name} copied to blob {destBlob.Name}");
        }
    }
}

Du kan kopiera en blobb till en fil på samma sätt. Om källobjektet är en blobb skapar du en SAS för att auktorisera åtkomsten till blobben under kopieringen.

Från och med version 8.5 av Azure Files-klientbiblioteket kan du skapa en resursögonblicksbild. Du kan också visa eller bläddra bland resursögonblicksbilder och ta bort resursögonblicksbilder. När resursögonblicksbilder har skapats är de skrivskyddade.

I följande exempel skapas en ögonblicksbild av en filresurs.

//-------------------------------------------------
// Create a share snapshot
//-------------------------------------------------
public async Task CreateShareSnapshotAsync(string shareName)
{
    // Get the connection string from app settings
    string connectionString = ConfigurationManager.AppSettings["StorageConnectionString"];

    // Instatiate a ShareServiceClient
    ShareServiceClient shareServiceClient = new ShareServiceClient(connectionString);

    // Instantiate a ShareClient which will be used to access the file share
    ShareClient share = shareServiceClient.GetShareClient(shareName);

    // Ensure that the share exists
    if (await share.ExistsAsync())
    {
        // Create a snapshot
        ShareSnapshotInfo snapshotInfo = await share.CreateSnapshotAsync();
        Console.WriteLine($"Snapshot created: {snapshotInfo.Snapshot}");
    }
}

I följande exempel visas ögonblicksbilderna på en resurs.

//-------------------------------------------------
// List the snapshots on a share
//-------------------------------------------------
public void ListShareSnapshots()
{
    // Get the connection string from app settings
    string connectionString = ConfigurationManager.AppSettings["StorageConnectionString"];

    // Instatiate a ShareServiceClient
    ShareServiceClient shareServiceClient = new ShareServiceClient(connectionString);

    // Display each share and the snapshots on each share
    foreach (ShareItem item in shareServiceClient.GetShares(ShareTraits.All, ShareStates.Snapshots))
    {
        if (null != item.Snapshot)
        {
            Console.WriteLine($"Share: {item.Name}\tSnapshot: {item.Snapshot}");
        }
    }
}

I följande exempel bläddras filer och kataloger i resursögonblicksbilder.

//-------------------------------------------------
// List the snapshots on a share
//-------------------------------------------------
public void ListSnapshotContents(string shareName, string snapshotTime)
{
    // Get the connection string from app settings
    string connectionString = ConfigurationManager.AppSettings["StorageConnectionString"];

    // Instatiate a ShareServiceClient
    ShareServiceClient shareService = new ShareServiceClient(connectionString);

    // Get a ShareClient
    ShareClient share = shareService.GetShareClient(shareName);

    Console.WriteLine($"Share: {share.Name}");

    // Get as ShareClient that points to a snapshot
    ShareClient snapshot = share.WithSnapshot(snapshotTime);

    // Get the root directory in the snapshot share
    ShareDirectoryClient rootDir = snapshot.GetRootDirectoryClient();

    // Recursively list the directory tree
    ListDirTree(rootDir);
}

//-------------------------------------------------
// Recursively list a directory tree
//-------------------------------------------------
public void ListDirTree(ShareDirectoryClient dir)
{
    // List the files and directories in the snapshot
    foreach (ShareFileItem item in dir.GetFilesAndDirectories())
    {
        if (item.IsDirectory)
        {
            Console.WriteLine($"Directory: {item.Name}");
            ShareDirectoryClient subDir = dir.GetSubdirectoryClient(item.Name);
            ListDirTree(subDir);
        }
        else
        {
            Console.WriteLine($"File: {dir.Name}\\{item.Name}");
        }
    }
}

Genom att ta en ögonblicksbild av en filresurs kan du återställa enskilda filer eller hela filresursen.

Du kan återställa en fil från en ögonblicksbild av en filresurs genom att skicka en fråga till ögonblicksbilderna av en filresurs. Du kan sedan hämta en fil som tillhör en viss resursögonblicksbild. Använd den versionen för att läsa direkt eller återställa filen.

//-------------------------------------------------
// Restore file from snapshot
//-------------------------------------------------
public async Task RestoreFileFromSnapshot(string shareName, string directoryName, string fileName, string snapshotTime)
{
    // Get the connection string from app settings
    string connectionString = ConfigurationManager.AppSettings["StorageConnectionString"];

    // Instatiate a ShareServiceClient
    ShareServiceClient shareService = new ShareServiceClient(connectionString);

    // Get a ShareClient
    ShareClient share = shareService.GetShareClient(shareName);

    // Get as ShareClient that points to a snapshot
    ShareClient snapshot = share.WithSnapshot(snapshotTime);

    // Get a ShareDirectoryClient, then a ShareFileClient to the snapshot file
    ShareDirectoryClient snapshotDir = snapshot.GetDirectoryClient(directoryName);
    ShareFileClient snapshotFile = snapshotDir.GetFileClient(fileName);

    // Get a ShareDirectoryClient, then a ShareFileClient to the live file
    ShareDirectoryClient liveDir = share.GetDirectoryClient(directoryName);
    ShareFileClient liveFile = liveDir.GetFileClient(fileName);

    // Restore the file from the snapshot
    ShareFileCopyInfo copyInfo = await liveFile.StartCopyAsync(snapshotFile.Uri);

    // Display the status of the operation
    Console.WriteLine($"Restore status: {copyInfo.CopyStatus}");
}

Följande exempel tar bort en ögonblicksbild av en filresurs.

//-------------------------------------------------
// Delete a snapshot
//-------------------------------------------------
public async Task DeleteSnapshotAsync(string shareName, string snapshotTime)
{
    // Get the connection string from app settings
    string connectionString = ConfigurationManager.AppSettings["StorageConnectionString"];

    // Instatiate a ShareServiceClient
    ShareServiceClient shareService = new ShareServiceClient(connectionString);

    // Get a ShareClient
    ShareClient share = shareService.GetShareClient(shareName);

    // Get a ShareClient that points to a snapshot
    ShareClient snapshotShare = share.WithSnapshot(snapshotTime);

    try
    {
        // Delete the snapshot
        await snapshotShare.DeleteIfExistsAsync();
    }
    catch (RequestFailedException ex)
    {
        Console.WriteLine($"Exception: {ex.Message}");
        Console.WriteLine($"Error code: {ex.Status}\t{ex.ErrorCode}");
    }
}

Felsöka Azure Files med hjälp av mått

Azure Lagringsanalys stöder mått för Azure Files. Med hjälp av mätvärdesdata kan du spåra begäranden och diagnostisera problem.

Du kan aktivera mått för Azure Files från Azure Portal. Du kan också aktivera mått programmatiskt genom att anropa åtgärden Ange egenskaper för filtjänst med REST-API:et eller någon av dess analoger i Azure Files-klientbiblioteket.

Följande kodexempel visar hur du använder .NET-klientbiblioteket för att aktivera mått för Azure Files.

//-------------------------------------------------
// Use metrics
//-------------------------------------------------
public async Task UseMetricsAsync()
{
    // Get the connection string from app settings
    string connectionString = ConfigurationManager.AppSettings["StorageConnectionString"];

    // Instatiate a ShareServiceClient
    ShareServiceClient shareService = new ShareServiceClient(connectionString);

    // Set metrics properties for File service
    await shareService.SetPropertiesAsync(new ShareServiceProperties()
    {
        // Set hour metrics
        HourMetrics = new ShareMetrics()
        {
            Enabled = true,
            IncludeApis = true,
            Version = "1.0",

            RetentionPolicy = new ShareRetentionPolicy()
            {
                Enabled = true,
                Days = 14
            }
        },

        // Set minute metrics
        MinuteMetrics = new ShareMetrics()
        {
            Enabled = true,
            IncludeApis = true,
            Version = "1.0",

            RetentionPolicy = new ShareRetentionPolicy()
            {
                Enabled = true,
                Days = 7
            }
        }
    });

    // Read the metrics properties we just set
    ShareServiceProperties serviceProperties = await shareService.GetPropertiesAsync();

    // Display the properties
    Console.WriteLine();
    Console.WriteLine($"HourMetrics.InludeApis: {serviceProperties.HourMetrics.IncludeApis}");
    Console.WriteLine($"HourMetrics.RetentionPolicy.Days: {serviceProperties.HourMetrics.RetentionPolicy.Days}");
    Console.WriteLine($"HourMetrics.Version: {serviceProperties.HourMetrics.Version}");
    Console.WriteLine();
    Console.WriteLine($"MinuteMetrics.InludeApis: {serviceProperties.MinuteMetrics.IncludeApis}");
    Console.WriteLine($"MinuteMetrics.RetentionPolicy.Days: {serviceProperties.MinuteMetrics.RetentionPolicy.Days}");
    Console.WriteLine($"MinuteMetrics.Version: {serviceProperties.MinuteMetrics.Version}");
    Console.WriteLine();
}

Om du stöter på problem kan du läsa Felsöka Azure Files.

Nästa steg

Mer information om Azure Files finns i följande resurser:

Begreppsrelaterade artiklar och videoklipp

Verktygsstöd för File Storage

Referens

Relaterade kodexempel med inaktuella .NET version 11.x SDK:er finns i Kodexempel med .NET version 11.x.

Utveckla för Azure Files med .NET

Gäller för

Förstå .NET-API: er

Skapa konsolprogrammet och hämta monteringen

Använd NuGet för att installera de paket som behövs

Spara dina autentiseringsuppgifter för lagringskontot i App.config-filen

Lägga till med hjälp av direktiv

Ansluta till filresursen via programmering

Ange den största storleken för en filresurs

Generera en signatur för delad åtkomst för en fil eller filresurs

Kopiera filer

Kopiera en fil till en annan fil

Kopiera en fil till en blobb

Resursögonblicksbilder

Skapa resursögonblicksbilder

Lista resursögonblicksbilder

Visa en lista över filer och kataloger i resursögonblicksbilder

Återställa filresurser eller filer från resursögonblicksbilder

Ta bort resursögonblicksbilder

Felsöka Azure Files med hjälp av mått

Nästa steg

Begreppsrelaterade artiklar och videoklipp

Verktygsstöd för File Storage

Referens

Ytterligare resurser