Quickstart: Azure Blob Storage-clientbibliotheek voor .NET

  • Artikel

Notitie

Met de optie Volledig nieuw bouwen wordt u stapsgewijs begeleid bij het maken van een nieuw project, het installeren van pakketten, het schrijven van de code en het uitvoeren van een eenvoudige console-app. Deze aanpak wordt aanbevolen als u alle details wilt begrijpen die betrekking hebben op het maken van een app die verbinding maakt met Azure Blob Storage. Als u liever implementatietaken automatiseert en begint met een voltooid project, kiest u Beginnen met een sjabloon.

Notitie

De optie Beginnen met een sjabloon maakt gebruik van de Azure Developer CLI om implementatietaken te automatiseren en u begint met een voltooid project. Deze aanpak wordt aanbevolen als u de code zo snel mogelijk wilt verkennen zonder de installatietaken te doorlopen. Als u de voorkeur geeft aan stapsgewijze instructies voor het bouwen van de app, kiest u Volledig nieuw bouwen.

Aan de slag met de Azure Blob Storage-clientbibliotheek voor .NET. Azure Blob Storage is de oplossing voor objectopslag van Microsoft voor de cloud en is geoptimaliseerd voor het opslaan van enorme hoeveelheden ongestructureerde gegevens.

In dit artikel voert u de stappen uit om het pakket te installeren en voorbeeldcode voor basistaken uit te proberen.

In dit artikel gebruikt u de Azure Developer CLI om Azure-resources te implementeren en een voltooide console-app uit te voeren met slechts een paar opdrachten.

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

In deze video ziet u hoe u de Azure Blob Storage-clientbibliotheek voor .NET kunt gaan gebruiken.

De stappen in de video worden ook beschreven in de volgende secties.

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

Maak een .NET-console-app met behulp van de .NET CLI of Visual Studio 2022.

  1. Navigeer boven aan Visual Studio naar Bestand>nieuw>project...

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

    A screenshot showing how to create a new project using Visual Studio.

  3. Voer voor de projectnaam BlobQuickstart in. Laat de standaardwaarden voor de rest van de velden staan en selecteer Volgende.

  4. Zorg ervoor dat voor framework de meest recente geïnstalleerde versie van .NET 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.

    A screenshot showing how to add a new package using 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!");

Als Azure Developer CLI is geïnstalleerd, kunt u een opslagaccount maken en de voorbeeldcode uitvoeren met slechts een paar opdrachten. U kunt het project uitvoeren in uw lokale ontwikkelomgeving of in een DevContainer.

De Azure Developer CLI-sjabloon initialiseren en resources implementeren

Voer vanuit een lege map de volgende stappen uit om de azd sjabloon te initialiseren, Azure-resources in te richten en aan de slag te gaan met de code:

  • Kloon de assets van de quickstart-opslagplaats vanuit GitHub en initialiseer de sjabloon lokaal:

    azd init --template blob-storage-quickstart-dotnet

    U wordt gevraagd om de volgende informatie:

    • Omgevingsnaam: deze waarde wordt gebruikt als voorvoegsel voor alle Azure-resources die zijn gemaakt door Azure Developer CLI. De naam moet uniek zijn voor alle Azure-abonnementen en moet tussen de 3 en 24 tekens lang zijn. De naam mag alleen cijfers en kleine letters bevatten.

  • Meld u aan bij Azure:

    azd auth login

  • De resources inrichten en implementeren in Azure:

    azd up

    U wordt gevraagd om de volgende informatie:

    • Abonnement: het Azure-abonnement waarop uw resources zijn geïmplementeerd.
    • Locatie: De Azure-regio waar uw resources worden geïmplementeerd.

    De implementatie kan enkele minuten duren. De uitvoer van de azd up opdracht bevat de naam van het zojuist gemaakte opslagaccount, dat u later nodig hebt om de code uit te voeren.

De voorbeeldcode uitvoeren

Op dit moment worden de resources geïmplementeerd in Azure en kan het project worden uitgevoerd. Volg deze stappen om de naam van het opslagaccount in de code bij te werken en de voorbeeldconsole-app uit te voeren:

  • Werk de naam van het opslagaccount bij: Navigeer naar de src map en bewerk Program.csdeze. Zoek de <storage-account-name> tijdelijke aanduiding en vervang deze door de werkelijke naam van het opslagaccount dat door de azd up opdracht is gemaakt. De wijzigingen opslaan.
  • Voer het project uit: 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, bouwt u het project met behulp van dotnet builden voert u de toepassing uit met behulp van de dotnet run.
  • Bekijk de uitvoer: met deze app wordt een testbestand gemaakt in uw lokale gegevensmap en geüpload naar een container in het opslagaccount. 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.

Zie Codevoorbeelden voor meer informatie over hoe de voorbeeldcode werkt.

Wanneer u klaar bent met het testen van de code, raadpleegt u de sectie Resources opschonen om de resources te verwijderen die met de azd up opdracht zijn gemaakt.

Objectmodel

Azure Blob Storage is geoptimaliseerd voor het opslaan van grote hoeveelheden ongestructureerde gegevens. Niet-gestructureerde gegevens voldoen niet aan een bepaald gegevensmodel of -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 of Blob storage architecture.

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

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

Codevoorbeelden

De voorbeeldcodefragmenten in de volgende secties laten zien hoe u de volgende taken 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 de codevoorbeelden te laten werken, zoals beschreven in de sectie Voor het instellen .

Notitie

De Azure Developer CLI-sjabloon bevat een project met voorbeeldcode die al is geïmplementeerd. De volgende voorbeelden bevatten details voor elk deel van de voorbeeldcode. De sjabloon implementeert de aanbevolen verificatiemethode zonder wachtwoord, zoals beschreven in de sectie Verifiëren bij Azure . De methode verbindingsreeks wordt weergegeven als alternatief, maar wordt niet gebruikt in de sjabloon en wordt niet aanbevolen voor productiecode.

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 wachtwoorden 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 aanpak moet echter met 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 mogelijk te maken. Beide opties worden in het volgende voorbeeld gedemonstreerd.

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

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

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

Rollen toewijzen aan uw Microsoft Entra-gebruikersaccount

Zorg er bij het lokaal ontwikkelen voor dat het gebruikersaccount dat toegang heeft tot blobgegevens over de juiste machtigingen beschikt. U hebt Inzender voor Opslagblobgegevens nodig om blobgegevens te lezen en schrijven. Als u uzelf deze rol wilt toewijzen, moet u de rol Gebruikerstoegang Beheer istrator of een andere rol met de actie Microsoft.Authorization/roleAssignments/write toegewezen krijgen. U kunt Azure RBAC-rollen toewijzen aan een gebruiker met behulp van Azure Portal, Azure CLI of Azure PowerShell. Meer informatie over de beschikbare bereiken voor roltoewijzingen vindt u op de overzichtspagina van het bereik.

In dit scenario wijst u machtigingen toe aan uw gebruikersaccount, dat is afgestemd op 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 Inzender voor opslagblobgegevens toegewezen aan uw gebruikersaccount, dat zowel lees- als schrijftoegang biedt tot blobgegevens in uw opslagaccount.

Belangrijk

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

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

  2. Selecteer op de overzichtspagina van het opslagaccount 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 voeg vervolgens roltoewijzing toe in de resulterende vervolgkeuzelijst.

    A screenshot showing how to assign a role.

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

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

  7. Zoek in het dialoogvenster naar uw Microsoft Entra-gebruikersnaam (meestal uw user@domain e-mailadres) en kies Vervolgens onderaan het dialoogvenster Selecteren .

  8. Selecteer Beoordelen + toewijzen om naar de laatste pagina te gaan en vervolgens opnieuw beoordelen en toewijzen om het proces te voltooien.

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

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

  1. Zorg ervoor dat u voor lokale ontwikkeling bent geverifieerd met hetzelfde Microsoft Entra-account waaraan u de rol hebt toegewezen. U kunt zich verifiëren via populaire ontwikkelhulpprogramma's, zoals de Azure CLI of Azure PowerShell. De ontwikkelhulpprogramma's waarmee u zich kunt verifiëren, variëren per taal.

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

    az login

  2. Als u dit 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.

      A screenshot showing how to add the identity package.

  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 referenties van de ontwikkelaar gebruikt van het hulpprogramma met prioriteit waarmee u bent aangemeld voor verificatie 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 Azure Portal.

    A screenshot showing how to find the storage account name.

    Notitie

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

Een container maken

Maak een nieuwe container in uw opslagaccount door de methode CreateBlobContainerAsync op het object aan te blobServiceClient roepen. In dit voorbeeld voegt de code een GUID-waarde toe aan de containernaam om ervoor te zorgen dat deze uniek is.

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

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

Zie Een blobcontainer maken met .NET voor meer informatie over het maken van een container en voor meer codevoorbeelden.

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.

Een blob uploaden naar een container

Upload een blob naar een container met behulp van UploadAsync. Met de voorbeeldcode wordt een tekstbestand gemaakt in de lokale gegevensmap om naar de container te uploaden.

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

// 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, overwrite the blob if it already exists
await blobClient.UploadAsync(localFilePath, true);

Zie Een blob uploaden met .NET voor meer informatie over het uploaden van blobs en voor meer codevoorbeelden.

Blobs in een container weergeven

Hiermee worden de blobs in de container weergegeven door de methode GetBlobsAsync aan te roepen.

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

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

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

Zie Lijst-blobs met .NET voor meer informatie over het weergeven van blobs en voor meer codevoorbeelden.

Blob downloaden

Download de blob die we eerder hebben gemaakt door de methode DownloadToAsync aan te roepen. De voorbeeldcode voegt de tekenreeks 'GEDOWNLOAD' toe aan de bestandsnaam, zodat u beide bestanden in het lokale bestandssysteem kunt zien.

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

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

Zie Een blob downloaden met .NET voor meer informatie over het downloaden van blobs en voor meer codevoorbeelden.

Een container verwijderen

Met de volgende code worden de resources opgeschoond die de app heeft gemaakt door de container te verwijderen met Behulp van DeleteAsync. In het codevoorbeeld worden ook 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 kans om te controleren of de resources correct zijn gemaakt voordat ze worden verwijderd.

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

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

Zie Een blobcontainer verwijderen en herstellen met .NET voor meer informatie over het verwijderen van een container en voor meer codevoorbeelden.

De voltooide code

Nadat u deze stappen hebt voltooid, moet de code in uw 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 is vergelijkbaar met het volgende voorbeeld (GUID-waarden weggelaten voor leesbaarheid):

Azure Blob Storage - .NET quickstart sample

Uploading to Blob storage as blob:
         https://mystorageacct.blob.core.windows.net/quickstartblobsGUID/quickstartGUID.txt

Listing blobs...
        quickstartGUID.txt

Downloading blob to
        ./data/quickstartGUIDDOWNLOADED.txt

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

Voordat u begint met het opschonen, controleert u de gegevensmap voor de twee bestanden. U kunt ze openen en zien dat ze identiek zijn.

Resources opschonen

Nadat u de bestanden hebt gecontroleerd en het testen hebt voltooid, drukt u op Enter om de testbestanden te verwijderen, samen met de container die u in het opslagaccount hebt gemaakt. U kunt ook Azure CLI gebruiken om resources te verwijderen.

Wanneer u klaar bent met de quickstart, kunt u de resources die u hebt gemaakt opschonen door de volgende opdracht uit te voeren:

azd down

U wordt gevraagd om het verwijderen van de resources te bevestigen. Voer y dit in om te bevestigen.

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:

Azure Blob Storage-bibliotheek voor .NET-voorbeelden