Quickstart: clientbibliotheek Azure Blob Storage voor .NET

Aan de slag met de Azure Blob Storage-clientbibliotheek voor .NET. Azure Blob Storage is de oplossing voor opslag van objecten in de cloud van Microsoft. Volg deze stappen om het pakket te installeren en voorbeeldcode voor basistaken uit te proberen. Blob Storage is geoptimaliseerd voor het opslaan van enorme hoeveelheden niet-structureerde gegevens.

API-referentiedocumentatie | Broncode van bibliotheek | Pakket (NuGet) | Samples

Vereisten

Instellen

In deze sectie wordt uitgelegd hoe u een project voorbereidt voor gebruik met de Azure Blob Storage-clientbibliotheek voor .NET.

Het project maken

Voor de volgende stappen moet u een .NET-console-app maken met behulp van de .NET CLI of Visual Studio 2022.

  1. Navigeer bovenaan Visual Studio naar Bestand>Nieuw>project...

  2. Voer in het dialoogvenster console-app in het zoekvak van de projectsjabloon in en selecteer het eerste resultaat. Kies Volgende onderaan het dialoogvenster.

    Een schermopname die laat zien hoe u een nieuw project maakt met Visual Studio.

  3. Voer bij ProjectnaamBlobQuickstart in. Laat de standaardwaarden voor de rest van de velden staan en selecteer Volgende.

  4. Zorg ervoor dat voor framework .NET 6.0 is geselecteerd. Kies Maken. Het nieuwe project wordt geopend in de Visual Studio-omgeving.

Het pakket installeren

Als u wilt communiceren met Azure Blob Storage, installeert u de Azure Blob Storage-clientbibliotheek voor .NET.

  1. Klik in Solution Explorer met de rechtermuisknop op het knooppunt Afhankelijkheden van uw project. Selecteer NuGet-pakketten beheren.

  2. Zoek in het resulterende venster naar Azure.Storage.Blobs. Selecteer het juiste resultaat en selecteer Installeren.

    Een schermopname die laat zien hoe u een nieuw pakket toevoegt met behulp van Visual Studio.

De app-code instellen

Vervang de begincode in het Program.cs bestand zodat deze overeenkomt met het volgende voorbeeld, dat de benodigde using instructies voor deze oefening bevat.

using Azure.Storage.Blobs;
using Azure.Storage.Blobs.Models;
using System;
using System.IO;

// See https://aka.ms/new-console-template for more information
Console.WriteLine("Hello, World!");

Verifiëren bij Azure en toegang tot blobgegevens autoriseren

Toepassingsaanvragen voor Azure Blob Storage moeten worden geautoriseerd. Het gebruik van de DefaultAzureCredential klasse die wordt geleverd door de Azure Identity-clientbibliotheek is de aanbevolen methode voor het implementeren van verbindingen zonder wachtwoord met Azure-services in uw code, inclusief Blob Storage.

U kunt aanvragen voor Azure Blob Storage ook autoriseren met behulp van de toegangssleutel voor het account. Deze benadering moet echter met de nodige voorzichtigheid worden gebruikt. Ontwikkelaars moeten ijverig zijn om de toegangssleutel nooit beschikbaar te maken op een onbeveiligde locatie. Iedereen met de toegangssleutel kan aanvragen voor het opslagaccount autoriseren en heeft effectief toegang tot alle gegevens. DefaultAzureCredential biedt verbeterde beheer- en beveiligingsvoordelen ten opzichte van de accountsleutel om verificatie zonder wachtwoord toe te staan. Beide opties worden in het volgende voorbeeld gedemonstreerd.

DefaultAzureCredential is een klasse die wordt geleverd door de Azure Identity-clientbibliotheek voor .NET, waarover u meer informatie kunt vinden in het overzicht DefaultAzureCredential. DefaultAzureCredential ondersteunt meerdere verificatiemethoden en bepaalt welke methode tijdens runtime moet worden gebruikt. Met deze benadering kan uw app verschillende verificatiemethoden gebruiken in verschillende omgevingen (lokaal versus productie) zonder omgevingsspecifieke code te implementeren.

De volgorde en locaties waarin DefaultAzureCredential naar referenties wordt gezocht, vindt u in het overzicht van de Azure Identity-bibliotheek.

Uw app kan zich bijvoorbeeld verifiëren met behulp van uw Visual Studio-aanmeldingsreferenties bij het ontwikkelen van lokaal. Uw app kan vervolgens een beheerde identiteit gebruiken zodra deze in Azure is geïmplementeerd. Er zijn geen codewijzigingen vereist voor deze overgang.

Rollen toewijzen aan uw Azure AD-gebruikersaccount

Wanneer u lokaal ontwikkelt, moet u ervoor zorgen dat het gebruikersaccount dat toegang heeft tot blobgegevens, de juiste machtigingen heeft. U hebt Storage Blob Data Contributor nodig om blobgegevens te kunnen lezen en schrijven. Als u uzelf deze rol wilt toewijzen, moet u de rol Beheerder voor gebruikerstoegang of een andere rol met de actie Microsoft.Authorization/roleAssignments/write krijgen toegewezen. U kunt Azure RBAC-rollen toewijzen aan een gebruiker met behulp van de Azure Portal, Azure CLI of Azure PowerShell. Meer informatie over de beschikbare bereiken voor roltoewijzingen vindt u op de pagina bereikoverzicht .

In dit scenario wijst u machtigingen toe aan uw gebruikersaccount, binnen het bereik van het opslagaccount, om het principe van minimale bevoegdheden te volgen. Deze procedure biedt gebruikers alleen de minimale machtigingen die nodig zijn en maakt veiligere productieomgevingen.

In het volgende voorbeeld wordt de rol Bijdrager voor opslagblobgegevens toegewezen aan uw gebruikersaccount, die zowel lees- als schrijftoegang biedt tot blobgegevens in uw opslagaccount.

Belangrijk

In de meeste gevallen duurt het een paar minuten voordat de roltoewijzing is doorgegeven in Azure, maar in zeldzame gevallen kan het maximaal acht minuten duren. Als u verificatiefouten krijgt wanneer u de code voor het eerst uitvoert, wacht u even en probeert u het opnieuw.

  1. Zoek in de Azure Portal uw opslagaccount met behulp van de hoofdzoekbalk of linkernavigatiebalk.

  2. Selecteer op de overzichtspagina van het opslagaccount de optie Toegangsbeheer (IAM) in het menu aan de linkerkant.

  3. Selecteer op de pagina Toegangsbeheer (IAM) het tabblad Roltoewijzingen .

  4. Selecteer + Toevoegen in het bovenste menu en vervolgens Roltoewijzing toevoegen in de resulterende vervolgkeuzelijst.

    Een schermopname die laat zien hoe u een rol toewijst.

  5. Gebruik het zoekvak om de resultaten te filteren op de gewenste rol. Zoek in dit voorbeeld naar Inzender voor opslagblobgegevens , selecteer het overeenkomende resultaat en kies volgende.

  6. Selecteer onder Toegang toewijzen aande optie Gebruiker, groep of service-principal en kies vervolgens + Leden selecteren.

  7. Zoek in het dialoogvenster naar uw Azure AD gebruikersnaam (meestal uw user@domain e-mailadres) en kies vervolgens Selecteren onderaan het dialoogvenster.

  8. Selecteer Beoordelen en toewijzen om naar de laatste pagina te gaan en klik vervolgens nogmaals op Controleren + toewijzen om het proces te voltooien.

Meld u aan en verbind uw app-code met Azure met behulp van DefaultAzureCredential

U kunt de toegang tot gegevens in uw opslagaccount autoriseren met behulp van de volgende stappen:

  1. Zorg ervoor dat u bent geverifieerd met hetzelfde Azure AD account waaraan u de rol hebt toegewezen. U kunt zich verifiëren via de Azure CLI, Visual Studio of Azure PowerShell.

    Meld u aan bij Azure via de Azure CLI met behulp van de volgende opdracht:

    az login
    
  2. Als u wilt gebruiken DefaultAzureCredential, voegt u het pakket Azure.Identity toe aan uw toepassing.

    1. Klik in Solution Explorer met de rechtermuisknop op het knooppunt Afhankelijkheden van uw project. Selecteer NuGet-pakketten beheren.

    2. Zoek in het resulterende venster naar Azure.Identity. Selecteer het juiste resultaat en selecteer Installeren.

      Een schermopname die laat zien hoe u het identiteitspakket toevoegt.

  3. Werk uw Program.cs-code bij zodat deze overeenkomt met het volgende voorbeeld. Wanneer de code tijdens de ontwikkeling op uw lokale werkstation wordt uitgevoerd, worden de ontwikkelaarsreferenties van het hulpprogramma met prioriteit waarbij u bent aangemeld, gebruikt om te verifiëren bij Azure, zoals de Azure CLI of Visual Studio.

    using Azure.Storage.Blobs;
    using Azure.Storage.Blobs.Models;
    using System;
    using System.IO;
    using Azure.Identity;
    
    // TODO: Replace <storage-account-name> with your actual storage account name
    var blobServiceClient = new BlobServiceClient(
            new Uri("https://<storage-account-name>.blob.core.windows.net"),
            new DefaultAzureCredential());
    
  4. Zorg ervoor dat u de naam van het opslagaccount bijwerkt in de URI van uw BlobServiceClient. De naam van het opslagaccount vindt u op de overzichtspagina van de Azure Portal.

    Een schermopname die laat zien hoe u de naam van het opslagaccount kunt vinden.

    Notitie

    Wanneer deze code wordt geïmplementeerd in Azure, kan deze code worden gebruikt om aanvragen voor Azure Storage te autoriseren vanuit een toepassing die wordt uitgevoerd in Azure. U moet echter een beheerde identiteit inschakelen voor uw app in Azure. Configureer vervolgens uw opslagaccount zodat deze beheerde identiteit verbinding kan maken. Zie de zelfstudie Auth from Azure-hosted apps (Verificatie vanuit door Azure gehoste apps ) voor gedetailleerde instructies over het configureren van deze verbinding tussen Azure-services.

Objectmodel

Azure Blob Storage is geoptimaliseerd voor het opslaan van grote hoeveelheden ongestructureerde gegevens. Ongestructureerde gegevens voldoen niet aan een bepaald gegevensmodel of bepaalde definitie, zoals tekst of binaire gegevens. Er zijn drie typen resources voor blobopslag:

  • Het opslagaccount
  • Een container in het opslagaccount
  • Een blob in de container

Het volgende diagram geeft de relatie tussen deze resources weer.

Diagram van blobopslagarchitectuur.

Gebruik de volgende .NET-klassen om te communiceren met deze resources:

  • BlobServiceClient: Met de klasse BlobServiceClient kunt u Azure Storage-resources en blob-containers bewerken.
  • BlobContainerClient: Met de klasse BlobContainerClient kunt u Azure Storage-containers en de bijbehorende blobs bewerken.
  • BlobClient: Met de klasse BlobClient kunt u Azure Storage-blobs bewerken.

Codevoorbeelden

De voorbeeldcodefragmenten in de volgende secties laten zien hoe u eenvoudige gegevensbewerkingen uitvoert met de Azure Blob Storage-clientbibliotheek voor .NET.

Belangrijk

Zorg ervoor dat u de juiste NuGet-pakketten hebt geïnstalleerd en de benodigde using-instructies hebt toegevoegd om ervoor te zorgen dat de codevoorbeelden werken, zoals beschreven in de sectie instellen .

  • Azure.Identity (als u de methode zonder wachtwoord gebruikt)
  • Azure.Storage.Blobs

Een container maken

Verzin een naam voor de nieuwe container. Met de onderstaande code wordt een GUID-waarde aan de containernaam toegevoegd om te verzekeren dat deze uniek is.

Belangrijk

Containernamen moeten uit kleine letters bestaan. Zie Containers, blobs en metagegevens een naam geven en hiernaar verwijderen voor meer informatie over de naamgeving van containers en blobs.

U kunt de methode CreateBlobContainerAsync aanroepen op de blobServiceClient om een container in uw opslagaccount te maken.

Voeg deze code toe aan het einde van de Program.cs klasse:

// TODO: Replace <storage-account-name> with your actual storage account name
var blobServiceClient = new BlobServiceClient(
        new Uri("https://<storage-account-name>.blob.core.windows.net"),
        new DefaultAzureCredential());

//Create a unique name for the container
string containerName = "quickstartblobs" + Guid.NewGuid().ToString();

// Create the container and return a container client object
BlobContainerClient containerClient = await blobServiceClient.CreateBlobContainerAsync(containerName);

Een blob uploaden naar een container

Voeg de volgende code toe aan het einde van de Program.cs klasse:

// Create a local file in the ./data/ directory for uploading and downloading
string localPath = "data";
Directory.CreateDirectory(localPath);
string fileName = "quickstart" + Guid.NewGuid().ToString() + ".txt";
string localFilePath = Path.Combine(localPath, fileName);

// Write text to the file
await File.WriteAllTextAsync(localFilePath, "Hello, World!");

// Get a reference to a blob
BlobClient blobClient = containerClient.GetBlobClient(fileName);

Console.WriteLine("Uploading to Blob storage as blob:\n\t {0}\n", blobClient.Uri);

// Upload data from the local file
await blobClient.UploadAsync(localFilePath, true);

Het codefragment voltooit de volgende stappen:

  1. Hiermee maakt u een tekstbestand in de lokale map gegevens.
  2. Hiermee wordt een verwijzing naar een BlobClient-object opgehaald door de methode GetBlobClient aan te roepen voor de container vanuit de sectie Een container maken.
  3. Hiermee wordt het lokale tekstbestand geüpload naar de blob door de methode UploadAsync aan te roepen. Met deze methode wordt de blob gemaakt als deze nog niet bestaat, of overschreven als dat wel het geval is.

Blobs in een container weergeven

Hiermee worden de blobs in de container weergegeven door de methode GetBlobsAsync aan te roepen. In dit geval is slechts één blob aan de container toegevoegd, zodat met de weergavebewerking alleen die ene blob wordt geretourneerd.

Voeg de volgende code toe aan het einde van de Program.cs klasse:

Console.WriteLine("Listing blobs...");

// List all blobs in the container
await foreach (BlobItem blobItem in containerClient.GetBlobsAsync())
{
    Console.WriteLine("\t" + blobItem.Name);
}

Een blob downloaden

Download de eerder gemaakte blob door de methode DownloadToAsync aan te roepen. Met de voorbeeldcode wordt het achtervoegsel 'DOWNLOADED' toegevoegd aan de naam van het bestand, zodat u beide bestanden in het lokale bestandssysteem kunt zien.

Voeg de volgende code toe aan het einde van de Program.cs klasse:

// Download the blob to a local file
// Append the string "DOWNLOADED" before the .txt extension 
// so you can compare the files in the data directory
string downloadFilePath = localFilePath.Replace(".txt", "DOWNLOADED.txt");

Console.WriteLine("\nDownloading blob to\n\t{0}\n", downloadFilePath);

// Download the blob's contents and save it to a file
await blobClient.DownloadToAsync(downloadFilePath);

Een container verwijderen

Met de volgende code worden de resources opgeruimd die door de app zijn gemaakt door de hele container te verwijderen met behulp van DeleteAsync. Ook worden de lokale bestanden verwijderd die door de app zijn gemaakt.

De app pauzeert voor gebruikersinvoer door Console.ReadLine aan te roepen voordat deze de blob, container en lokale bestanden verwijdert. Dit is een goede gelegenheid om te controleren of de resources daadwerkelijk correct zijn gemaakt, voordat ze worden verwijderd.

Voeg de volgende code toe aan het einde van de Program.cs klasse:

// Clean up
Console.Write("Press any key to begin clean up");
Console.ReadLine();

Console.WriteLine("Deleting blob container...");
await containerClient.DeleteAsync();

Console.WriteLine("Deleting the local source and downloaded files...");
File.Delete(localFilePath);
File.Delete(downloadFilePath);

Console.WriteLine("Done");

De voltooide code

Nadat u deze stappen hebt voltooid, moet de code in het Program.cs bestand er nu als volgt uitzien:

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

// TODO: Replace <storage-account-name> with your actual storage account name
var blobServiceClient = new BlobServiceClient(
        new Uri("https://<storage-account-name>.blob.core.windows.net"),
        new DefaultAzureCredential());

//Create a unique name for the container
string containerName = "quickstartblobs" + Guid.NewGuid().ToString();

// Create the container and return a container client object
BlobContainerClient containerClient = await blobServiceClient.CreateBlobContainerAsync(containerName);

// Create a local file in the ./data/ directory for uploading and downloading
string localPath = "data";
Directory.CreateDirectory(localPath);
string fileName = "quickstart" + Guid.NewGuid().ToString() + ".txt";
string localFilePath = Path.Combine(localPath, fileName);

// Write text to the file
await File.WriteAllTextAsync(localFilePath, "Hello, World!");

// Get a reference to a blob
BlobClient blobClient = containerClient.GetBlobClient(fileName);

Console.WriteLine("Uploading to Blob storage as blob:\n\t {0}\n", blobClient.Uri);

// Upload data from the local file
await blobClient.UploadAsync(localFilePath, true);

Console.WriteLine("Listing blobs...");

// List all blobs in the container
await foreach (BlobItem blobItem in containerClient.GetBlobsAsync())
{
    Console.WriteLine("\t" + blobItem.Name);
}

// Download the blob to a local file
// Append the string "DOWNLOADED" before the .txt extension 
// so you can compare the files in the data directory
string downloadFilePath = localFilePath.Replace(".txt", "DOWNLOADED.txt");

Console.WriteLine("\nDownloading blob to\n\t{0}\n", downloadFilePath);

// Download the blob's contents and save it to a file
await blobClient.DownloadToAsync(downloadFilePath);

// Clean up
Console.Write("Press any key to begin clean up");
Console.ReadLine();

Console.WriteLine("Deleting blob container...");
await containerClient.DeleteAsync();

Console.WriteLine("Deleting the local source and downloaded files...");
File.Delete(localFilePath);
File.Delete(downloadFilePath);

Console.WriteLine("Done");

De code uitvoeren

Met deze app wordt een testbestand gemaakt in uw lokale map gegevens en geüpload naar de Blob-opslag. Vervolgens wordt een lijst gemaakt van de blobs in de container en wordt het bestand gedownload met een nieuwe naam, zodat u het oude en nieuwe bestand kunt vergelijken.

Als u Visual Studio gebruikt, drukt u op F5 om de code te bouwen en uit te voeren en te communiceren met de console-app. Als u de .NET CLI gebruikt, gaat u naar de toepassingsmap en bouwt en voert u de toepassing uit.

dotnet build
dotnet run

De uitvoer van de app lijkt op die in het volgende voorbeeld:

Azure Blob Storage - .NET quickstart sample

Uploading to Blob storage as blob:
         https://mystorageacct.blob.core.windows.net/quickstartblobs60c70d78-8d93-43ae-954d-8322058cfd64/quickstart2fe6c5b4-7918-46cb-96f4-8c4c5cb2fd31.txt

Listing blobs...
        quickstart2fe6c5b4-7918-46cb-96f4-8c4c5cb2fd31.txt

Downloading blob to
        ./data/quickstart2fe6c5b4-7918-46cb-96f4-8c4c5cb2fd31DOWNLOADED.txt

Press any key to begin clean up
Deleting blob container...
Deleting the local source and downloaded files...
Done

Voordat u begint met opschonen, controleert u of de twee bestanden zich in de map gegevens bevinden. Als u ze opent, ziet u dat ze identiek zijn.

Nadat u de bestanden hebt gecontroleerd, drukt u op Enter om de testbestanden te verwijderen en het voorbeeld te voltooien.

Volgende stappen

In deze snelstart hebt u geleerd hoe u blobs kunt uploaden, downloaden en er een lijst van maken met behulp van .NET.

Als u voorbeeld-apps voor Blob-opslag wilt zien, ga dan naar: