Snabbstart: Azure Blob Storage-klientbibliotek för .NET

  • Artikel

Kommentar

Alternativet Skapa från grunden vägleder dig steg för steg genom processen att skapa ett nytt projekt, installera paket, skriva koden och köra en grundläggande konsolapp. Den här metoden rekommenderas om du vill förstå all information som ingår i skapandet av en app som ansluter till Azure Blob Storage. Om du föredrar att automatisera distributionsuppgifter och börja med ett slutfört projekt väljer du Börja med en mall.

Kommentar

Alternativet Börja med en mall använder Azure Developer CLI för att automatisera distributionsuppgifter och startar dig med ett slutfört projekt. Den här metoden rekommenderas om du vill utforska koden så snabbt som möjligt utan att gå igenom konfigurationsuppgifterna. Om du föredrar stegvisa instruktioner för att skapa appen väljer du Skapa från grunden.

Kom igång med Azure Blob Storage-klientbiblioteket för .NET. Azure Blob Storage är Microsofts objektlagringslösning för molnet och optimerad för lagring av enorma mängder ostrukturerade data.

I den här artikeln följer du stegen för att installera paketet och prova exempelkod för grundläggande uppgifter.

I den här artikeln använder du Azure Developer CLI för att distribuera Azure-resurser och köra en slutförd konsolapp med bara några få kommandon.

API-referensdokumentation NuGet-exempel (Library source code | Package) | |

Den här videon visar hur du börjar använda Azure Blob Storage-klientbiblioteket för .NET.

Stegen i videon beskrivs också i följande avsnitt.

Förutsättningar

Konfigurera

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

Skapa projektet

Skapa en .NET-konsolapp med hjälp av .NET CLI eller Visual Studio 2022.

  1. Överst i Visual Studio går du till Fil>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.

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

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

  4. För Ramverket kontrollerar du att den senaste installerade versionen av .NET är markerad. 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. Högerklicka på noden Beroenden i projektet i Solution Explorer. 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.

    A screenshot showing how to add a new package using Visual Studio.

Konfigurera appkoden

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

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

Med Azure Developer CLI installerat kan du skapa ett lagringskonto och köra exempelkoden med bara några få kommandon. Du kan köra projektet i din lokala utvecklingsmiljö eller i en DevContainer.

Initiera CLI-mallen för Azure Developer och distribuera resurser

Från en tom katalog följer du de här stegen för att initiera mallen azd , etablera Azure-resurser och komma igång med koden:

  • Klona snabbstartslagringsplatsens tillgångar från GitHub och initiera mallen lokalt:

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

    Du uppmanas att ange följande information:

    • Miljönamn: Det här värdet används som prefix för alla Azure-resurser som skapats av Azure Developer CLI. Namnet måste vara unikt för alla Azure-prenumerationer och måste vara mellan 3 och 24 tecken långt. Namnet får endast innehålla siffror och gemener.

  • Logga in på Azure:

    azd auth login

  • Etablera och distribuera resurserna till Azure:

    azd up

    Du uppmanas att ange följande information:

    • Prenumeration: Den Azure-prenumeration som dina resurser distribueras till.
    • Plats: Den Azure-region där dina resurser distribueras.

    Distributionen kan ta några minuter att slutföra. Utdata från azd up kommandot innehåller namnet på det nyligen skapade lagringskontot, som du behöver senare för att köra koden.

Kör exempelkoden

Nu distribueras resurserna till Azure och projektet är redo att köras. Följ dessa steg för att uppdatera namnet på lagringskontot i koden och kör exempelkonsolappen:

  • Uppdatera lagringskontots namn: Navigera till src katalogen och redigera Program.cs. Leta upp <storage-account-name> platshållaren och ersätt den med det faktiska namnet på lagringskontot som skapades av azd up kommandot. Spara ändringarna.
  • Kör projektet: 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 går du till programkatalogen, skapar projektet med och dotnet buildkör programmet med hjälp av dotnet run.
  • Observera utdata: Den här appen skapar en testfil i din lokala datamapp och laddar upp den till en container i lagringskontot. 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.

Mer information om hur exempelkoden fungerar finns i Kodexempel.

När du är klar med att testa koden kan du läsa avsnittet Rensa resurser för att ta bort de resurser som skapades av azd up kommandot.

Objektmodell

Azure Blob Storage är optimerat för lagring av 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 of Blob storage architecture.

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

  • BlobServiceClient: Med BlobServiceClient klassen kan du ändra 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 följande uppgifter med Azure Blob Storage-klientbiblioteket för .NET:

Viktigt!

Kontrollera att du har installerat rätt NuGet-paket och lagt till nödvändiga med hjälp av instruktioner för att kodexemplen ska fungera enligt beskrivningen i avsnittet konfigurera.

Kommentar

Azure Developer CLI-mallen innehåller ett projekt med exempelkod redan på plats. Följande exempel innehåller information om varje del av exempelkoden. Mallen implementerar den rekommenderade autentiseringsmetoden utan lösenord, enligt beskrivningen i avsnittet Autentisera till Azure . Metoden anslutningssträng visas som ett alternativ, men används inte i mallen och rekommenderas inte för produktionskod.

Autentisera till Azure och auktorisera åtkomst till blobdata

Programbegäranden till Azure Blob Storage måste vara auktoriserade. 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 till 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 osäker 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ösenordslös 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 Översikt ö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 autentiseringsuppgifterna söks finns i översikten över Azure Identity Library.

Din app kan till exempel autentisera med dina Inloggningsuppgifter för Visual Studio med när den utvecklas 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 Microsoft Entra-användarkonto

När du utvecklar lokalt kontrollerar du att användarkontot 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 åtgärden Microsoft.Authorization/roleAssignments/write . Du kan tilldela Azure RBAC-roller till en användare med hjälp av Azure-portalen, Azure CLI eller Azure PowerShell. Du kan lära dig 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 Contributor till ditt användarkonto, vilket ger både läs- och skrivåtkomst till blobdata i ditt lagringskonto.

Viktigt!

I de flesta fall tar det en minut eller två för rolltilldelningen att spridas 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-portalen 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.

    A screenshot showing how to assign a role.

  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 väljer 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 Microsoft Entra-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. För lokal utveckling kontrollerar du att du är autentiserad med samma Microsoft Entra-konto som du tilldelade rollen till. Du kan autentisera via populära utvecklingsverktyg, till exempel Azure CLI eller Azure PowerShell. De utvecklingsverktyg som du kan autentisera med varierar mellan olika språk.

    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. Högerklicka på noden Beroenden i projektet i Solution Explorer. Välj Hantera NuGet-paket.

    2. Sök efter Azure.Identity i det resulterande fönstret. Välj lämpligt resultat och välj Installera.

      A screenshot showing how to add the identity package.

  3. Uppdatera din Program.cs kod 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 på 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 i Azure-portalen.

    A screenshot showing how to find the storage account name.

    Kommentar

    När du distribuerar 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 ditt lagringskonto så att den hanterade identiteten kan ansluta. Detaljerade anvisningar om hur du konfigurerar den här anslutningen mellan Azure-tjänster finns i självstudiekursen Auth from Azure-hosted apps (Auth from Azure-hosted apps ).

Skapa en container

Skapa en ny container i ditt lagringskonto genom att anropa metoden CreateBlobContainerAsync på blobServiceClient objektet. I det här exemplet lägger koden till ett GUID-värde i containernamnet för att säkerställa att det är unikt.

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

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

Mer information om hur du skapar en container och om du vill utforska fler kodexempel finns i Skapa en blobcontainer med .NET.

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.

Ladda upp en blob till en container

Ladda upp en blob till en container med UploadAsync. Exempelkoden skapar en textfil i den lokala datakatalogen som ska laddas upp till containern.

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

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

Mer information om hur du laddar upp blobar och om du vill utforska fler kodexempel finns i Ladda upp en blob med .NET.

Lista blobar i en container

Visa en lista över blobarna i containern genom att anropa metoden GetBlobsAsync .

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

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

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

Mer information om att visa blobar och utforska fler kodexempel finns i Lista blobar med .NET.

Ladda ned en blob

Ladda ned bloben som vi skapade tidigare genom att anropa metoden DownloadToAsync . Exempelkoden lägger till strängen "DOWNLOADED" i filnamnet så att du kan se båda filerna i det lokala filsystemet.

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

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

Mer information om hur du laddar ned blobar och om du vill utforska fler kodexempel finns i Ladda ned en blob med .NET.

Ta bort en container

Följande kod rensar de resurser som appen skapade genom att ta bort containern med DeleteAsync. Kodexemplet 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 har skapats korrekt innan de tas bort.

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

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

Mer information om hur du tar bort en container och om du vill utforska fler kodexempel finns i Ta bort och återställa en blobcontainer med .NET.

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 går du till programkatalogen och skapar och kör programmet.

dotnet build

dotnet run

Utdata från appen liknar följande exempel (GUID-värden utelämnas för läsbarhet):

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

Innan du påbörjar rensningsprocessen kontrollerar du datamappen för de två filerna. Du kan öppna dem och observera att de är identiska.

Rensa resurser

När du har verifierat filerna och testat klart trycker du på Retur för att ta bort testfilerna tillsammans med containern som du skapade i lagringskontot. Du kan också använda Azure CLI för att ta bort resurser.

När du är klar med snabbstarten kan du rensa de resurser som du skapade genom att köra följande kommando:

azd down

Du uppmanas att bekräfta borttagningen av resurserna. Ange y för att bekräfta.

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 Blob Storage-exempelappar fortsätter du till:

Azure Blob Storage-bibliotek för .NET-exempel