Snabbstart: Azure Blob Storage klientbibliotek för .NET

Kom igång med Azure Blob Storage-klientbiblioteket för .NET. Azure Blob Storage är Microsoft objektlagringslösning för molnet. Följ de här stegen för att installera paketet och prova exempelkod för grundläggande uppgifter. Blob Storage är optimerad för lagring av enorma mängder ostrukturerade data.

API-referensdokumentation | Bibliotekskällans kod | Paket (NuGet) | Prover

Krav

Inrätta

Det här avsnittet beskriver steg för steg hur du förbereder ett projekt för att arbeta med Azure Blob Storage-klientbiblioteket för .NET.

Skapa projektet

För de kommande stegen måste du skapa en .NET-konsolapp med hjälp av .NET CLI eller Visual Studio 2022.

  1. Överst i Visual Studio går du till Arkiv>Nytt>projekt...

  2. I dialogrutan anger du konsolappen i sökrutan för projektmallen och väljer det första resultatet. Välj Nästa längst ned i dialogrutan.

    En skärmbild som visar hur du skapar ett nytt projekt med Visual Studio.

  3. Som Projektnamn anger du BlobQuickstart. Lämna standardvärdena för resten av fälten och välj Nästa.

  4. För Framework kontrollerar du att .NET 6.0 är valt. Välj sedan Skapa. Det nya projektet öppnas i Visual Studio-miljön.

Installera paketet

Om du vill interagera med Azure Blob Storage installerar du Azure Blob Storage-klientbiblioteket för .NET.

  1. I Solution Explorer högerklickar du på noden Beroenden i projektet. Välj Hantera NuGet-paket.

  2. I det resulterande fönstret söker du efter Azure.Storage.Blobs. Välj lämpligt resultat och välj Installera.

    En skärmbild som visar hur du lägger till ett nytt paket med Visual Studio.

Konfigurera appkoden

Ersätt startkoden i filen så att den matchar följande exempel, som innehåller nödvändiga using instruktioner för den här övningenProgram.cs.

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

Autentisera till Azure och auktorisera åtkomst till blobdata

Programbegäranden till Azure Blob Storage måste auktoriseras. Att använda klassen DefaultAzureCredential som tillhandahålls av Azure Identity-klientbiblioteket är den rekommenderade metoden för att implementera lösenordslösa anslutningar till Azure-tjänster i din kod, inklusive Blob Storage.

Du kan också auktorisera begäranden att Azure Blob Storage med hjälp av kontoåtkomstnyckeln. Den här metoden bör dock användas med försiktighet. Utvecklare måste vara noggranna för att aldrig exponera åtkomstnyckeln på en oskyddad plats. Alla som har åtkomstnyckeln kan auktorisera begäranden mot lagringskontot och har effektivt åtkomst till alla data. DefaultAzureCredential ger bättre hanterings- och säkerhetsfördelar jämfört med kontonyckeln för att tillåta lösenordsfri autentisering. Båda alternativen visas i följande exempel.

DefaultAzureCredential är en klass som tillhandahålls av Azure Identity-klientbiblioteket för .NET, som du kan läsa mer om i översikten över DefaultAzureCredential. DefaultAzureCredential stöder flera autentiseringsmetoder och avgör vilken metod som ska användas vid körning. Med den här metoden kan din app använda olika autentiseringsmetoder i olika miljöer (lokalt jämfört med produktion) utan att implementera miljöspecifik kod.

Den ordning och de platser där DefaultAzureCredential du söker efter autentiseringsuppgifter finns i översikten över Azure Identity Library.

Din app kan till exempel autentisera med dina Inloggningsuppgifter för Visual Studio med när du utvecklar lokalt. Din app kan sedan använda en hanterad identitet när den har distribuerats till Azure. Inga kodändringar krävs för den här övergången.

Tilldela roller till ditt Azure AD användarkonto

När du utvecklar lokalt kontrollerar du att det användarkonto som har åtkomst till blobdata har rätt behörigheter. Du behöver Storage Blob Data-deltagare för att läsa och skriva blobdata. Om du vill tilldela dig själv den här rollen måste du tilldelas rollen Administratör för användaråtkomst eller en annan roll som innehåller Microsoft. Auktorisering/roleAssignments/skrivåtgärd. Du kan tilldela Azure RBAC-roller till en användare med hjälp av Azure Portal, Azure CLI eller Azure PowerShell. Du kan läsa mer om tillgängliga omfång för rolltilldelningar på översiktssidan för omfång .

I det här scenariot tilldelar du behörigheter till ditt användarkonto, begränsat till lagringskontot, för att följa principen om lägsta behörighet. Den här metoden ger användarna endast de minsta behörigheter som krävs och skapar säkrare produktionsmiljöer.

I följande exempel tilldelas rollen Storage Blob Data-deltagare till ditt användarkonto, som ger både läs- och skrivåtkomst till blobdata i ditt lagringskonto.

Viktigt

I de flesta fall tar det en minut eller två innan rolltilldelningen sprids i Azure, men i sällsynta fall kan det ta upp till åtta minuter. Om du får autentiseringsfel när du först kör koden väntar du en stund och försöker igen.

  1. Leta upp ditt lagringskonto i Azure Portal med hjälp av huvudsökfältet eller det vänstra navigeringsfältet.

  2. På översiktssidan för lagringskontot väljer du Åtkomstkontroll (IAM) på den vänstra menyn.

  3. På sidan Åtkomstkontroll (IAM) väljer du fliken Rolltilldelningar .

  4. Välj + Lägg till på den översta menyn och sedan Lägg till rolltilldelning från den resulterande nedrullningsbara menyn.

    En skärmbild som visar hur du tilldelar en roll.

  5. Använd sökrutan för att filtrera resultatet till önskad roll. I det här exemplet söker du efter Storage Blob Data Contributor och väljer matchande resultat och sedan Nästa.

  6. Under Tilldela åtkomst till väljer du Användare, grupp eller tjänstens huvudnamn och sedan + Välj medlemmar.

  7. I dialogrutan söker du efter ditt Azure AD användarnamn (vanligtvis din user@domain e-postadress) och väljer sedan Välj längst ned i dialogrutan.

  8. Välj Granska + tilldela för att gå till den sista sidan och sedan Granska + tilldela igen för att slutföra processen.

Logga in och anslut din appkod till Azure med defaultAzureCredential

Du kan auktorisera åtkomst till data i ditt lagringskonto med hjälp av följande steg:

  1. Kontrollera att du är autentiserad med samma Azure AD konto som du tilldelade rollen till. Du kan autentisera via Azure CLI, Visual Studio eller Azure PowerShell.

    Logga in på Azure via Azure CLI med följande kommando:

    az login
    
  2. Om du vill använda DefaultAzureCredentiallägger du till Azure.Identity-paketet i ditt program.

    1. I Solution Explorer högerklickar du på noden Beroenden i projektet. Välj Hantera NuGet-paket.

    2. I det resulterande fönstret söker du efter Azure.Identity. Välj lämpligt resultat och välj Installera.

      En skärmbild som visar hur du lägger till identitetspaketet.

  3. Uppdatera program.cs-koden så att den matchar följande exempel. När koden körs på din lokala arbetsstation under utvecklingen använder den utvecklarautentiseringsuppgifterna för det prioriterade verktyget som du är inloggad i för att autentisera till Azure, till exempel Azure CLI eller 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. Se till att uppdatera lagringskontots namn i URI:n för din BlobServiceClient. Namnet på lagringskontot finns på översiktssidan för Azure Portal.

    En skärmbild som visar hur du hittar lagringskontots namn.

    Anteckning

    När den distribueras till Azure kan samma kod användas för att auktorisera begäranden till Azure Storage från ett program som körs i Azure. Du måste dock aktivera hanterad identitet i din app i Azure. Konfigurera sedan lagringskontot så att den hanterade identiteten kan ansluta. Detaljerade anvisningar om hur du konfigurerar den här anslutningen mellan Azure-tjänster finns i självstudien Auth from Azure-hosted apps (Autentisering från Azure-värdbaserade appar ).

Objektmodell

Azure Blob Storage är optimerat för att lagra enorma mängder ostrukturerade data. Ostrukturerade data följer inte en viss datamodell eller definition, till exempel text eller binära data. I blobblagringen finns tre typer av resurser:

  • Lagringskontot
  • En container på lagringskontot
  • En blob i containern

Följande diagram visar relationen mellan de här resurserna.

Diagram över Blob Storage-arkitekturen.

Använd följande .NET-klasser för att interagera med dessa resurser:

  • BlobServiceClient: Med BlobServiceClient klassen kan du manipulera Azure Storage-resurser och blobcontainrar.
  • BlobContainerClient: Med BlobContainerClient klassen kan du manipulera Azure Storage-containrar och deras blobar.
  • BlobClient: Med BlobClient klassen kan du manipulera Azure Storage-blobar.

Kodexempel

Exempelkodfragmenten i följande avsnitt visar hur du utför grundläggande dataåtgärder med Azure Blob Storage-klientbiblioteket för .NET.

Viktigt

Kontrollera att du har installerat rätt NuGet-paket och lagt till nödvändiga using-instruktioner för att kodexemplen ska fungera, enligt beskrivningen i konfigurationsavsnittet .

  • Azure.Identity (om du använder den lösenordslösa metoden)
  • Azure.Storage.Blobs

Skapa en container

Bestäm ett namn för den nya containern. Koden nedan lägger till ett GUID-värde i containernamnet för att säkerställa att det är unikt.

Viktigt

Containernamn måste använda gemener. Mer information om namngivning av containrar och blobar finns i Namngivning och referens av containrar, blobar och metadata.

Du kan anropa metoden CreateBlobContainerAsyncblobServiceClient för att skapa en container i ditt lagringskonto.

Lägg till den här koden i slutet av Program.cs klassen:

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

Ladda upp en blob till en container

Lägg till följande kod i slutet av Program.cs klassen:

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

Kodfragmentet utför följande steg:

  1. Skapar en textfil i den lokala datakatalogen .
  2. Hämtar en referens till ett BlobClient-objekt genom att anropa metoden GetBlobClient i containern från avsnittet Skapa en container .
  3. Laddar upp den lokala textfilen till bloben genom att anropa metoden UploadAsync . Den här metoden skapar bloben om den inte redan finns, och skriver över den om den finns.

Lista blobar i en container

Lista blobarna i containern genom att anropa metoden GetBlobsAsync . I det här fallet har endast en blob lagts till i containern, så listningsåtgärden returnerar bara den bloben.

Lägg till följande kod i slutet av Program.cs klassen:

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

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

Ladda ned en blob

Ladda ned den tidigare skapade bloben genom att anropa metoden DownloadToAsync . Exempelkoden lägger till ett suffix med "DOWNLOADED" i filnamnet så att du kan se båda filerna i det lokala filsystemet.

Lägg till följande kod i slutet av Program.cs klassen:

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

Ta bort en container

Följande kod rensar resurserna som appen skapade genom att ta bort hela containern med hjälp av DeleteAsync. Den tar också bort de lokala filer som skapats av appen.

Appen pausar för användarindata genom att anropa Console.ReadLine innan den tar bort bloben, containern och de lokala filerna. Det här är en bra chans att kontrollera att resurserna faktiskt har skapats korrekt innan de tas bort.

Lägg till följande kod i slutet av Program.cs klassen:

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

Den färdiga koden

När du har slutfört de här stegen bör koden i Program.cs filen nu likna följande:

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

Kör koden

Den här appen skapar en testfil i din lokala datamapp och laddar upp den till Blob Storage. I exemplet visas sedan blobarna i containern och filen laddas ned med ett nytt namn så att du kan jämföra de gamla och nya filerna.

Om du använder Visual Studio trycker du på F5 för att skapa och köra koden och interagera med konsolappen. Om du använder .NET CLI navigerar du till programkatalogen och skapar och kör programmet.

dotnet build
dotnet run

Utdata från appen liknar följande exempel:

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

Kontrollera datamappen för de två filerna innan du påbörjar rensningsprocessen. Du kan öppna dem och se att de är identiska.

När du har verifierat filerna trycker du på Retur för att ta bort testfilerna och slutför demonstrationen.

Nästa steg

I den här snabbstarten har du lärt dig att ladda upp, ladda ned och lista blobar med hjälp av .NET.

Om du vill se Exempelappar för Blob Storage fortsätter du till: