De Azure SDK voor .NET gebruiken in ASP.NET Core-apps
Met de Azure SDK voor .NET kunnen ASP.NET Core-apps worden geïntegreerd met veel verschillende Azure-services. In dit artikel leert u de aanbevolen procedures en de stappen voor de overstap naar de Azure SDK voor .NET in uw ASP.NET Core-apps. U leert het volgende:
- Registreer diensten voor afhankelijkheidsinjectie.
- Verifiëren bij Azure zonder wachtwoorden of geheimen te gebruiken.
- Gecentraliseerde, gestandaardiseerde configuratie implementeren.
- Veelvoorkomende aandachtspunten voor web-apps configureren, zoals logregistratie en herhalingen.
Algemene Azure SDK-clientbibliotheken verkennen
ASP.NET Core-apps die verbinding maken met Azure-services, zijn doorgaans afhankelijk van de volgende Azure SDK-clientbibliotheken:
- Microsoft.Extensions.Azure biedt helpermethoden voor het registreren van clients bij de dependency injection-service en het afhandelen van verschillende taken voor u, zoals het instellen van logging, het afhandelen van de levensduur van DI-services en het beheer van authenticatiegegevens.
- Azure.Identity biedt ondersteuning voor Microsoft Entra ID-verificatie in de Azure SDK. Het biedt een set TokenCredential-implementaties voor het bouwen van Azure SDK-clients die ondersteuning bieden voor Microsoft Entra-verificatie.
-
Azure.<service-namespace>
bibliotheken, zoals Azure.Storage.Blobs en Azure.Messaging.ServiceBus, bieden serviceclients en andere typen waarmee u verbinding kunt maken met specifieke Azure-services en deze kunt gebruiken. Zie Bibliotheken met behulp van Azure.Core voor een volledige inventarisatie van deze bibliotheken.
In de volgende secties leert u hoe u een ASP.NET Core-toepassing implementeert die gebruikmaakt van deze bibliotheken.
Azure SDK-clients registreren bij de DI-serviceverzameling
De Azure SDK voor .NET-clientbibliotheken bieden serviceclients om uw app te verbinden met Azure-services, zoals Azure Blob Storage en Azure Key Vault. Registreer deze services bij de afhankelijkheidscontainer in het Program.cs
bestand van uw app om ze beschikbaar te maken via afhankelijkheidsinjectie.
Voer de volgende stappen uit om de services te registreren die u nodig hebt:
Voeg het pakket Microsoft.Extensions.Azure toe:
dotnet add package Microsoft.Extensions.Azure
Voeg de relevante
Azure.*
serviceclientpakketten toe:dotnet add package Azure.Security.KeyVault.Secrets dotnet add package Azure.Storage.Blobs dotnet add package Azure.Messaging.ServiceBus
Roep in het
Program.cs
bestand van uw app de AddAzureClients extensiemethode vanuit deMicrosoft.Extensions.Azure
bibliotheek aan om een client te registreren om te communiceren met elke Azure-service. Sommige clientbibliotheken bieden extra subclients voor specifieke subgroepen van de Azure-servicefunctionaliteit. U kunt dergelijke subclients registreren voor afhankelijkheidsinjectie via de AddClient extensiemethode.builder.Services.AddAzureClients(clientBuilder => { // Register a client for each Azure service using inline configuration clientBuilder.AddSecretClient(new Uri("<key_vault_url>")); clientBuilder.AddBlobServiceClient(new Uri("<storage_url>")); clientBuilder.AddServiceBusClientWithNamespace( "<your_namespace>.servicebus.windows.net"); // Register a subclient for each Azure Service Bus Queue var queueNames = new string[] { "queue1", "queue2" }; foreach (string queue in queueNames) { clientBuilder.AddClient<ServiceBusSender, ServiceBusClientOptions>( (_, _, provider) => provider.GetService<ServiceBusClient>() .CreateSender(queue)).WithName(queue); } // Register a shared credential for Microsoft Entra ID authentication clientBuilder.UseCredential(new DefaultAzureCredential()); });
Injecteer de geregistreerde clients in uw ASP.NET Core-app-onderdelen, -services of API-eindpunt:
app.MapGet("/reports", async ( BlobServiceClient blobServiceClient, IAzureClientFactory<ServiceBusSender> senderFactory) => { // Create the named client ServiceBusSender serviceBusSender = senderFactory.CreateClient("queue1"); await serviceBusSender.SendMessageAsync(new ServiceBusMessage("Hello world")); // Use the blob client BlobContainerClient containerClient = blobServiceClient.GetBlobContainerClient("reports"); List<BlobItem> reports = new(); await foreach (BlobItem blobItem in containerClient.GetBlobsAsync()) { reports.Add(blobItem); } return reports; }) .WithName("GetReports");
Zie Afhankelijkheidsinjectie met de Azure SDK voor .NET voor meer informatie.
Verifiëren met behulp van Microsoft Entra-id
Verificatie op basis van tokens met Microsoft Entra-id is de aanbevolen benadering voor het verifiëren van aanvragen voor Azure-services. Om deze aanvragen te autoriseren, beheert op rollen gebaseerd toegangsbeheer (RBAC) van Azure de toegang tot Azure-resources op basis van de Microsoft Entra-identiteit en toegewezen rollen van een gebruiker.
Gebruik de Azure Identity-bibliotheek voor de bovengenoemde verificatieondersteuning op basis van tokens. De bibliotheek biedt klassen zoals DefaultAzureCredential
om het configureren van beveiligde verbindingen te vereenvoudigen.
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. Ga naar de sectie Verificatie van de Azure SDK voor .NET-documenten voor meer informatie over deze onderwerpen.
Notitie
Met veel Azure-services kunt u aanvragen ook autoriseren met behulp van sleutels. 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 autoriseren voor de bijbehorende Azure-resource.
Voeg het Azure.Identity-pakket toe:
dotnet add package Azure.Identity
Roep in het
Program.cs
bestand van uw app de UseCredential extensiemethode vanuit deMicrosoft.Extensions.Azure
bibliotheek aan om een gedeeld exemplaarDefaultAzureCredential
in te stellen voor alle geregistreerde Azure-serviceclients:builder.Services.AddAzureClients(clientBuilder => { // Register a client for each Azure service using inline configuration clientBuilder.AddSecretClient(new Uri("<key_vault_url>")); clientBuilder.AddBlobServiceClient(new Uri("<storage_url>")); clientBuilder.AddServiceBusClientWithNamespace( "<your_namespace>.servicebus.windows.net"); // Register a subclient for each Azure Service Bus Queue var queueNames = new string[] { "queue1", "queue2" }; foreach (string queue in queueNames) { clientBuilder.AddClient<ServiceBusSender, ServiceBusClientOptions>( (_, _, provider) => provider.GetService<ServiceBusClient>() .CreateSender(queue)).WithName(queue); } // Register a shared credential for Microsoft Entra ID authentication clientBuilder.UseCredential(new DefaultAzureCredential()); });
DefaultAzureCredential
detecteert beschikbare referenties in de huidige omgeving en gebruikt deze om te verifiëren bij Azure-services. Zie het overzicht defaultAzureCredential voor de volgorde en locaties waarinDefaultAzureCredential
wordt gescand op referenties. Het gebruik van een gedeeld exemplaarDefaultAzureCredential
zorgt ervoor dat de onderliggende tokencache wordt gebruikt, waardoor de tolerantie en prestaties van toepassingen worden verbeterd vanwege minder aanvragen voor een nieuw token.
Configuraties toepassen
Azure SDK-serviceclients ondersteunen configuraties om hun standaardgedrag te wijzigen. Er zijn twee manieren om serviceclients te configureren:
- JSON-configuratiebestanden zijn over het algemeen de aanbevolen aanpak omdat ze het beheren van verschillen in app-implementaties tussen omgevingen vereenvoudigen.
- Inline-codeconfiguraties kunnen worden toegepast wanneer u de serviceclient registreert. In de sectie Clients en subclients registreren hebt u bijvoorbeeld expliciet de URI-variabelen doorgegeven aan de clientconstructors.
IConfiguration
prioriteitsregels worden gerespecteerd door de Microsoft.Extensions.Azure
uitbreidingsmethoden, die worden beschreven in de documentatie van Configuration Providers .
Voer de stappen in de volgende secties uit om uw app bij te werken voor het gebruik van de JSON-bestandsconfiguratie voor de juiste omgevingen. Gebruik het appsettings.Development.json
bestand voor ontwikkelingsinstellingen en het bestand voor de instellingen van de appsettings.Production.json
productieomgeving. U kunt configuratie-instellingen toevoegen waarvan de namen openbare eigenschappen van de ClientOptions klasse zijn aan het JSON-bestand.
Geregistreerde services configureren
Werk het
appsettings.<environment>.json
bestand in uw app bij met de gemarkeerde serviceconfiguraties:{ "Logging": { "LogLevel": { "Default": "Information", "Microsoft.AspNetCore": "Warning", "Azure.Messaging.ServiceBus": "Debug" } }, "AzureDefaults": { "Diagnostics": { "IsTelemetryDisabled": false, "IsLoggingContentEnabled": true }, "Retry": { "MaxRetries": 3, "Mode": "Exponential" } }, "KeyVault": { "VaultUri": "https://<your-key-vault-name>.vault.azure.net" }, "ServiceBus": { "Namespace": "<your_service-bus_namespace>.servicebus.windows.net" }, "Storage": { "ServiceUri": "https://<your-storage-account-name>.storage.windows.net" } }
In het voorgaande JSON-voorbeeld:
- De sleutelnamen op het hoogste niveau,
KeyVault
,ServiceBus
enStorage
, zijn willekeurige namen die worden gebruikt om te verwijzen naar de configuratiesecties uit uw code. U geeft deze namen door aanAddClient
extensiemethoden om een bepaalde client te configureren. Alle andere sleutelnamen worden toegewezen aan specifieke clientopties en JSON-serialisatie wordt op een niet-hoofdlettergevoelige manier uitgevoerd. - De
KeyVault:VaultUri
,ServiceBus:Namespace
enStorage:ServiceUri
sleutelwaarden worden respectievelijk toegewezen aan de argumenten van de SecretClient(Uri, TokenCredential, SecretClientOptions), ServiceBusClient(String)en BlobServiceClient(Uri, TokenCredential, BlobClientOptions) constructoroverbelastingen. DeTokenCredential
varianten van de constructors worden gebruikt omdat een standaardwaardeTokenCredential
wordt ingesteld via de UseCredential(TokenCredential) methode-aanroep.
- De sleutelnamen op het hoogste niveau,
Werk het
Program.cs
bestand bij om de JSON-bestandsconfiguraties op te halen met behulp vanIConfiguration
en ze door te geven aan uw serviceregistraties.builder.Services.AddAzureClients(clientBuilder => { // Register clients using a config file section clientBuilder.AddSecretClient( builder.Configuration.GetSection("KeyVault")); clientBuilder.AddBlobServiceClient( builder.Configuration.GetSection("Storage")); // Register clients using a specific config key-value pair clientBuilder.AddServiceBusClientWithNamespace( builder.Configuration["ServiceBus:Namespace"]);
Azure-standaardinstellingen en herhalingen configureren
Mogelijk wilt u de standaardconfiguraties van Azure-clients globaal of voor een specifieke serviceclient wijzigen. U wilt bijvoorbeeld misschien andere instellingen voor opnieuw proberen instellen of een andere versie van de service-API gebruiken. U kunt de instellingen voor opnieuw proberen globaal of per service instellen.
Werk uw configuratiebestand bij om standaardinstellingen voor Azure in te stellen, zoals een nieuw standaardbeleid voor opnieuw proberen dat door alle geregistreerde Azure-clients wordt gebruikt:
{ "Logging": { "LogLevel": { "Default": "Information", "Microsoft.AspNetCore": "Warning", "Azure.Messaging.ServiceBus": "Debug" } }, "AzureDefaults": { "Diagnostics": { "IsTelemetryDisabled": false, "IsLoggingContentEnabled": true }, "Retry": { "MaxRetries": 3, "Mode": "Exponential" } }, "KeyVault": { "VaultUri": "https://<your-key-vault-name>.vault.azure.net" }, "ServiceBus": { "Namespace": "<your_service-bus_namespace>.servicebus.windows.net" }, "Storage": { "ServiceUri": "https://<your-storage-account-name>.storage.windows.net" } }
Roep in het
Program.cs
bestand deConfigureDefaults
extensiemethode aan om de standaardinstellingen op te halen en toe te passen op uw serviceclients:builder.Services.AddAzureClients(clientBuilder => { // Register clients using a config file section clientBuilder.AddSecretClient( builder.Configuration.GetSection("KeyVault")); clientBuilder.AddBlobServiceClient( builder.Configuration.GetSection("Storage")); // Register clients using a specific config key-value pair clientBuilder.AddServiceBusClientWithNamespace( builder.Configuration["ServiceBus:Namespace"]); // Register a subclient for each Azure Service Bus Queue string[] queueNames = [ "queue1", "queue2" ]; foreach (string queue in queueNames) { clientBuilder.AddClient<ServiceBusSender, ServiceBusClientOptions>( (_, _, provider) => provider.GetService<ServiceBusClient>() .CreateSender(queue)).WithName(queue); } clientBuilder.UseCredential(new DefaultAzureCredential()); // Set up any default settings clientBuilder.ConfigureDefaults( builder.Configuration.GetSection("AzureDefaults")); });
Logboekregistratie configureren
De Azure SDK voor .NET-clientbibliotheken kunnen clientbibliotheekbewerkingen vastleggen om aanvragen en antwoorden op Azure-services te bewaken. Clientbibliotheken kunnen ook verschillende andere gebeurtenissen registreren, waaronder nieuwe pogingen, het ophalen van tokens en servicespecifieke gebeurtenissen van verschillende clients. Wanneer u een Azure SDK-client registreert met behulp van de AddAzureClients extensiemethode, wordt de AzureEventSourceLogForwarder client geregistreerd bij de container voor afhankelijkheidsinjectie. De AzureEventSourceLogForwarder
stuurt logboekberichten van Azure SDK-evenementbronnen door naar ILoggerFactory, zodat u de standaardconfiguratie voor ASP.NET Core-logboekregistratie kunt gebruiken.
In de volgende tabel ziet u hoe de Azure SDK voor .NET EventLevel
wordt toegewezen aan de ASP.NET Core LogLevel
. Zie voor meer informatie over deze onderwerpen en andere scenario's Logboekregistratie met de Azure SDK voor .NET en Afhankelijkheidsinjectie met de Azure SDK voor .NET.
Azure SDK EventLevel |
ASP.NET Core LogLevel |
---|---|
Critical |
Critical |
Error |
Error |
Informational |
Information |
Warning |
Warning |
Verbose |
Debug |
LogAlways |
Information |
U kunt standaardlogboekniveaus en andere instellingen wijzigen met dezelfde JSON-configuraties die worden beschreven in de sectie Verificatie configureren. Schakel bijvoorbeeld het ServiceBusClient
logboekniveau Debug
in door de Logging:LogLevel:Azure.Messaging.ServiceBus
sleutel als volgt in te stellen:
{
"Logging": {
"LogLevel": {
"Default": "Information",
"Microsoft.AspNetCore": "Warning",
"Azure.Messaging.ServiceBus": "Debug"
}
},
"AzureDefaults": {
"Diagnostics": {
"IsTelemetryDisabled": false,
"IsLoggingContentEnabled": true
},
"Retry": {
"MaxRetries": 3,
"Mode": "Exponential"
}
},
"KeyVault": {
"VaultUri": "https://<your-key-vault-name>.vault.azure.net"
},
"ServiceBus": {
"Namespace": "<your_service-bus_namespace>.servicebus.windows.net"
},
"Storage": {
"ServiceUri": "https://<your-storage-account-name>.storage.windows.net"
}
}