Общая клиентская библиотека Azure Core для .NET — версия 1.30.0

Azure.Core предоставляет общие примитивы, абстракции и вспомогательные средства для современных клиентских библиотек пакета SDK azure для .NET. Эти библиотеки соответствуют рекомендациям по проектированию пакета Azure SDK для .NET и могут быть легко определены по именам пакетов и пространств имен, начиная с "Azure", например Azure.Storage.Blobs. Более полный список клиентских библиотек, использующих Azure.Core, можно найти здесь.

Azure.Core позволяет клиентским библиотекам предоставлять общие функциональные возможности согласованно, поэтому, научившись использовать эти API в одной клиентской библиотеке, вы узнаете, как использовать их в других клиентских библиотеках.

Исходный код | Пакет (NuGet) | Справочная документация по API

Начало работы

Как правило, устанавливать Azure.Core не требуется; он будет установлен автоматически при установке одной из клиентских библиотек с его помощью. Если вы хотите установить его явным образом (например, для реализации собственной клиентской библиотеки), пакет NuGet можно найти здесь.

Основные понятия

Main общие понятия Azure.Core (и поэтому библиотеки пакета SDK Azure, использующие Azure.Core), включают:

• Настройка клиентов службы, например настройка повторных попыток, ведение журнала (ClientOptions).
• Доступ к сведениям ОБ HTTP-ответе (Response, Response<T>).
• Вызов длительных операций (Operation<T>).
• Разбиение по страницам и асинхронные потоки (AsyncPageable<T>).
• Исключения для согласованного сообщения об ошибках из запросов на обслуживание. (RequestFailedException).
• Настройка запроса (RequestContext).
• Абстракции для представления учетных данных пакета AZURE SDK. (TokenCredentials).

Ниже приведены разделы, описывающие эти общие понятия более подробно.

Потокобезопасность

Мы гарантируем, что все методы экземпляра клиента являются потокобезопасны и независимы друг от друга (руководство). Это гарантирует, что рекомендация по повторному использованию экземпляров клиента всегда будет безопасной, даже в разных потоках.

Дополнительные понятия

Параметры | клиента Доступ к ответу | Длительные операции | Обработка сбоев | Диагностики | Насмешливый | Время существования клиента

Примеры

ПРИМЕЧАНИЕ: Примеры в этом файле применяются только к пакетам, которые соответствуют рекомендациям по проектированию пакета AZURE SDK. Имена таких пакетов обычно начинаются с Azure.

Настройка клиентов службы с помощью ClientOptions

Клиентские библиотеки пакета SDK Azure обычно предоставляют один или несколько типов клиентов служб, которые являются main отправными точками для вызова соответствующих служб Azure. Вы можете легко найти эти типы клиентов, так как их имена заканчиваются словом Client. Например, BlockBlobClient может использоваться для вызова службы хранилища BLOB-объектов, а KeyClient также для доступа к криптографическим ключам службы Key Vault.

Эти типы клиентов могут создаваться путем вызова простого конструктора или его перегрузки, которая принимает различные параметры конфигурации. Эти параметры передаются как параметр, расширяющий ClientOptions класс, предоставляемый Azure.Core. Различные параметры службы обычно добавляются в ее подклассы, но набор параметров пакета 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. Мы ссылаемся на эти методы обслуживания клиентских методов. Методы службы возвращают общий тип Response<T> Azure.Core (в редких случаях его неуниверсивный одноуровневый элемент— необработанный 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 вызова службы возникает ошибка. Тип исключения предоставляет свойство Status с кодом состояния HTTP и свойство 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);
}

Дополнительные сведения об ответах с разбивкой на страницы см. в статье Разбивка на страницы с помощью пакета Azure SDK для .NET.

Использование операций 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можно настроить запросы, отправляемые клиентами службы , с помощью методов протокола или удобных API, которые предоставляются RequestContext в качестве параметра.

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

Application Insights, компонент Azure Monitor, является расширяемой службой управления производительностью приложений (APM) для разработчиков и DevOps-специалистов. Используйте ее для мониторинга ваших работающих приложений. Он автоматически обнаруживает аномалии производительности и включает мощные средства аналитики, которые помогут диагностировать проблемы и понять, что пользователи на самом деле делают с вашим приложением.

Если приложение уже использует ApplicationInsights, автоматический сбор трассировок пакета AZURE SDK поддерживается начиная с версии 2.12.0.

Чтобы настроить отслеживание ApplicationInsights для приложения, следуйте указаниям в руководстве по запуску мониторинга приложения .

Дополнительные сведения о диагностика в диагностика примерах.

Устранение неполадок

Три main способа устранения неполадок — проверка исключений, включение ведения журнала и распределенная трассировка

Дальнейшие действия

Изучите и установите доступные библиотеки azure SDK.

Участие

На этом проекте приветствуются публикации и предложения. Для участия в большинстве процессов по разработке документации необходимо принять лицензионное соглашение участника (CLA), в котором указывается, что вы предоставляете нам права на использование ваших публикаций. Для получения подробных сведений посетите веб-страницу https://cla.microsoft.com.

При отправке запроса на включение внесенных изменений CLA-бот автоматически определит необходимость предоставления соглашения CLA и соответствующего оформления запроса на включение внесенных изменений (например, добавление метки, комментария). Просто следуйте инструкциям бота. Это потребуется сделать только один раз во всех репозиториях с помощью нашего CLA.

В рамках этого проекта действуют правила поведения в отношении продуктов с открытым исходным кодом Майкрософт. Дополнительные сведения см. в разделе часто задаваемых вопросов о правилах поведения или обратитесь к opencode@microsoft.com с любыми дополнительными вопросами или комментариями.