Vývoj pro Soubory Azure pomocí .NET

Seznamte se se základy vývoje aplikací .NET, které k ukládání dat používají azure Files . Tento článek ukazuje, jak vytvořit jednoduchou konzolovou aplikaci, která provede následující akce pomocí .NET a Azure Files:

• Získejte obsah souboru.
• Nastavte maximální velikost nebo kvótu sdílené složky.
• Vytvořte sdílený přístupový podpis (SAS) pro soubor.
• Zkopírujte soubor do jiného souboru ve stejném účtu úložiště.
• Zkopírujte soubor do objektu blob ve stejném účtu úložiště.
• Vytvořte snímek sdílené složky.
• Obnovte soubor ze snímku sdílené složky.
• K řešení potíží použijte metriky služby Azure Storage.

Další informace o službě Soubory Azure najdete v tématu Co je Azure Files?

Platí pro

Typ sdílené složky	SMB	NFS
Sdílené složky úrovně Standard (GPv2), LRS/ZRS
Sdílené složky úrovně Standard (GPv2), GRS/GZRS
Sdílené složky úrovně Premium (FileStorage), LRS/ZRS

Vysvětlení rozhraní API .NET

Soubory Azure poskytuje dva přístupy ke klientským aplikacím: protokol SMB (Server Message Block) a REST. V rozhraní .NET tyto System.IO přístupy abstrahují rozhraní Azure.Storage.Files.Shares API.

Vytvoření konzolové aplikace a získání sestavení

Klientskou knihovnu Azure Files můžete použít v libovolném typu aplikace .NET. Mezi tyto aplikace patří cloud Azure, web, desktop a mobilní aplikace. V této příručce vytvoříme konzolovou aplikaci pro zjednodušení.

V sadě Visual Studio vytvořte novou konzolovou aplikaci pro Windows. Následující kroky ukazují, jak vytvořit konzolovou aplikaci v sadě Visual Studio 2019. Kroky u ostatních verzí sady Visual Studio jsou podobné.

1. Spusťte Visual Studio a vyberte Vytvořit nový projekt.
2. V části Vytvořit nový projekt zvolte Konzolová aplikace (.NET Framework) pro C# a pak vyberte Další.
3. V části Konfigurace nového projektu zadejte název aplikace a vyberte Vytvořit.

Do třídy v Program souboru Program.cs přidejte všechny příklady kódu v tomto článku.

Použití balíčku NuGet k instalaci požadovaných balíčků

Projděte si tyto balíčky v projektu:

• Základní knihovna Azure pro .NET: Tento balíček je implementace kanálu klienta Azure.
• Klientská knihovna objektů blob služby Azure Storage pro .NET: Tento balíček poskytuje programový přístup k prostředkům objektů blob ve vašem účtu úložiště.
• Klientská knihovna Azure Storage Files pro .NET: Tento balíček poskytuje programový přístup k prostředkům souborů ve vašem účtu úložiště.
• Knihovna nástroje System Configuration Manager pro .NET: Tento balíček poskytuje třídu, která ukládá a načítá hodnoty v konfiguračním souboru.

Balíčky můžete získat pomocí NuGetu. Postupujte následovně:

1. V Průzkumník řešení klikněte pravým tlačítkem na projekt a zvolte Spravovat balíčky NuGet.

2. V Správce balíčků NuGet vyberte Procházet. Pak vyhledejte a zvolte Azure.Core a pak vyberte Nainstalovat.

   Tento krok nainstaluje balíček a jeho závislosti.

3. Vyhledejte a nainstalujte tyto balíčky:

   • Azure.Storage.Blobs
   • Azure.Storage.Files.Shares
   • System.Configuration.ConfigurationManager

Uložení přihlašovacích údajů účtu úložiště do souboru App.config

Dále uložte své přihlašovací údaje do souboru App.config projektu. V Průzkumník řešení poklikejte App.config na soubor a upravte ho tak, aby byl podobný následujícímu příkladu.

Nahraďte myaccount názvem svého účtu úložiště a mykey klíčem účtu úložiště.

<?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>

Přidání direktiv using

V Průzkumník řešení otevřete soubor Program.cs a do horní části souboru přidejte následující direktivy using.

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;

Programový přístup ke sdílené složce

Do souboru Program.cs přidejte následující kód pro přístup ke sdílené složce prostřednictvím kódu programu.

Následující metoda vytvoří sdílenou složku, pokud ještě neexistuje. Metoda začíná vytvořením objektu ShareClient z připojovací řetězec. Ukázka se pak pokusí stáhnout soubor, který jsme vytvořili dříve. Volání této metody z 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");
    }
}

Nastavení maximální velikosti sdílené složky

Počínaje verzí 5.x klientské knihovny Azure Files můžete nastavit kvótu (maximální velikost) sdílené složky. Můžete se taky podívat, kolik data je aktuálně uloženo ve sdílené složce.

Nastavení kvóty pro sdílenou složku omezuje celkovou velikost souborů uložených ve sdílené složce. Pokud celková velikost souborů ve sdílené složce překročí kvótu, klienti nemůžou zvětšit velikost existujících souborů. Klienti také nemůžou vytvářet nové soubory, pokud tyto soubory nejsou prázdné.

Dole uvedený příklad ukazuje, jak můžete zkontrolovat aktuální využití sdílené složky a jak nastavit kvótu pro sdílenou složku.

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

Vygenerování sdíleného přístupového podpisu pro soubor nebo sdílenou složku

Počínaje verzí 5.x klientské knihovny Azure Files můžete vygenerovat sdílený přístupový podpis (SAS) pro sdílenou složku nebo pro jednotlivé soubory.

Následující příklad metoda vrátí SAS na souboru v zadané sdílené složce.

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

Další informace o vytváření a používání sdílených přístupových podpisů naleznete v tématu Jak sdílený přístupový podpis funguje.

Kopírování souborů

Od verze 5.x klientské knihovny služby Azure Files můžete soubor zkopírovat do jiného souboru, do souboru do objektu blob nebo objektu blob do souboru.

Pomocí AzCopy můžete také zkopírovat jeden soubor do jiného nebo zkopírovat objekt blob do souboru nebo naopak. Viz Začínáme s nástrojem AzCopy.

Kopírování souboru do jiného souboru

V následujícím příkladu se zkopíruje soubor do jiného souboru ve stejné sdílené složce. K kopírování můžete použít ověřování pomocí sdíleného klíče, protože tato operace kopíruje soubory ve stejném účtu úložiště.

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

Kopírování souboru do objektu blob

V následujícím příkladu se vytvoří soubor a zkopíruje se do objektu blob ve stejném účtu úložiště. V příkladu se pro zdrojový soubor vytvoří SAS, který služba během operace kopírování použije k autorizaci přístupu ke zdrojovému souboru.

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

Stejným způsobem můžete kopírovat objekt blob do souboru. Pokud je zdrojovým objektem objekt blob, vytvořte SAS k autorizaci přístupu k tomuto objektu blob během operace kopírování.

Snímky sdílených složek

Od verze 8.5 klientské knihovny Azure Files můžete vytvořit snímek sdílené složky. Umožňuje také vypsat nebo procházet snímky sdílené složky a odstranit je. Po vytvoření jsou snímky sdílených složek jen pro čtení.

Vytvoření snímků sdílené složky

Následující příklad vytvoří snímek sdílené složky.

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

Výpis snímků sdílené složky

Následující příklad uvádí snímky ve sdílené složce.

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

Výpis souborů a adresářů ve snímcích sdílených složek

Následující příklad prochází soubory a adresáře v rámci snímků sdílených složek.

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

Obnovení sdílených složek nebo souborů ze snímků sdílených složek

Pořízení snímku sdílené složky umožňuje obnovit jednotlivé soubory nebo celou sdílenou složku.

Soubor můžete ze snímku sdílené složky obnovit zadáním dotazu na snímky sdílené složky nebo sdílenou složku. Pak můžete načíst soubor, který patří do určitého snímku sdílené složky. Tuto verzi použijte k přímému čtení nebo obnovení souboru.

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

Odstranění snímků sdílené složky

Následující příklad odstraní snímek sdílené složky.

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

Řešení potíží se službou Azure Files pomocí metrik

Azure Analýza úložiště podporuje metriky pro Soubory Azure. S údaji z metriky můžete sledovat žádosti a diagnostikovat potíže.

Metriky pro Azure Files můžete povolit na webu Azure Portal. Metriky můžete také povolit programově voláním operace Nastavit vlastnosti souborové služby pomocí rozhraní REST API nebo některého z jejích analogů v klientské knihovně Azure Files.

Následující příklad kódu ukazuje, jak pomocí klientské knihovny .NET povolit metriky pro Soubory Azure.

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

Pokud narazíte na nějaké problémy, projděte si řešení potíží se službou Azure Files.

Další kroky

Další informace o službě Azure Files najdete v následujících zdrojích informací:

• Začínáme s nástrojem AzCopy
• Řešení problémů se Soubory Azure
• Rozhraní API služby Azure Storage pro .NET
• Rozhraní REST API služby File Service

Související ukázky kódu s využitím zastaralých sad .NET verze 11.x najdete v ukázkách kódu pomocí .NET verze 11.x.