Share via

Een blob uploaden met .NET

  • Artikel

In dit artikel wordt beschreven hoe u een blob uploadt met behulp van de Azure Storage-clientbibliotheek voor .NET. U kunt gegevens uploaden naar een blok-blob vanuit een bestandspad, een stroom, een binair object of een tekenreeks. U kunt ook een blobstream openen en ernaar schrijven of grote blobs in blokken uploaden.

Vereisten

Uw omgeving instellen

Als u geen bestaand project hebt, ziet u in deze sectie hoe u een project instelt voor gebruik met de Azure Blob Storage-clientbibliotheek voor .NET. De stappen omvatten pakketinstallatie, het toevoegen van using instructies en het maken van een geautoriseerd clientobject. Zie Aan de slag met Azure Blob Storage en .NET voor meer informatie.

Pakketten installeren

Installeer vanuit uw projectmap pakketten voor de Azure Blob Storage- en Azure Identity-clientbibliotheken met behulp van de dotnet add package opdracht. Het Azure.Identity-pakket is nodig voor verbindingen zonder wachtwoord met Azure-services.

dotnet add package Azure.Storage.Blobs
dotnet add package Azure.Identity

Voeg using-instructies toe

Voeg deze using instructies toe aan het begin van het codebestand:

using Azure.Identity;
using Azure.Storage.Blobs;
using Azure.Storage.Blobs.Models;
using Azure.Storage.Blobs.Specialized;

Voor sommige codevoorbeelden in dit artikel zijn mogelijk aanvullende using instructies vereist.

Een clientobject maken

Als u een app wilt verbinden met Blob Storage, maakt u een exemplaar van BlobServiceClient. In het volgende voorbeeld ziet u hoe u een clientobject maakt met behulp van DefaultAzureCredential autorisatie:

public BlobServiceClient GetBlobServiceClient(string accountName)
{
    BlobServiceClient client = new(
        new Uri($"https://{accountName}.blob.core.windows.net"),
        new DefaultAzureCredential());

    return client;
}

U kunt een serviceclient registreren voor afhankelijkheidsinjectie in een .NET-app.

U kunt ook clientobjecten maken voor specifieke containers of blobs. Zie Clientobjecten maken en beheren die interactie hebben met gegevensbronnen voor meer informatie over het maken en beheren van clientobjecten.

Autorisatie

Het autorisatiemechanisme moet over de benodigde machtigingen beschikken om een blob te kunnen uploaden. Voor autorisatie met Microsoft Entra ID (aanbevolen) hebt u ingebouwde Azure RBAC-rol Opslagblobgegevensbijdrager of hoger nodig. Zie de autorisatierichtlijnen voor Put Blob (REST API) en Put Block (REST API) voor meer informatie.

Gegevens uploaden naar een blok-blob

U kunt een van de volgende methoden gebruiken om gegevens te uploaden naar een blok-blob:

Wanneer u deze uploadmethoden gebruikt, kan de clientbibliotheek Put Blob of een reeks Put Block-aanroepen aanroepen, gevolgd door Put Block List. Dit gedrag is afhankelijk van de totale grootte van het object en hoe de opties voor gegevensoverdracht worden ingesteld.

Als u een stream in Blob Storage wilt openen en naar die stream wilt schrijven, gebruikt u een van de volgende methoden:

Een blok-blob uploaden vanuit een lokaal bestandspad

In het volgende voorbeeld wordt een blok-blob geüpload vanuit een lokaal bestandspad:

public static async Task UploadFromFileAsync(
    BlobContainerClient containerClient,
    string localFilePath)
{
    string fileName = Path.GetFileName(localFilePath);
    BlobClient blobClient = containerClient.GetBlobClient(fileName);

    await blobClient.UploadAsync(localFilePath, true);
}

Een blok-blob uploaden vanuit een stream

In het volgende voorbeeld wordt een blok-blob geüpload door een Stream-object te maken en de stream te uploaden.

public static async Task UploadFromStreamAsync(
    BlobContainerClient containerClient,
    string localFilePath)
{
    string fileName = Path.GetFileName(localFilePath);
    BlobClient blobClient = containerClient.GetBlobClient(fileName);

    FileStream fileStream = File.OpenRead(localFilePath);
    await blobClient.UploadAsync(fileStream, true);
    fileStream.Close();
}

Een blok-blob uploaden vanuit een BinaryData-object

In het volgende voorbeeld wordt een blok-blob geüpload vanuit een BinaryData-object .

public static async Task UploadFromBinaryDataAsync(
    BlobContainerClient containerClient,
    string localFilePath)
{
    string fileName = Path.GetFileName(localFilePath);
    BlobClient blobClient = containerClient.GetBlobClient(fileName);

    FileStream fileStream = File.OpenRead(localFilePath);
    BinaryReader reader = new BinaryReader(fileStream);

    byte[] buffer = new byte[fileStream.Length];
    reader.Read(buffer, 0, buffer.Length);
    BinaryData binaryData = new BinaryData(buffer);

    await blobClient.UploadAsync(binaryData, true);

    fileStream.Close();
}

Een blok-blob uploaden vanuit een tekenreeks

In het volgende voorbeeld wordt een blok-blob vanuit een tekenreeks geüpload:

public static async Task UploadFromStringAsync(
    BlobContainerClient containerClient,
    string blobName)
{
    BlobClient blobClient = containerClient.GetBlobClient(blobName);
    string blobContents = "Sample blob data";

    await blobClient.UploadAsync(BinaryData.FromString(blobContents), overwrite: true);
}

Uploaden naar een stream in Blob Storage

U kunt een stream openen in Blob Storage en ernaar schrijven. In het volgende voorbeeld wordt een zip-bestand gemaakt in Blob Storage en worden er bestanden naar geschreven. In plaats van een zip-bestand te bouwen in het lokale geheugen, bevindt zich slechts één bestand tegelijk in het geheugen.

public static async Task UploadToStreamAsync(
    BlobContainerClient containerClient,
    string localDirectoryPath)
{
    string zipFileName = Path.GetFileName(
        Path.GetDirectoryName(localDirectoryPath)) + ".zip";

    BlockBlobClient blockBlobClient = containerClient.GetBlockBlobClient(zipFileName);

    using (Stream stream = await blockBlobClient.OpenWriteAsync(true))
    {
        using (ZipArchive zip = new ZipArchive(stream, ZipArchiveMode.Create, leaveOpen: false))
        {
            foreach (var fileName in Directory.EnumerateFiles(localDirectoryPath))
            {
                using (var fileStream = File.OpenRead(fileName))
                {
                    var entry = zip.CreateEntry(
                        Path.GetFileName(fileName), CompressionLevel.Optimal);
                    using (var innerFile = entry.Open())
                    {
                        await fileStream.CopyToAsync(innerFile);
                    }
                }
            }
        }
    }
}

Een blok-blob uploaden met configuratieopties

U kunt configuratieopties voor clientbibliotheek definiëren bij het uploaden van een blob. Deze opties kunnen worden afgestemd om de prestaties te verbeteren, de betrouwbaarheid te verbeteren en de kosten te optimaliseren. In de volgende codevoorbeelden ziet u hoe u BlobUploadOptions gebruikt om configuratieopties te definiëren bij het aanroepen van een uploadmethode.

Opties voor gegevensoverdracht opgeven bij uploaden

U kunt de waarden in StorageTransferOptions configureren om de prestaties voor gegevensoverdrachtbewerkingen te verbeteren. In het volgende codevoorbeeld ziet u hoe u waarden instelt voor StorageTransferOptions en de opties opneemt als onderdeel van een BlobUploadOptions exemplaar. De waarden in dit voorbeeld zijn niet bedoeld als aanbeveling. Als u deze waarden goed wilt afstemmen, moet u rekening houden met de specifieke behoeften van uw app.

public static async Task UploadWithTransferOptionsAsync(
    BlobContainerClient containerClient,
    string localFilePath)
{
    string fileName = Path.GetFileName(localFilePath);
    BlobClient blobClient = containerClient.GetBlobClient(fileName);

    var transferOptions = new StorageTransferOptions
    {
        // Set the maximum number of parallel transfer workers
        MaximumConcurrency = 2,

        // Set the initial transfer length to 8 MiB
        InitialTransferSize = 8 * 1024 * 1024,

        // Set the maximum length of a transfer to 4 MiB
        MaximumTransferSize = 4 * 1024 * 1024
    };

    var uploadOptions = new BlobUploadOptions()
    {
        TransferOptions = transferOptions
    };

    FileStream fileStream = File.OpenRead(localFilePath);
    await blobClient.UploadAsync(fileStream, uploadOptions);
    fileStream.Close();
}

Zie Prestaties afstemmen voor uploads en downloads met .NET voor meer informatie over het afstemmen van opties voor het afstemmen van gegevensoverdracht.

Opties voor overdrachtvalidatie opgeven bij uploaden

U kunt opties voor overdrachtvalidatie opgeven om ervoor te zorgen dat gegevens correct worden geüpload en niet zijn gemanipuleerd tijdens de overdracht. Validatieopties voor overdracht kunnen worden gedefinieerd op clientniveau met behulp van BlobClientOptions, waarmee validatieopties worden toegepast op alle methoden die worden aangeroepen vanuit een BlobClient-exemplaar .

U kunt ook opties voor overdrachtvalidatie op methodeniveau overschrijven met behulp van BlobUploadOptions. In het volgende codevoorbeeld ziet u hoe u een BlobUploadOptions object maakt en een algoritme opgeeft voor het genereren van een controlesom. De controlesom wordt vervolgens door de service gebruikt om de gegevensintegriteit van de geüploade inhoud te verifiëren.

public static async Task UploadWithChecksumAsync(
    BlobContainerClient containerClient,
    string localFilePath)
{
    string fileName = Path.GetFileName(localFilePath);
    BlobClient blobClient = containerClient.GetBlobClient(fileName);

    var validationOptions = new UploadTransferValidationOptions
    {
        ChecksumAlgorithm = StorageChecksumAlgorithm.Auto
    };

    var uploadOptions = new BlobUploadOptions()
    {
        TransferValidation = validationOptions
    };

    FileStream fileStream = File.OpenRead(localFilePath);
    await blobClient.UploadAsync(fileStream, uploadOptions);
    fileStream.Close();
}

In de volgende tabel ziet u de beschikbare opties voor het controlesomalgoritme, zoals gedefinieerd door StorageChecksumAlgorithm:

Naam Weergegeven als Beschrijving
Auto 0 Aanbevolen. Hiermee kan de bibliotheek een algoritme kiezen. Verschillende bibliotheekversies kunnen verschillende algoritmen kiezen.
Geen 1 Geen geselecteerd algoritme. Bereken of vraag controlesommen niet aan.
MD5 2 Standaard MD5-hash-algoritme.
StorageCrc64 3 Aangepaste 64-bits CRC van Azure Storage.

Notitie

Als de controlesom die is opgegeven in de aanvraag niet overeenkomt met de controlesom die door de service wordt berekend, mislukt de uploadbewerking. De bewerking wordt niet opnieuw geprobeerd wanneer u een standaardbeleid voor opnieuw proberen gebruikt. In .NET wordt er een RequestFailedException gegenereerd met statuscode 400 en foutcode Md5Mismatch of Crc64Mismatch, afhankelijk van welk algoritme wordt gebruikt.

Uploaden met indextags

Blob-indextags categoriseren gegevens in uw opslagaccount met behulp van tagkenmerken met sleutelwaarde. Deze tags worden automatisch geïndexeerd en weergegeven als doorzoekbare multidimensionale index om eenvoudig gegevens te vinden. U kunt tags toevoegen aan een BlobUploadOptions-exemplaar en dat exemplaar doorgeven aan de UploadAsync methode.

In het volgende voorbeeld wordt een blok-blob met indextags geüpload:

public static async Task UploadBlobWithTagsAsync(
    BlobContainerClient containerClient,
    string blobName)
{
    BlobClient blobClient = containerClient.GetBlobClient(blobName);
    string blobContents = "Sample blob data";

    BlobUploadOptions options = new BlobUploadOptions();
    options.Tags = new Dictionary<string, string>
    {
        { "Sealed", "false" },
        { "Content", "image" },
        { "Date", "2020-04-20" }
    };

    await blobClient.UploadAsync(BinaryData.FromString(blobContents), options);
}

De toegangslaag van een blob instellen bij uploaden

U kunt de toegangslaag van een blob instellen bij uploaden met behulp van de klasse BlobUploadOptions . In het volgende codevoorbeeld ziet u hoe u de toegangslaag instelt bij het uploaden van een blob:

public static async Task UploadWithAccessTierAsync(
    BlobContainerClient containerClient,
    string localFilePath)
{
    string fileName = Path.GetFileName(localFilePath);
    BlockBlobClient blockBlobClient = containerClient.GetBlockBlobClient(fileName);

    var uploadOptions = new BlobUploadOptions()
    {
        AccessTier = AccessTier.Cool
    };

    FileStream fileStream = File.OpenRead(localFilePath);
    await blockBlobClient.UploadAsync(fileStream, uploadOptions);
    fileStream.Close();
}

Het instellen van de toegangslaag is alleen toegestaan voor blok-blobs. U kunt de toegangslaag voor een blok-blob instellen op Hot, Coolof ArchiveCold. Als u de toegangslaag wilt Coldinstellen, moet u een minimale clientbibliotheekversie van 12.15.0 gebruiken.

Zie het overzicht van Access-lagen voor meer informatie over toegangslagen.

Een blok-blob uploaden door blokken te faseren en doorvoeren

U kunt meer controle hebben over het verdelen van uploads in blokken door afzonderlijke gegevensblokken handmatig te faseren. Wanneer alle blokken waaruit een blob bestaat zijn gefaseerd, kunt u ze doorvoeren in Blob Storage. U kunt deze methode gebruiken om de prestaties te verbeteren door blokken parallel te uploaden.

public static async Task UploadBlocksAsync(
    BlobContainerClient blobContainerClient,
    string localFilePath,
    int blockSize)
{
    string fileName = Path.GetFileName(localFilePath);
    BlockBlobClient blobClient = blobContainerClient.GetBlockBlobClient(fileName);

    FileStream fileStream = File.OpenRead(localFilePath);
    ArrayList blockIDArrayList = new ArrayList();
    byte[] buffer;

    var bytesLeft = (fileStream.Length - fileStream.Position);

    while (bytesLeft > 0)
    {
        if (bytesLeft >= blockSize)
        {
            buffer = new byte[blockSize];
            await fileStream.ReadAsync(buffer, 0, blockSize);
        }
        else
        {
            buffer = new byte[bytesLeft];
            await fileStream.ReadAsync(buffer, 0, Convert.ToInt32(bytesLeft));
            bytesLeft = (fileStream.Length - fileStream.Position);
        }

        using (var stream = new MemoryStream(buffer))
        {
            string blockID = Convert.ToBase64String(
                Encoding.UTF8.GetBytes(Guid.NewGuid().ToString()));

            blockIDArrayList.Add(blockID);
            await blobClient.StageBlockAsync(blockID, stream);
        }
        bytesLeft = (fileStream.Length - fileStream.Position);
    }

    string[] blockIDArray = (string[])blockIDArrayList.ToArray(typeof(string));

    await blobClient.CommitBlockListAsync(blockIDArray);
}

Resources

Zie de volgende resources voor meer informatie over het uploaden van blobs met behulp van de Azure Blob Storage-clientbibliotheek voor .NET.

REST API-bewerkingen

De Azure SDK voor .NET bevat bibliotheken die zijn gebaseerd op de Azure REST API, zodat u kunt communiceren met REST API-bewerkingen via bekende .NET-paradigma's. De clientbibliotheekmethoden voor het uploaden van blobs gebruiken de volgende REST API-bewerkingen:

Codevoorbeelden

Zie ook