다음을 통해 공유

.NET용 Azure Core 공유 클라이언트 라이브러리 - 버전 1.30.0

  • 아티클

Azure.Core는 최신 .NET Azure SDK 클라이언트 라이브러리에 대한 공유 기본 형식, 추상화 및 도우미를 제공합니다. 이러한 라이브러리는 .NET용 Azure SDK 디자인 지침을 따르며 'Azure'로 시작하는 패키지 및 네임스페이스 이름(예: )으로 쉽게 식별할 수 있습니다. Azure.Storage.Blobs Azure.Core를 사용하는 클라이언트 라이브러리의 전체 목록은 여기에서 찾을 수 있습니다.

Azure.Core를 사용하면 클라이언트 라이브러리가 일관된 방식으로 공통 기능을 노출할 수 있으므로 한 클라이언트 라이브러리에서 이러한 API를 사용하는 방법을 알아보면 다른 클라이언트 라이브러리에서 사용하는 방법을 알 수 있습니다.

소스 코드 | 패키지(NuGet) | API 참조 설명서

시작

일반적으로 Azure.Core를 설치할 필요가 없습니다. 를 사용하여 클라이언트 라이브러리 중 하나를 설치할 때 설치됩니다. 예를 들어 사용자 고유의 클라이언트 라이브러리를 구현하기 위해 명시적으로 설치하려는 경우 여기에서 NuGet 패키지를 찾을 수 있습니다.

주요 개념

Azure.Core의 기본 공유 개념(및 Azure.Core를 사용하는 Azure SDK 라이브러리)에는 다음이 포함됩니다.

  • 서비스 클라이언트 구성(예: 다시 시도 구성, 로깅(ClientOptions))
  • HTTP 응답 세부 정보 액세스(Response, Response<T>).
  • 장기 실행 작업(Operation<T>)을 호출합니다.
  • 페이징 및 비동기 스트림(AsyncPageable<T>).
  • 일관된 방식으로 서비스 요청의 오류를 보고하는 예외입니다. (RequestFailedException).
  • 요청 사용자 지정(RequestContext).
  • Azure SDK 자격 증명을 나타내는 추상화입니다. (TokenCredentials).

아래에서는 이러한 공유 개념을 자세히 설명하는 섹션을 찾을 수 있습니다.

스레드로부터의 안전성

모든 클라이언트 instance 메서드는 스레드로부터 안전하고 서로 독립적임을 보장합니다(지침). 이렇게 하면 스레드 간에 클라이언트 인스턴스를 다시 사용하는 것이 항상 안전합니다.

추가 개념

클라이언트 옵션 | 응답 | 에 액세스 장기 실행 작업 | 오류 | 처리 진단 | 조롱 | 클라이언트 수명

예제

참고: 이 파일의 샘플은 Azure SDK 디자인 지침을 따르는 패키지에만 적용됩니다. 이러한 패키지의 이름은 일반적으로 로 Azure시작합니다.

를 사용하여 서비스 클라이언트 구성 ClientOptions

Azure SDK 클라이언트 라이브러리는 일반적으로 해당 Azure 서비스를 호출하기 위한 기본 시작점인 하나 이상의 서비스 클라이언트 유형을 노출합니다. 이름이 Client라는 단어로 끝나면 이러한 클라이언트 형식을 쉽게 찾을 수 있습니다. 예를 들어 를 BlockBlobClient 사용하여 Blob Storage 서비스를 호출할 수 있으며 KeyClient Key Vault 서비스 암호화 키에 액세스하는 데 사용할 수 있습니다.

이러한 클라이언트 형식은 간단한 생성자 또는 다양한 구성 옵션을 사용하는 오버로드를 호출하여 인스턴스화할 수 있습니다. 이러한 옵션은 Azure.Core에서 노출하는 클래스를 ClientOptions 확장하는 매개 변수로 전달됩니다. 다양한 서비스별 옵션은 일반적으로 하위 클래스에 추가되지만 SDK 전체 옵션 집합은 에서 ClientOptions직접 사용할 수 있습니다.

SecretClientOptions options = new SecretClientOptions()
{
    Retry =
    {
        Delay = TimeSpan.FromSeconds(2),
        MaxRetries = 10,
        Mode = RetryMode.Fixed
    },
    Diagnostics =
    {
        IsLoggingContentEnabled = true,
        ApplicationId = "myApplicationId"
    }
};

SecretClient client = new SecretClient(new Uri("http://example.com"), new DefaultAzureCredential(), options);

클라이언트 구성 샘플의 클라이언트 구성에 대한 자세한 정보

를 사용하여 HTTP 응답 세부 정보 액세스 Response<T>

서비스 클라이언트에는 Azure 서비스를 호출하는 데 사용할 수 있는 메서드가 있습니다. 이러한 클라이언트 메서드 서비스 메서드를 참조합니다. 서비스 메서드 는 공유 Azure.Core 형식 Response<T> 을 반환합니다(드물게 제네릭이 아닌 형제, 원시 Response). 이 형식은 서비스 호출의 역직렬화된 결과와 서버에서 반환된 HTTP 응답의 세부 정보에 대한 액세스를 제공합니다.

// create a client
var client = new SecretClient(new Uri("http://example.com"), new DefaultAzureCredential());

// call a service method, which returns Response<T>
Response<KeyVaultSecret> response = await client.GetSecretAsync("SecretName");

// Response<T> has two main accessors.
// Value property for accessing the deserialized result of the call
KeyVaultSecret secret = response.Value;

// .. and GetRawResponse method for accessing all the details of the HTTP response
Response http = response.GetRawResponse();

// for example, you can access HTTP status
int status = http.Status;

// or the headers
foreach (HttpHeader header in http.Headers)
{
    Console.WriteLine($"{header.Name} {header.Value}");
}

응답 샘플의 응답 유형에 대한 자세한 정보

콘솔 로깅 설정

콘솔에 메시지를 출력하는 Azure SDK 로그 수신기를 만들려면 메서드를 사용합니다 AzureEventSourceListener.CreateConsoleLogger .

// Setup a listener to monitor logged events.
using AzureEventSourceListener listener = AzureEventSourceListener.CreateConsoleLogger();

진단 샘플의 로깅에 대한 자세한 정보

보고 오류 RequestFailedException

서비스 호출이 실패 Azure.RequestFailedException 하면 throw됩니다. 예외 형식은 HTTP 상태 코드가 있는 Status 속성과 서비스별 오류 코드가 있는 ErrorCode 속성을 제공합니다.

try
{
    KeyVaultSecret secret = client.GetSecret("NonexistentSecret");
}
// handle exception with status code 404
catch (RequestFailedException e) when (e.Status == 404)
{
    // handle not found error
    Console.WriteLine("ErrorCode " + e.ErrorCode);
}

응답 샘플에서 응답 처리에 대한 자세한 내용

서비스 메서드 반환 사용 AsyncPageable<T>

서비스 호출이 페이지에서 여러 값을 반환하는 경우 결과적으로 반환 Pageable<T>/AsyncPageable<T> 됩니다. 직접 또는 페이지에서 반복할 AsyncPageable 수 있습니다.

// call a service method, which returns AsyncPageable<T>
AsyncPageable<SecretProperties> allSecretProperties = client.GetPropertiesOfSecretsAsync();

await foreach (SecretProperties secretProperties in allSecretProperties)
{
    Console.WriteLine(secretProperties.Name);
}

페이징된 응답에 대한 자세한 내용은 .NET용 Azure SDK를 사용하여 페이지 매김을 참조하세요.

를 사용하여 Long-Running 작업 사용 Operation<T>

일부 작업을 완료하는 데 시간이 오래 걸리고 상태 대한 폴링이 필요합니다. 장기 실행 작업을 시작하는 메서드는 형식을 반환 *Operation<T> 합니다.

메서드는 WaitForCompletionAsync 작업이 완료될 때까지 기다렸다가 결과 값을 가져오는 쉬운 방법입니다.

// create a client
SecretClient client = new SecretClient(new Uri("http://example.com"), new DefaultAzureCredential());

// Start the operation
DeleteSecretOperation operation = await client.StartDeleteSecretAsync("SecretName");

Response<DeletedSecret> response = await operation.WaitForCompletionAsync();
DeletedSecret value = response.Value;

Console.WriteLine(value.Name);
Console.WriteLine(value.ScheduledPurgeDate);

장기 실행 작업 샘플의 장기 실행 작업에 대한 자세한 정보

를 사용하여 요청 사용자 지정 RequestContext

를 통한 ClientOptions서비스 클라이언트의 일반적인 구성 외에도 프로토콜 메서드 또는 매개 변수로 노출 RequestContext 되는 편리한 API를 사용하여 서비스 클라이언트에서 보낸 요청을 사용자 지정할 수 있습니다.

var context = new RequestContext();
context.AddClassifier(404, isError: false);

Response response = await client.GetPetAsync("pet1", context);

RequestContext 샘플의 요청 사용자 지정에 대한 자세한 정보

모의

Azure.Core를 사용하는 새 클라이언트 라이브러리의 가장 중요한 교차 절단 기능 중 하나는 모의용으로 설계되었다는 것입니다. 모의는 다음을 통해 사용하도록 설정됩니다.

  • 클라이언트 형식에서 보호된 매개 변수 없는 생성자를 제공합니다.
  • 서비스 메서드를 가상으로 만듭니다.
  • 가상 서비스 메서드에서 반환된 모델 형식을 생성하기 위한 API를 제공합니다. 이러한 팩터리 메서드를 찾으려면 ModelFactory 접미사가 있는 형식(예: )을 찾습니다. SecretModelFactory

예를 들어 ConfigurationClient.Get 메서드는 다음과 같이 모의( Moq 포함)할 수 있습니다.

// Create a mock response
var mockResponse = new Mock<Response>();

// Create a mock value
var mockValue = SecretModelFactory.KeyVaultSecret(
    SecretModelFactory.SecretProperties(new Uri("http://example.com"))
);

// Create a client mock
var mock = new Mock<SecretClient>();

// Setup client method
mock.Setup(c => c.GetSecret("Name", null, default))
    .Returns(Response.FromValue(mockValue, mockResponse.Object));

// Use the client mock
SecretClient client = mock.Object;
KeyVaultSecret secret = client.GetSecret("Name");

모의 샘플의 조롱에 대한 자세한 정보

Application Insights를 사용하여 분산 추적

Azure Monitor의 기능인 Application Insights는 개발자와 DevOps 전문가를 위한 확장 가능한 APM(애플리케이션 성능 관리) 서비스입니다. 라이브 애플리케이션을 모니터링하는 데 사용합니다. 성능 변칙을 자동으로 검색하고 문제를 진단하고 사용자가 앱에서 실제로 수행하는 작업을 이해하는 데 도움이 되는 강력한 분석 도구가 포함되어 있습니다.

애플리케이션이 이미 ApplicationInsights를 사용하는 경우 버전 2.12.0이후 Azure SDK 추적의 자동 컬렉션이 지원됩니다.

애플리케이션에 대한 ApplicationInsights 추적을 설정하려면 모니터링 애플리케이션 시작 가이드를 따릅니다.

진단 샘플의 진단 대한 자세한 정보

문제 해결

오류를 해결하는 세 가지 기본 방법은 예외 검사, 로깅 사용 및 분산 추적입니다.

다음 단계

사용 가능한 Azure SDK 라이브러리를 탐색하고 설치합니다.

참여

이 프로젝트에 대한 기여와 제안을 환영합니다. 대부분의 경우 기여하려면 권한을 부여하며 실제로 기여를 사용할 권한을 당사에 부여한다고 선언하는 CLA(기여자 라이선스 계약)에 동의해야 합니다. 자세한 내용은 https://cla.microsoft.com 을 참조하세요.

끌어오기 요청을 제출하면 CLA-bot은 CLA를 제공하고 PR을 적절하게 데코레이팅해야 하는지 여부를 자동으로 결정합니다(예: 레이블, 설명). 봇에서 제공하는 지침을 따르기만 하면 됩니다. CLA를 사용하여 모든 리포지토리에서 한 번만 이 작업을 수행해야 합니다.

이 프로젝트에는 Microsoft Open Source Code of Conduct(Microsoft 오픈 소스 준수 사항)가 적용됩니다. 자세한 내용은 Code of Conduct FAQ(규정 FAQ)를 참조하세요. 또는 추가 질문이나 의견은 opencode@microsoft.com으로 문의하세요.

Impressions