Överföra data med dataflyttbiblioteket

Azure Storage Data Movement-biblioteket är ett plattformsoberoende bibliotek med öppen källkod som är utformat för uppladdning, nedladdning och kopiering av blobar och filer med höga prestanda. Data movement-biblioteket innehåller praktiska metoder som inte är tillgängliga i Azure Storage-klientbiblioteket för .NET. Med de här metoderna kan du ange antalet parallella åtgärder, spåra överföringsframsteg, enkelt återuppta en avbruten överföring och mycket mer.

Det här biblioteket använder också .NET Core, vilket innebär att du kan använda det när du skapar .NET-appar för Windows, Linux och macOS. Mer information om .NET Core finns i .NET Core-dokumentationen. Det här biblioteket fungerar även för traditionella .NET Framework-appar för Windows.

Det här dokumentet visar hur du skapar ett .NET Core-konsolprogram som körs i Windows, Linux och macOS och utför följande scenarier:

• Ladda upp filer och kataloger till Blob Storage.
• Definiera antalet parallella åtgärder vid överföring av data.
• Spåra förloppet för dataöverföring.
• Återuppta avbruten dataöverföring.
• Kopiera filen från URL till Blob Storage.
• Kopiera från Blob Storage till Blob Storage.

Förutsättningar

• Visual Studio Code
• Ett Azure Storage-konto

Ställ in

1. Gå till installationsguiden för .NET Core för att installera .NET Core SDK. När du väljer din miljö väljer du kommandoradsalternativet.
2. Skapa en katalog för projektet från kommandoraden. Navigera till den här katalogen och skriv dotnet new console -o <sample-project-name> sedan för att skapa ett C#-konsolprojekt.
3. Öppna den här katalogen i Visual Studio Code. Det här steget kan snabbt utföras via kommandoraden genom att code . skriva i Windows.
4. Installera C#-tillägget från Visual Studio Code Marketplace. Starta om Visual Studio Code.
5. Nu bör du se två frågor. En är för att lägga till "nödvändiga tillgångar för att skapa och felsöka". Välj "ja". En annan uppmaning är att återställa olösta beroenden. Välj "återställ".
6. Ändra launch.json under .vscode för att använda extern terminal som en konsol. Den här inställningen bör läsas som "console": "externalTerminal"
7. Med Visual Studio Code kan du felsöka .NET Core-program. Tryck F5 för att köra programmet och kontrollera att konfigurationen fungerar. Du bör se "Hello World!" skrivs ut till konsolen.

Lägg till dataflyttbiblioteket i projektet

1. Lägg till den senaste versionen av dataflyttbiblioteket i dependencies avsnittet i <project-name>.csproj filen. I skrivande stund skulle den här versionen vara "Microsoft.Azure.Storage.DataMovement": "0.6.2"
2. En uppmaning ska visas för att återställa projektet. Välj knappen "återställ". Du kan också återställa projektet från kommandoraden genom att skriva kommandot dotnet restore i roten i projektkatalogen.

Ändra <project-name>.csproj:

<Project Sdk="Microsoft.NET.Sdk">
    <PropertyGroup>
        <OutputType>Exe</OutputType>
        <TargetFramework>netcoreapp2.0</TargetFramework>
    </PropertyGroup>
    <ItemGroup>
        <PackageReference Include="Microsoft.Azure.Storage.DataMovement" Version="0.6.2" />
        </ItemGroup>
    </Project>

Konfigurera programramverket

Det första vi gör är att konfigurera kodramverket för vårt program. Den här koden uppmanar oss att ange ett lagringskontonamn och en kontonyckel och använder dessa autentiseringsuppgifter för att skapa ett CloudStorageAccount objekt. Det här objektet används för att interagera med vårt lagringskonto i alla överföringsscenarier. Koden uppmanar oss också att välja vilken typ av överföringsåtgärd vi vill köra.

Ändra Program.cs:

using System;
using System.Threading;
using System.Threading.Tasks;
using System.Diagnostics;
using Microsoft.Azure.Storage;
using Microsoft.Azure.Storage.Blob;
using Microsoft.Azure.Storage.DataMovement;

namespace DMLibSample
{
    public class Program
    {
        public static void Main()
        {
            Console.WriteLine("Enter Storage account name:");
            string accountName = Console.ReadLine();

            Console.WriteLine("\nEnter Storage account key:");
            string accountKey = Console.ReadLine();

            string storageConnectionString = "DefaultEndpointsProtocol=https;AccountName=" + accountName + ";AccountKey=" + accountKey;
            CloudStorageAccount account = CloudStorageAccount.Parse(storageConnectionString);

            ExecuteChoice(account);
        }

        public static void ExecuteChoice(CloudStorageAccount account)
        {
            Console.WriteLine("\nWhat type of transfer would you like to execute?\n1. Local file --> Azure Blob\n2. Local directory --> Azure Blob directory\n3. URL (e.g. Amazon S3 file) --> Azure Blob\n4. Azure Blob --> Azure Blob");
            int choice = int.Parse(Console.ReadLine());

            if(choice == 1)
            {
                TransferLocalFileToAzureBlob(account).Wait();
            }
            else if(choice == 2)
            {
                TransferLocalDirectoryToAzureBlobDirectory(account).Wait();
            }
            else if(choice == 3)
            {
                TransferUrlToAzureBlob(account).Wait();
            }
            else if(choice == 4)
            {
                TransferAzureBlobToAzureBlob(account).Wait();
            }
        }

        public static async Task TransferLocalFileToAzureBlob(CloudStorageAccount account)
        {

        }

        public static async Task TransferLocalDirectoryToAzureBlobDirectory(CloudStorageAccount account)
        {

        }

        public static async Task TransferUrlToAzureBlob(CloudStorageAccount account)
        {

        }

        public static async Task TransferAzureBlobToAzureBlob(CloudStorageAccount account)
        {

        }
    }
}

Ladda upp en lokal fil till en blob

Lägg till metoderna GetSourcePath och GetBlob i Program.cs:

public static string GetSourcePath()
{
    Console.WriteLine("\nProvide path for source:");
    string sourcePath = Console.ReadLine();

    return sourcePath;
}

public static CloudBlockBlob GetBlob(CloudStorageAccount account)
{
    CloudBlobClient blobClient = account.CreateCloudBlobClient();

    Console.WriteLine("\nProvide name of Blob container:");
    string containerName = Console.ReadLine();
    CloudBlobContainer container = blobClient.GetContainerReference(containerName);
    container.CreateIfNotExistsAsync().Wait();

    Console.WriteLine("\nProvide name of new Blob:");
    string blobName = Console.ReadLine();
    CloudBlockBlob blob = container.GetBlockBlobReference(blobName);

    return blob;
}

TransferLocalFileToAzureBlob Ändra metoden:

public static async Task TransferLocalFileToAzureBlob(CloudStorageAccount account)
{
    string localFilePath = GetSourcePath();
    CloudBlockBlob blob = GetBlob(account);
    Console.WriteLine("\nTransfer started...");
    await TransferManager.UploadAsync(localFilePath, blob);
    Console.WriteLine("\nTransfer operation complete.");
    ExecuteChoice(account);
}

Den här koden uppmanar oss att ange sökvägen till en lokal fil, namnet på en ny eller befintlig container och namnet på en ny blob. Metoden TransferManager.UploadAsync utför uppladdningen med hjälp av den här informationen.

Tryck F5 för att köra programmet. Du kan kontrollera att uppladdningen inträffade genom att visa ditt Lagringskonto med Microsoft Azure Storage Explorer.

Ange antalet parallella åtgärder

Dataflyttbiblioteket ger möjlighet att ange antalet parallella åtgärder för att öka dataöverföringens dataflöde. Som standard anger Data Movement-biblioteket antalet parallella åtgärder till 8 * antalet kärnor på datorn.

Tänk på att många parallella åtgärder i en miljö med låg bandbredd kan överbelasta nätverksanslutningen och faktiskt förhindra att åtgärderna slutförs helt. Du bör experimentera med den här inställningen för att avgöra vad som fungerar bäst baserat på din tillgängliga nätverksbandbredd.

I det här exemplet lägger vi till kod som gör att vi kan ange antalet parallella åtgärder. Vi lägger också till kod som gånger tar hur lång tid det tar för överföringen att slutföras.

Lägg till en SetNumberOfParallelOperations metod i Program.cs:

public static void SetNumberOfParallelOperations()
{
    Console.WriteLine("\nHow many parallel operations would you like to use?");
    string parallelOperations = Console.ReadLine();
    TransferManager.Configurations.ParallelOperations = int.Parse(parallelOperations);
}

Ändra metoden så att den ExecuteChoice använder SetNumberOfParallelOperations:

public static void ExecuteChoice(CloudStorageAccount account)
{
    Console.WriteLine("\nWhat type of transfer would you like to execute?\n1. Local file --> Azure Blob\n2. Local directory --> Azure Blob directory\n3. URL (e.g. Amazon S3 file) --> Azure Blob\n4. Azure Blob --> Azure Blob");
    int choice = int.Parse(Console.ReadLine());

    SetNumberOfParallelOperations();

    if(choice == 1)
    {
        TransferLocalFileToAzureBlob(account).Wait();
    }
    else if(choice == 2)
    {
        TransferLocalDirectoryToAzureBlobDirectory(account).Wait();
    }
    else if(choice == 3)
    {
        TransferUrlToAzureBlob(account).Wait();
    }
    else if(choice == 4)
    {
        TransferAzureBlobToAzureBlob(account).Wait();
    }
}

Ändra metoden så att den TransferLocalFileToAzureBlob använder en timer:

public static async Task TransferLocalFileToAzureBlob(CloudStorageAccount account)
{
    string localFilePath = GetSourcePath();
    CloudBlockBlob blob = GetBlob(account);
    Console.WriteLine("\nTransfer started...");
    Stopwatch stopWatch = Stopwatch.StartNew();
    await TransferManager.UploadAsync(localFilePath, blob);
    stopWatch.Stop();
    Console.WriteLine("\nTransfer operation completed in " + stopWatch.Elapsed.TotalSeconds + " seconds.");
    ExecuteChoice(account);
}

Spåra överföringsstatus

Du kan spåra förloppet för överföringen under överföringsåtgärden genom att skapa ett TransferContext objekt. Objektet TransferContext finns i två former: SingleTransferContext för enskilda filöverföringar och DirectoryTransferContext för katalogöverföringar.

Lägg till metoderna GetSingleTransferContext och GetDirectoryTransferContext i Program.cs:

public static SingleTransferContext GetSingleTransferContext(TransferCheckpoint checkpoint)
{
    SingleTransferContext context = new SingleTransferContext(checkpoint);

    context.ProgressHandler = new Progress<TransferStatus>((progress) =>
    {
        Console.Write("\rBytes transferred: {0}", progress.BytesTransferred );
    });

    return context;
}

public static DirectoryTransferContext GetDirectoryTransferContext(TransferCheckpoint checkpoint)
{
    DirectoryTransferContext context = new DirectoryTransferContext(checkpoint);

    context.ProgressHandler = new Progress<TransferStatus>((progress) =>
    {
        Console.Write("\rBytes transferred: {0}", progress.BytesTransferred );
    });

    return context;
}

Ändra metoden så att den TransferLocalFileToAzureBlob använder GetSingleTransferContext:

public static async Task TransferLocalFileToAzureBlob(CloudStorageAccount account)
{
    string localFilePath = GetSourcePath();
    CloudBlockBlob blob = GetBlob(account);
    TransferCheckpoint checkpoint = null;
    SingleTransferContext context = GetSingleTransferContext(checkpoint);
    Console.WriteLine("\nTransfer started...\n");
    Stopwatch stopWatch = Stopwatch.StartNew();
    await TransferManager.UploadAsync(localFilePath, blob, null, context);
    stopWatch.Stop();
    Console.WriteLine("\nTransfer operation completed in " + stopWatch.Elapsed.TotalSeconds + " seconds.");
    ExecuteChoice(account);
}

Återuppta en avbruten överföring

En annan funktion som erbjuds av dataflyttbiblioteket är möjligheten att återuppta en avbruten överföring. Därefter lägger vi till kod som gör att vi tillfälligt kan avbryta överföringen genom att cskriva och sedan återuppta överföringen 3 sekunder senare.

Ändra metoden TransferLocalFileToAzureBlob:

public static async Task TransferLocalFileToAzureBlob(CloudStorageAccount account)
{
    string localFilePath = GetSourcePath();
    CloudBlockBlob blob = GetBlob(account);
    TransferCheckpoint checkpoint = null;
    SingleTransferContext context = GetSingleTransferContext(checkpoint);
    CancellationTokenSource cancellationSource = new CancellationTokenSource();
    Console.WriteLine("\nTransfer started...\nPress 'c' to temporarily cancel your transfer...\n");

    Stopwatch stopWatch = Stopwatch.StartNew();
    Task task;
    ConsoleKeyInfo keyinfo;
    try
    {
        task = TransferManager.UploadAsync(localFilePath, blob, null, context, cancellationSource.Token);
        while(!task.IsCompleted)
        {
            if(Console.KeyAvailable)
            {
                keyinfo = Console.ReadKey(true);
                if(keyinfo.Key == ConsoleKey.C)
                {
                    cancellationSource.Cancel();
                }
            }
        }
        await task;
    }
    catch(Exception e)
    {
        Console.WriteLine("\nThe transfer is canceled: {0}", e.Message);
    }

    if(cancellationSource.IsCancellationRequested)
    {
        Console.WriteLine("\nTransfer will resume in 3 seconds...");
        Thread.Sleep(3000);
        checkpoint = context.LastCheckpoint;
        context = GetSingleTransferContext(checkpoint);
        Console.WriteLine("\nResuming transfer...\n");
        await TransferManager.UploadAsync(localFilePath, blob, null, context);
    }

    stopWatch.Stop();
    Console.WriteLine("\nTransfer operation completed in " + stopWatch.Elapsed.TotalSeconds + " seconds.");
    ExecuteChoice(account);
}

Hittills har vårt checkpoint värde angetts till null. Om vi avbryter överföringen hämtar vi den sista kontrollpunkten för vår överföring och använder sedan den här nya kontrollpunkten i vår överföringskontext.

Överföra en lokal katalog till Blob Storage

Med dataflyttbiblioteket kan du överföra en katalog med filer och alla dess underkataloger, som du ser i följande exempel.

Lägg först till metoden GetBlobDirectory i Program.cs:

public static CloudBlobDirectory GetBlobDirectory(CloudStorageAccount account)
{
    CloudBlobClient blobClient = account.CreateCloudBlobClient();

    Console.WriteLine("\nProvide name of Blob container. This can be a new or existing Blob container:");
    string containerName = Console.ReadLine();
    CloudBlobContainer container = blobClient.GetContainerReference(containerName);
    container.CreateIfNotExistsAsync().Wait();

    CloudBlobDirectory blobDirectory = container.GetDirectoryReference("");

    return blobDirectory;
}

TransferLocalDirectoryToAzureBlobDirectoryÄndra sedan :

public static async Task TransferLocalDirectoryToAzureBlobDirectory(CloudStorageAccount account)
{
    string localDirectoryPath = GetSourcePath();
    CloudBlobDirectory blobDirectory = GetBlobDirectory(account);
    TransferCheckpoint checkpoint = null;
    DirectoryTransferContext context = GetDirectoryTransferContext(checkpoint);
    CancellationTokenSource cancellationSource = new CancellationTokenSource();
    Console.WriteLine("\nTransfer started...\nPress 'c' to temporarily cancel your transfer...\n");

    Stopwatch stopWatch = Stopwatch.StartNew();
    Task task;
    ConsoleKeyInfo keyinfo;
    UploadDirectoryOptions options = new UploadDirectoryOptions()
    {
        Recursive = true
    };

    try
    {
        task = TransferManager.UploadDirectoryAsync(localDirectoryPath, blobDirectory, options, context, cancellationSource.Token);
        while(!task.IsCompleted)
        {
            if(Console.KeyAvailable)
            {
                keyinfo = Console.ReadKey(true);
                if(keyinfo.Key == ConsoleKey.C)
                {
                    cancellationSource.Cancel();
                }
            }
        }
        await task;
    }
    catch(Exception e)
    {
        Console.WriteLine("\nThe transfer is canceled: {0}", e.Message);
    }

    if(cancellationSource.IsCancellationRequested)
    {
        Console.WriteLine("\nTransfer will resume in 3 seconds...");
        Thread.Sleep(3000);
        checkpoint = context.LastCheckpoint;
        context = GetDirectoryTransferContext(checkpoint);
        Console.WriteLine("\nResuming transfer...\n");
        await TransferManager.UploadDirectoryAsync(localDirectoryPath, blobDirectory, options, context);
    }

    stopWatch.Stop();
    Console.WriteLine("\nTransfer operation completed in " + stopWatch.Elapsed.TotalSeconds + " seconds.");
    ExecuteChoice(account);
}

Det finns några skillnader mellan den här metoden och metoden för att ladda upp en enda fil. Vi använder TransferManager.UploadDirectoryAsync nu och den getDirectoryTransferContext metod som vi skapade tidigare. Dessutom tillhandahåller vi nu ett options värde för vår uppladdningsåtgärd, vilket gör att vi kan ange att vi vill inkludera underkataloger i uppladdningen.

Kopiera en fil från URL till en blob

Nu ska vi lägga till kod som gör att vi kan kopiera en fil från en URL till en Azure Blob.

Ändra TransferUrlToAzureBlob:

public static async Task TransferUrlToAzureBlob(CloudStorageAccount account)
{
    Uri uri = new Uri(GetSourcePath());
    CloudBlockBlob blob = GetBlob(account);
    TransferCheckpoint checkpoint = null;
    SingleTransferContext context = GetSingleTransferContext(checkpoint);
    CancellationTokenSource cancellationSource = new CancellationTokenSource();
    Console.WriteLine("\nTransfer started...\nPress 'c' to temporarily cancel your transfer...\n");

    Stopwatch stopWatch = Stopwatch.StartNew();
    Task task;
    ConsoleKeyInfo keyinfo;
    try
    {
        task = TransferManager.CopyAsync(uri, blob, CopyMethod.ServiceSideAsyncCopy, null, context, cancellationSource.Token);
        while(!task.IsCompleted)
        {
            if(Console.KeyAvailable)
            {
                keyinfo = Console.ReadKey(true);
                if(keyinfo.Key == ConsoleKey.C)
                {
                    cancellationSource.Cancel();
                }
            }
        }
        await task;
    }
    catch(Exception e)
    {
        Console.WriteLine("\nThe transfer is canceled: {0}", e.Message);
    }

    if(cancellationSource.IsCancellationRequested)
    {
        Console.WriteLine("\nTransfer will resume in 3 seconds...");
        Thread.Sleep(3000);
        checkpoint = context.LastCheckpoint;
        context = GetSingleTransferContext(checkpoint);
        Console.WriteLine("\nResuming transfer...\n");
        await TransferManager.CopyAsync(uri, blob, CopyMethod.ServiceSideAsyncCopy, null, context, cancellationSource.Token);
    }

    stopWatch.Stop();
    Console.WriteLine("\nTransfer operation completed in " + stopWatch.Elapsed.TotalSeconds + " seconds.");
    ExecuteChoice(account);
}

Ett viktigt användningsfall för den här funktionen är när du behöver flytta data från en annan molntjänst till Azure. Om du har en URL som ger dig åtkomst till resursen kan du enkelt flytta resursen TransferManager.CopyAsync till Azure Blobs med hjälp av metoden . Den här metoden introducerar även en CopyMethod-parameter . I följande tabell visas tillgängliga alternativ för den här parametern:

Kopiera en blob

En annan funktion som tillhandahålls av dataflyttbiblioteket är möjligheten att kopiera från en Azure Storage-resurs till en annan.

Ändra metoden TransferAzureBlobToAzureBlob:

public static async Task TransferAzureBlobToAzureBlob(CloudStorageAccount account)
{
    CloudBlockBlob sourceBlob = GetBlob(account);
    CloudBlockBlob destinationBlob = GetBlob(account);
    TransferCheckpoint checkpoint = null;
    SingleTransferContext context = GetSingleTransferContext(checkpoint);
    CancellationTokenSource cancellationSource = new CancellationTokenSource();
    Console.WriteLine("\nTransfer started...\nPress 'c' to temporarily cancel your transfer...\n");

    Stopwatch stopWatch = Stopwatch.StartNew();
    Task task;
    ConsoleKeyInfo keyinfo;
    try
    {
        task = TransferManager.CopyAsync(sourceBlob, destinationBlob, CopyMethod.SyncCopy, null, context, cancellationSource.Token);
        while(!task.IsCompleted)
        {
            if(Console.KeyAvailable)
            {
                keyinfo = Console.ReadKey(true);
                if(keyinfo.Key == ConsoleKey.C)
                {
                    cancellationSource.Cancel();
                }
            }
        }
        await task;
    }
    catch(Exception e)
    {
        Console.WriteLine("\nThe transfer is canceled: {0}", e.Message);
    }

    if(cancellationSource.IsCancellationRequested)
    {
        Console.WriteLine("\nTransfer will resume in 3 seconds...");
        Thread.Sleep(3000);
        checkpoint = context.LastCheckpoint;
        context = GetSingleTransferContext(checkpoint);
        Console.WriteLine("\nResuming transfer...\n");
        await TransferManager.CopyAsync(sourceBlob, destinationBlob, CopyMethod.SyncCopy, null, context, cancellationSource.Token);
    }

    stopWatch.Stop();
    Console.WriteLine("\nTransfer operation completed in " + stopWatch.Elapsed.TotalSeconds + " seconds.");
    ExecuteChoice(account);
}

I det här exemplet anger vi den booleska parametern i TransferManager.CopyAsync för CopyMethod.SyncCopy att indikera att vi vill göra en synkron kopia. Den här konfigurationen innebär att resursen laddas ned till vår lokala dator först och sedan laddas upp till Azure Blob. Det synkrona kopieringsalternativet är ett bra sätt att se till att kopieringsåtgärden har en konsekvent hastighet. Däremot beror hastigheten på en asynkron kopia på serversidan på den tillgängliga nätverksbandbredden på servern, vilket kan variera. Synkron kopiering kan dock generera ytterligare utgående kostnad jämfört med asynkron kopia. Den rekommenderade metoden är att använda synkron kopiering på en virtuell Azure-dator som finns i samma region som ditt källlagringskonto för att undvika utgående kostnader.

Dataförflyttningsprogrammet är nu klart. Det fullständiga kodexemplet är tillgängligt på GitHub.

Nästa steg

Referensdokumentation för Azure Storage Data Movement-biblioteket.