Vývoj pro Soubory Azure pomocí .NET

Seznamte se se základy vývoje aplikací .NET, které používají soubory Azure k ukládání dat. V tomto článku se dozvíte, jak vytvořit jednoduchou konzolovou aplikaci, která provede následující akce se soubory .NET a Azure:

  • Získá obsah souboru.
  • Nastavte maximální velikost nebo kvótu pro sdílenou složku.
  • Vytvoření sdíleného přístupového podpisu (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ří snímek sdílené složky.
  • Obnovte soubor ze snímku sdílené složky.
  • pro řešení potíží použijte Azure Storage metriky.

Další informace o službě soubory Azure 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
Standardní sdílené složky (GPv2), LRS/ZRS Yes No
Standardní sdílené složky (GPv2), GRS/GZRS Yes No
Premium sdílené složky (úložiště souborů), 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 rozhraní .NET rozhraní System.IO Azure.Storage.Files.Shares API a tyto přístupy abstraktní.

rozhraní API Kdy je použít Poznámky
System.IO Vaše aplikace:
  • Musí číst/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.
I/O souborů implementovaných pomocí služby Azure Files přes SMB je obvykle stejné jako u vstupu a výstupu pomocí libovolné síťové sdílené složky nebo místního úložného zařízení. Úvod do řady funkcí v rozhraní .NET, včetně vstupně-výstupních operací se soubory, najdete v kurzu konzolové aplikace .
Azure. Storage. Soubory. sdílené složky Vaše aplikace:
  • K souborům Azure nelze přistupovat pomocí protokolu SMB na portu 445 z důvodu omezení 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 se soubory pomocí REST místo SMB a správy sdílené složky.

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

Knihovnu klienta soubory Azure můžete použít v jakémkoli typu aplikace .NET. Mezi tyto aplikace patří 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 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 možnosti 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 Program třídy v 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ů

Podívejte se na tyto balíčky v projektu:

balíčky můžete získat pomocí NuGet. Postupujte takto:

  1. v Průzkumník řešení klikněte pravým tlačítkem myši na projekt a vyberte možnost spravovat balíčky NuGet.

  2. v NuGet Správce balíčků 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. Struktur
    • Azure. Storage. Soubory. sdílené složky
    • System.Configuration.ConfigurationManager

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

Potom uložte své přihlašovací údaje do souboru App.config projektu. V Průzkumník řešení dvakrát klikněte App.config a upravte soubor 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>

Poznámka

Emulátor úložiště Azurite v současné době nepodporuje soubory Azure. Aby váš připojovací řetězec mohl pracovat se soubory Azure, musí cílit na účet služby Azure Storage 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 programový přístup ke sdílené složky.

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. Tuto metodu volejte 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é 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ílené složky omezuje celkovou velikost souborů uložených ve sdíleném souboru. Pokud celková velikost souborů ve sdíleném souboru překračuje kvótu, klienti ji nezvětšují. Klienti také nebudou moci 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é Azure Files můžete vygenerovat sdílený přístupový podpis (SAS) pro sdílenou složku nebo pro jednotlivý soubor.

Následující příklad metody vrátí SAS pro soubor v zadané sdílené složky.

//-------------------------------------------------
// 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 sdílený přístupový podpis funguje.

Kopírování souborů

Od verze 5.x klientské knihovny Azure Files můžete zkopírovat soubor do jiného souboru, soubor do objektu blob nebo objekt 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 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í.

Snímky sdílené složky

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é složky 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 vypíše snímky ve sdílené složky.

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

Zobrazení seznamu souborů a adresářů v rámci snímků sdílené složky

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é složky

Pořízení snímku sdílené složky umožňuje obnovit jednotlivé soubory nebo celou 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í Azure Files s využitím metrik

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

Metriky můžete povolit pro Azure Files z Azure Portal. Metriky můžete povolit také programově voláním operace Set File Service Properties (Nastavit vlastnosti služby souborů) pomocí REST API nebo jedné z jejích analogií v klientské Azure Files knihovně.

Následující příklad kódu ukazuje, jak použít klientskou knihovnu .NET k povolení metrik 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 článek Řešení potíží s Azure Files v Windows.

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