ASP.NET Core 앱에서 .NET용 Azure SDK 사용

아티클
11/16/2024

.NET용 Azure SDK를 사용하면 ASP.NET Core 앱이 다양한 Azure 서비스와 통합될 수 있습니다. 이 문서에서는 ASP.NET Core 앱에서 .NET용 Azure SDK를 채택하는 모범 사례 및 단계를 알아봅니다. 이 문서에서 배울 내용은 다음과 같습니다.

종속성 주입을 위한 서비스를 등록합니다.
암호 또는 비밀을 사용하지 않고 Azure에 인증합니다.
중앙 집중식 표준화된 구성을 구현합니다.
로깅 및 다시 시도와 같은 일반적인 웹앱 문제를 구성합니다.

일반적인 Azure SDK 클라이언트 라이브러리 살펴보기

Azure 서비스에 연결하는 ASP.NET Core 앱은 일반적으로 다음 Azure SDK 클라이언트 라이브러리에 따라 달라집니다.

Microsoft.Extensions.Azure 는 클라이언트를 종속성 주입 서비스 컬렉션에 등록하는 도우미 메서드를 제공하고 로깅 설정, DI 서비스 수명 처리, 인증 자격 증명 관리와 같은 다양한 문제를 처리합니다.
Azure.Identity 를 사용하면 Azure SDK에서 Microsoft Entra ID 인증을 지원할 수 있습니다. Microsoft Entra 인증을 지원하는 Azure SDK 클라이언트를 생성하기 위한 TokenCredential 구현 집합을 제공합니다.
Azure.<service-namespace>Azure.Storage.Blobs 및 Azure.Messaging.ServiceBus와 같은 라이브러리는 특정 Azure 서비스에 연결하고 사용하는 데 도움이 되는 서비스 클라이언트 및 기타 형식을 제공합니다. 이러한 라이브러리의 전체 인벤토리는 Azure.Core를 사용하는 라이브러리를 참조하세요.

앞의 섹션에서는 이러한 라이브러리를 사용하는 ASP.NET Core 애플리케이션을 구현하는 방법을 살펴봅니다.

DI 서비스 컬렉션에 Azure SDK 클라이언트 등록

.NET용 Azure SDK 클라이언트 라이브러리는 Azure Blob Storage 및 Azure Key Vault와 같은 Azure 서비스에 앱을 연결하는 서비스 클라이언트를 제공합니다. 이러한 서비스를 앱 파일의 종속성 컨테이너에 Program.cs 등록하여 종속성 주입을 통해 사용할 수 있도록 합니다.

다음 단계를 완료하여 필요한 서비스를 등록합니다.

Microsoft.Extensions.Azure 패키지를 추가합니다.
```
dotnet add package Microsoft.Extensions.Azure
```

관련 Azure.* 서비스 클라이언트 패키지를 추가합니다.

dotnet add package Azure.Security.KeyVault.Secrets
dotnet add package Azure.Storage.Blobs
dotnet add package Azure.Messaging.ServiceBus

Program.cs 앱 파일에서 라이브러리에서 확장 메서드를 Microsoft.Extensions.Azure 호출 AddAzureClients 하여 클라이언트를 등록하여 각 Azure 서비스와 통신합니다. 일부 클라이언트 라이브러리는 Azure 서비스 기능의 특정 하위 그룹에 대한 추가 하위 집합 을 제공합니다. 확장 메서드를 통해 종속성 주입을 위해 이러한 하위클라이언트를 등록할 AddClient 수 있습니다.

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());
});

등록된 클라이언트를 ASP.NET Core 앱 구성 요소, 서비스 또는 API 엔드포인트에 삽입합니다.

최소 API
Blazor

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

@page "/"
@using Azure.Storage.Blobs
@using Azure.Storage.Blobs.Models
@using Azure.Messaging.ServiceBus
@using Microsoft.Extensions.Azure;

<h1>Reports</h1>

<ul>
    @foreach (var report in reports)
    {
        <li>@report.Name</li>
    }
</ul>

@code {
    List<BlobItem> reports = new();

    private BlobServiceClient _blobServiceClient;
    private ServiceBusSender _serviceBusSender;

    public Home(
        BlobServiceClient blobServiceClient,
        IAzureClientFactory<ServiceBusSender> senderFactory)
    {
         _blobServiceClient = blobServiceClient;
        _serviceBusSender = senderFactory.CreateClient("queue1");
    }

자세한 내용은 .NET용 Azure SDK를 사용한 종속성 주입을 참조하세요.

Microsoft Entra ID를 사용하여 인증

Microsoft Entra ID를 사용한 토큰 기반 인증은 Azure 서비스에 대한 요청을 인증하는 데 권장되는 방법입니다. 이러한 요청에 권한을 부여하기 위해 Azure RBAC(역할 기반 액세스 제어) 는 사용자의 Microsoft Entra ID 및 할당된 역할에 따라 Azure 리소스에 대한 액세스를 관리합니다.

앞에서 언급한 토큰 기반 인증 지원에 Azure ID 라이브러리를 사용합니다. 라이브러리는 보안 연결 구성을 간소화하는 것과 같은 DefaultAzureCredential 클래스를 제공합니다. DefaultAzureCredential은 여러 인증 방법을 지원하고 런타임에 사용해야 하는 방법을 결정합니다. 이 방법을 사용하면 앱에서 환경별 코드를 구현하지 않고도 다양한 환경(로컬 및 프로덕션)에서 다양한 인증 방법을 사용할 수 있습니다. 이러한 항목에 대한 자세한 내용은 .NET용 Azure SDK 문서의 인증 섹션을 참조하세요.

참고 항목

또한 많은 Azure 서비스를 통해 키를 사용하여 요청에 권한을 부여할 수 있습니다. 그러나 이 방법은 신중하게 사용해야 합니다. 개발자는 액세스 키를 안전하지 않은 위치에 노출하지 않도록 끊임없이 노력해야 합니다. 액세스 키가 있는 모든 사용자는 연결된 Azure 리소스에 대한 요청에 권한을 부여할 수 있습니다.

Azure.Identity 패키지를 추가합니다.
```
dotnet add package Azure.Identity
```

Program.cs 앱 파일에서 라이브러리에서 확장 메서드를 Microsoft.Extensions.Azure 호출 UseCredential 하여 등록된 모든 Azure 서비스 클라이언트에 대한 공유 DefaultAzureCredential 인스턴스를 설정합니다.

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 는 현재 환경에서 사용 가능한 자격 증명을 검색하고 이를 사용하여 Azure 서비스에 인증합니다. 자격 증명을 검색하는 DefaultAzureCredential 순서 및 위치는 DefaultAzureCredential 개요를 참조하세요. 공유 DefaultAzureCredential 인스턴스를 사용하면 기본 토큰 캐시가 사용되므로 새 토큰에 대한 요청 수가 줄어들어 애플리케이션 복원력과 성능이 향상됩니다.

구성 적용

Azure SDK 서비스 클라이언트는 기본 동작을 변경하는 구성을 지원합니다. 서비스 클라이언트를 구성하는 방법에는 두 가지가 있습니다.

JSON 구성 파일 은 일반적으로 환경 간 앱 배포의 차이점 관리를 간소화하기 때문에 권장되는 방법입니다.
서비스 클라이언트를 등록할 때 인라인 코드 구성을 적용할 수 있습니다. 예를 들어 클라이언트 등록 및 하위클라이언트 섹션에서 클라이언트 생성자에 URI 변수를 명시적으로 전달했습니다.

IConfiguration 우선 순위 규칙은 구성 공급자 설명서에 Microsoft.Extensions.Azure 자세히 설명된 확장 메서드에 의해 준수됩니다 .

다음 섹션의 단계를 완료하여 적절한 환경에 JSON 파일 구성을 사용하도록 앱을 업데이트합니다. 개발 설정에 appsettings.Development.json 파일을 사용하고 프로덕션 환경 설정에 appsettings.Production.json 파일을 사용합니다. 이름이 클래스의 ClientOptions 공용 속성인 구성 설정을 JSON 파일에 추가할 수 있습니다.

등록된 서비스 구성

appsettings.<environment>.json 강조 표시된 서비스 구성으로 앱의 파일을 업데이트합니다.
```
{
  "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"
  }
}
```
이전 JSON 샘플에서:
- 최상위 키 이름, KeyVaultServiceBus및 Storage이름은 코드에서 구성 섹션을 참조하는 데 사용되는 임의의 이름입니다. 이러한 이름을 확장 메서드에 전달하여 AddClient 지정된 클라이언트를 구성합니다. 다른 모든 키 이름은 특정 클라이언트 옵션에 매핑되며 JSON serialization은 대/소문자를 구분하지 않는 방식으로 수행됩니다.
- , ServiceBus:Namespace및 키 값은 KeyVault:VaultUri각각 , ServiceBusClient(String)및 BlobServiceClient(Uri, TokenCredential, BlobClientOptions) 생성자 오버로드의 SecretClient(Uri, TokenCredential, SecretClientOptions)인수에 매핑 Storage:ServiceUri 됩니다. 기본 TokenCredential은 UseCredential(TokenCredential) 메서드 호출을 통해 설정되기 때문에 생성자의 TokenCredential 변형이 사용됩니다.

Program.cs 파일을 업데이트하여 JSON 파일 구성을 검색 IConfiguration 하고 서비스 등록에 전달합니다.

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 기본값 구성 및 다시 시도

전역적으로 또는 특정 서비스 클라이언트에 대한 기본 Azure 클라이언트 구성을 변경할 수 있습니다. 예를 들어 다른 재시도 설정을 사용하거나 다른 서비스 API 버전을 사용할 수 있습니다. 재시도 설정은 전역으로 또는 서비스별로 설정할 수 있습니다.

등록된 모든 Azure 클라이언트에서 사용할 새 기본 다시 시도 정책과 같은 기본 Azure 설정을 설정하도록 구성 파일을 업데이트합니다.

{
  "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"
  }
}

Program.cs 파일에서 확장 메서드를 ConfigureDefaults 호출하여 기본 설정을 검색하고 서비스 클라이언트에 적용합니다.

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

로깅 구성

.NET용 Azure SDK 클라이언트 라이브러리는 클라이언트 라이브러리 작업을 기록하여 Azure 서비스에 대한 요청 및 응답을 모니터링할 수 있습니다. 클라이언트 라이브러리는 재시도, 토큰 검색 및 다양한 클라이언트의 서비스별 이벤트를 비롯한 다양한 다른 이벤트를 기록할 수도 있습니다. 확장 메서드 AzureEventSourceLogForwarder 를 사용하여 Azure SDK 클라이언트를 AddAzureClients 등록하면 종속성 주입 컨테이너에 등록됩니다. AzureEventSourceLogForwarder 로깅에 표준 ASP.NET Core 로깅 구성을 사용할 수 있도록 Azure SDK 이벤트 원본 ILoggerFactory 에서 로그 메시지를 전달합니다.

다음 표에서 .NET용 Azure SDK EventLevel이 ASP.NET Core LogLevel로 매핑되는 방식을 볼 수 있습니다. 이러한 항목 및 기타 시나리오에 대한 자세한 내용은 .NET용 Azure SDK 및 .NET 용 Azure SDK를 사용한 종속성 주입을 사용하여 로깅을 참조하세요.

Azure SDK `EventLevel`	ASP.NET Core `LogLevel`
`Critical`	`Critical`
`Error`	`Error`
`Informational`	`Information`
`Warning`	`Warning`
`Verbose`	`Debug`
`LogAlways`	`Information`

인증 구성 섹션에 설명된 것과 동일한 JSON 구성을 사용하여 기본 로그 수준 및 기타 설정을 변경할 수 있습니다. 예를 들어 다음과 같이 키를 설정 Logging:LogLevel:Azure.Messaging.ServiceBus 하여 로그 수준을 Debug 전환 ServiceBusClient 합니다.

{
  "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"
  }
}

다음을 통해 공유