Vývoj pro Soubory Azure pomocí .NET

  • Článek

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á pomocí rozhraní .NET a Azure Files provede následující akce:

  • 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.
  • Obnovení souboru ze snímku sdílené složky
  • K řešení potíží použijte metriky služby Azure Storage.

Další informace o Azure Files najdete v tématu Co je Azure Files?

Tip

Projděte si úložiště s ukázkami kódu pro Azure Storage

Snadno použitelné a úplné ukázky kódu pro Azure Storage, které si můžete stáhnout a použít, jsou shrnuté v seznamu ukázky pro Azure Storage.

Platí pro

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

Vysvětlení rozhraní API .NET

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

rozhraní API Kdy je použít Poznámky
System.IO Vaše aplikace:
  • Potřebuje číst a zapisovat soubory pomocí protokolu SMB
  • Je spuštěná v zařízení, které má prostřednictvím portu 445 přístup k vašemu účtu služby Soubory Azure.
  • Nemusí spravovat žádná nastavení pro správu sdílené složky.
 Vstupně-výstupní operace souborů implementované s Azure Files přes protokol SMB jsou obecně stejné jako vstupně-výstupní operace s libovolnou sdílenou složkou sítě nebo místním úložným zařízením. Úvod k řadě funkcí v .NET, včetně vstupně-výstupních operací souborů, najdete v kurzu Konzolová aplikace .
Azure.Storage.Files.Shares Vaše aplikace:
  • Nejde získat přístup k Azure Files pomocí protokolu SMB na portu 445 kvůli omezením brány firewall nebo poskytovatele internetových služeb
  • Vyžaduje funkce pro správu, jako je například možnost nastavit kvótu sdílené složky nebo vytvořit sdílený přístupový podpis.
 Tento článek ukazuje použití Azure.Storage.Files.Shares pro vstupně-výstupní operace souborů pomocí REST místo protokolu SMB a správy sdílené složky.

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

Klientskou knihovnu Azure Files můžete použít v libovolném typu aplikace .NET. Tyto aplikace zahrnují cloudové, webové, desktopové a mobilní aplikace Azure. 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.

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

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

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

K získání balíčků můžete použít NuGet. Postupujte takto:

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

  2. Ve Správci 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 přihlašovací údaje do souboruApp.config projektu. V Průzkumník řešení poklikejte App.config a upravte soubor tak, aby byl podobný následujícímu příkladu.

Nahraďte myaccount názvem úč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>

Poznámka

Emulátor úložiště Azurite v současné době nepodporuje Azure Files. Aby váš připojovací řetězec fungoval s Azure Files, musí cílit na účet úložiště Azure v cloudu.

Přidání direktiv using

V Průzkumník řešení otevřete soubor Program.cs a na začátek 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ího řetězce. 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í ukázková metoda vrátí SAS v 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ů najdete v tématu Jak funguje sdílený přístupový podpis.

Kopírování souborů

Počínaje verzí 5.x klientské knihovny Azure Files můžete zkopírovat soubor do jiného souboru, soubor do objektu blob nebo objekt blob do souboru.

AzCopy můžete také použít ke zkopírování jednoho souboru do jiného nebo ke zkopírování objektu blob do souboru nebo naopak. Viz Začínáme s Nástrojem AzCopy.

Poznámka

Pokud kopírujete objekt blob do souboru nebo soubor do objektu blob, musíte použít sdílený přístupový podpis (SAS) k ověření přístupu ze zdrojovému objektu, a to i když kopírujete v rámci jednoho účtu úložiště.

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. Ke kopírování můžete použít ověřování pomocí sdíleného klíče , protože tato operace kopíruje soubory v rámci stejného úč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í.

Sdílení snímků

Počínaje verzí 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 ve snímcích 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 konkrétní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íží s Azure Files pomocí metrik

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

Metriky pro Azure Files můžete povolit z 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 jeho analogů v klientské knihovně Azure Files.

Následující příklad kódu ukazuje, jak pomocí klientské knihovny .NET povolit metriky pro 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();
}

Pokud narazíte na nějaké problémy, přečtěte si téma Řešení potíží s Azure Files.

Další kroky

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

Koncepční články a videa

Podpora nástrojů pro úložiště File

Reference

Související ukázky kódu s využitím zastaralých sad SDK .NET verze 11.x najdete v tématu Ukázky kódu pomocí rozhraní .NET verze 11.x.