клиентская библиотека Центры событий Azure для .NET версии 5.8.1

  • Статья

Центры событий Azure — это высокомасштабируемая служба публикации и подписки, которая может принимать миллионы событий в секунду и передавать их нескольким потребителям. Это позволяет обрабатывать и анализировать большие объемы данных, создаваемых подключенными устройствами и приложениями. После сбора данных Центры событий можно получать, преобразовывать и хранить их с помощью любого поставщика аналитики в режиме реального времени или адаптеров пакетной обработки и хранения. Если вы хотите узнать больше о Центры событий Azure, ознакомьтесь с разделом Что такое Центры событий.

Клиентская библиотека Центров событий Azure позволяет публиковать и потреблять события Центров событий Azure и может использоваться в следующих целях:

  • выдача данных телеметрии о приложении для бизнес-аналитики и диагностики;

  • публикация фактов о состоянии вашего приложения, которые заинтересованные стороны могут наблюдать и использовать в качестве триггера для выполнения действий;

  • наблюдение за важными операциями и взаимодействиями внутри бизнес-среды или другой экосистемы, что позволяет слабо связанным системам взаимодействовать без необходимости привязывать их друг к другу;

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

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

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

Предварительные требования

  • Подписка Azure: Чтобы использовать службы Azure, включая Центры событий Azure, вам потребуется подписка. Если у вас нет учетной записи Azure, вы можете зарегистрироваться для получения бесплатной пробной версии или использовать преимущества подписки Visual Studio при создании учетной записи.

  • Пространство имен Центров событий с концентратором событий: Для взаимодействия с Центры событий Azure также необходимо иметь пространство имен и концентратор событий. Если вы не знакомы с созданием ресурсов Azure, вы можете воспользоваться пошаговым руководством по созданию концентратора событий с помощью портал Azure. Здесь также можно найти подробные инструкции по использованию Azure CLI, Azure PowerShell или шаблонов Azure Resource Manager (ARM) для создания концентратора событий.

  • C# 8.0: Клиентская библиотека Центры событий Azure использует новые функции, появившиеся в C# 8.0. Чтобы воспользоваться преимуществами синтаксиса C# 8.0, рекомендуется компилировать с помощью пакета SDK для .NET Core версии 3.0 или более поздней версии с языковой версиейlatest.

    Пользователям Visual Studio, желающим использовать все преимущества синтаксиса C# 8.0, потребуется использовать Visual Studio 2019 или более поздней версии. Скачать Visual Studio 2019, в том числе бесплатный выпуск Community, можно здесь. Пользователи Visual Studio 2017 могут воспользоваться преимуществами синтаксиса C# 8, используя пакет NuGet Microsoft.Net.Compilers и задав версию языка, хотя процесс редактирования может быть не идеальным.

    Вы по-прежнему можете использовать библиотеку с предыдущими версиями языка C#, но вам придется управлять асинхронными перечисляемыми и асинхронными одноразовыми элементами вручную, а не использовать преимущества нового синтаксиса. Вы по-прежнему можете использовать любую версию платформы, поддерживаемую пакетом SDK для .NET Core, включая более ранние версии .NET Core или .NET Framework. Дополнительные сведения см. в статье Определение целевых платформ.
    Важное примечание. Для сборки или выполнения примеров и примеров без изменений необходимо использовать C# 11.0. Вы по-прежнему можете запускать примеры, если решите настроить их для других языковых версий. Пример этого доступен в примере: Более ранние версии языка.

Чтобы быстро создать базовый набор ресурсов Центров событий в Azure и получить для них строку подключения, можно развернуть наш пример шаблона, щелкнув:

Развертывание в Azure

Установка пакета

Установите клиентную библиотеку Центры событий Azure для .NET с помощью NuGet:

dotnet add package Azure.Messaging.EventHubs

Аутентификация клиента

Чтобы клиентская библиотека Центров событий взаимодействовала с концентратором событий, ей необходимо понимать, как подключиться и авторизовать его. Самый простой способ сделать это — использовать строку подключения, которая создается автоматически при создании пространства имен Центров событий. Если вы не знакомы с использованием строк подключения к Центрам событий, вы можете воспользоваться пошаговым руководством, чтобы получить строку подключения к Центрам событий.

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

  • Клиент концентратора событий — это основной интерфейс для разработчиков, взаимодействующих с клиентской библиотекой службы "Центры событий". Существует несколько различных клиентов службы "Центры событий", каждый из которых предназначен для определенного ее использования, например публикации или использования событий.

  • Производитель концентратора событий — это тип клиента, служащий источником данных телеметрии, диагностических сведений, журналов использования и другими данных журналов в составе решения для встроенных устройств, приложения для мобильных устройств, игры, работающей на консоли или на другом устройстве, а также некоторых клиентских или серверных бизнес-решений или веб-сайта.

  • Потребитель концентратора событий — это тип клиента, который считывает данные из концентратора событий и позволяет обрабатывать его. Обработка может подразумевать агрегирование, сложные вычисления и фильтрацию. Обработка может также включать распространение или хранение информации в исходном или преобразованном виде. Потребители концентраторов событий часто являются надежными и масштабируемыми частями инфраструктурами платформы со встроенными возможностями аналитики, например Azure Stream Analytics, Apache Spark или Apache Storm.

  • Секция — это упорядоченная последовательность событий, которая хранится в концентраторе событий. Секции   это средства организации данных, связанные с параллелизмом, требуемым потребителями событий. Служба "Центры событий Azure" обеспечивает потоковую передачу сообщений посредством шаблона секционированных потребителей, в котором каждый потребитель считывает только определенное подмножество (секцию) потока сообщений. По мере поступления новых событий они добавляются в конец этой последовательности. Количество секций указывается во время создания концентратора событий и не может быть изменено.

  • Группа потребителей — это представление всего концентратора событий. Группы потребителей предоставляют каждому из нескольких приложений возможность иметь отдельное представление потока событий, а также считывать поток независимо друг от друга, в собственном темпе и из собственного положения. В одной группе потребителей может быть не более 5 одновременных читателей. Однако рекомендуется только один активный потребитель для каждой пары из секции и группы потребителей. Каждый активный читатель получает все события из своего раздела. Если в одном разделе несколько читателей, они получат дублирующиеся события.

Дополнительные понятия и более подробное обсуждение см. в разделе Функции Центров событий.

Время существования клиента

Каждый из типов клиентов Центров событий можно безопасно кэшировать и использовать в качестве отдельного экземпляра на протяжении всего времени существования приложения, что рекомендуется при регулярной публикации или считывания событий. Клиенты отвечают за эффективное управление сетью, ЦП и использованием памяти, работая над тем, чтобы обеспечить низкий уровень использования в периоды бездействия. CloseAsync Для правильной очистки сетевых ресурсов и других неуправляемых объектов требуется вызов или DisposeAsync на клиенте.

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

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

Типы моделей данных, такие как EventData и EventDataBatch , не являются потокобезопасны. Они не должны совместно использоваться в потоках и использоваться одновременно с клиентскими методами.

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

Параметры | клиента Обработка сбоев | Диагностики | Насмешливый

Примеры

Проверка концентратора событий

Многие операции с концентратором событий выполняются в области определенной секции. Поскольку секции принадлежат концентратору событий, их имена назначаются во время создания. Чтобы понять, какие секции доступны, опросите концентратор событий с помощью одного из клиентов концентратора событий. В примерах показано EventHubProducerClient, но суть и форма одинаковы для всех клиентов.

var connectionString = "<< CONNECTION STRING FOR THE EVENT HUBS NAMESPACE >>";
var eventHubName = "<< NAME OF THE EVENT HUB >>";

await using (var producer = new EventHubProducerClient(connectionString, eventHubName))
{
    string[] partitionIds = await producer.GetPartitionIdsAsync();
}

Публикация событий в концентраторе событий

Чтобы опубликовать события, необходимо создать EventHubProducerClient. Производители публикуют события пакетами и могут запросить определенную секцию или разрешить службе "Центры событий" выбрать, какие события секции будут опубликованы. Рекомендуется использовать автоматическую маршрутизацию, когда публикация событий должна быть высокой доступностью или когда данные о событиях должны распределяться равномерно между секциями. В нашем примере будет использоваться автоматическая маршрутизация.

var connectionString = "<< CONNECTION STRING FOR THE EVENT HUBS NAMESPACE >>";
var eventHubName = "<< NAME OF THE EVENT HUB >>";

await using (var producer = new EventHubProducerClient(connectionString, eventHubName))
{
    using EventDataBatch eventBatch = await producer.CreateBatchAsync();
    eventBatch.TryAdd(new EventData(new BinaryData("First")));
    eventBatch.TryAdd(new EventData(new BinaryData("Second")));

    await producer.SendAsync(eventBatch);
}

Чтение событий из концентратора событий

Чтобы считывать события из концентратора событий, необходимо создать EventHubConsumerClient для данной группы потребителей. При создании концентратора событий он предоставляет группу потребителей по умолчанию, которую можно использовать для начала работы с концентраторами событий. В нашем примере мы рассмотрим чтение всех событий, опубликованных в концентраторе событий с помощью итератора.

Примечание: Важно отметить, что этот подход к потреблению предназначен для улучшения опыта изучения клиентской библиотеки Центров событий и создания прототипов. Рекомендуется не использовать его в рабочих сценариях. Для использования в рабочей среде рекомендуем выбрать клиент обработчика событий, так как он обеспечивает более надежную и производительную работу.

var connectionString = "<< CONNECTION STRING FOR THE EVENT HUBS NAMESPACE >>";
var eventHubName = "<< NAME OF THE EVENT HUB >>";

string consumerGroup = EventHubConsumerClient.DefaultConsumerGroupName;

await using (var consumer = new EventHubConsumerClient(consumerGroup, connectionString, eventHubName))
{
    using var cancellationSource = new CancellationTokenSource();
    cancellationSource.CancelAfter(TimeSpan.FromSeconds(45));

    await foreach (PartitionEvent receivedEvent in consumer.ReadEventsAsync(cancellationSource.Token))
    {
        // At this point, the loop will wait for events to be available in the Event Hub.  When an event
        // is available, the loop will iterate with the event that was received.  Because we did not
        // specify a maximum wait time, the loop will wait forever unless cancellation is requested using
        // the cancellation token.
    }
}

Чтение событий из секции концентратора событий

Чтобы считывать события для секции концентратора событий, необходимо создать для данной EventHubConsumerClient группы потребителей. При создании концентратора событий он предоставляет группу потребителей по умолчанию, которую можно использовать для начала работы с концентраторами событий. Чтобы считывать данные из определенной секции, потребителю также потребуется указать, где в потоке событий следует начать получать события; В нашем примере мы сосредоточимся на чтении всех опубликованных событий для первого раздела концентратора событий.

var connectionString = "<< CONNECTION STRING FOR THE EVENT HUBS NAMESPACE >>";
var eventHubName = "<< NAME OF THE EVENT HUB >>";

string consumerGroup = EventHubConsumerClient.DefaultConsumerGroupName;

await using (var consumer = new EventHubConsumerClient(consumerGroup, connectionString, eventHubName))
{
    EventPosition startingPosition = EventPosition.Earliest;
    string partitionId = (await consumer.GetPartitionIdsAsync()).First();

    using var cancellationSource = new CancellationTokenSource();
    cancellationSource.CancelAfter(TimeSpan.FromSeconds(45));

    await foreach (PartitionEvent receivedEvent in consumer.ReadEventsFromPartitionAsync(partitionId, startingPosition, cancellationSource.Token))
    {
        // At this point, the loop will wait for events to be available in the partition.  When an event
        // is available, the loop will iterate with the event that was received.  Because we did not
        // specify a maximum wait time, the loop will wait forever unless cancellation is requested using
        // the cancellation token.
    }
}

Обработка событий с помощью клиента обработчика событий

В большинстве рабочих сценариев рекомендуется использовать клиент обработчика событий для чтения и обработки событий. Процессор предназначен для обеспечения надежной обработки событий во всех разделах концентратора событий в производительном и отказоустойчивом режиме, обеспечивая при этом средства для сохранения его состояния. Клиенты обработчика событий также могут совместно работать в контексте группы потребителей для данного концентратора событий, где они будут автоматически управлять распределением и балансировкой работы по мере того, как экземпляры становятся доступными или недоступными для группы.

Поскольку EventProcessorClient имеет зависимость от BLOB-объектов службы хранилища Azure для сохранения состояния, необходимо предоставить BlobContainerClient для процессора, который был настроен для учетной записи хранения, и контейнера, который следует использовать.

var cancellationSource = new CancellationTokenSource();
cancellationSource.CancelAfter(TimeSpan.FromSeconds(45));

var storageConnectionString = "<< CONNECTION STRING FOR THE STORAGE ACCOUNT >>";
var blobContainerName = "<< NAME OF THE BLOB CONTAINER >>";

var eventHubsConnectionString = "<< CONNECTION STRING FOR THE EVENT HUBS NAMESPACE >>";
var eventHubName = "<< NAME OF THE EVENT HUB >>";
var consumerGroup = "<< NAME OF THE EVENT HUB CONSUMER GROUP >>";

Task processEventHandler(ProcessEventArgs eventArgs) => Task.CompletedTask;
Task processErrorHandler(ProcessErrorEventArgs eventArgs) => Task.CompletedTask;

var storageClient = new BlobContainerClient(storageConnectionString, blobContainerName);
var processor = new EventProcessorClient(storageClient, consumerGroup, eventHubsConnectionString, eventHubName);

processor.ProcessEventAsync += processEventHandler;
processor.ProcessErrorAsync += processErrorHandler;

await processor.StartProcessingAsync();

try
{
    // The processor performs its work in the background; block until cancellation
    // to allow processing to take place.

    await Task.Delay(Timeout.Infinite, cancellationSource.Token);
}
catch (TaskCanceledException)
{
    // This is expected when the delay is canceled.
}

try
{
    await processor.StopProcessingAsync();
}
finally
{
    // To prevent leaks, the handlers should be removed when processing is complete.

    processor.ProcessEventAsync -= processEventHandler;
    processor.ProcessErrorAsync -= processErrorHandler;
}

Дополнительные сведения можно найти в файле сведений клиента обработчика событий и в соответствующих примерах.

Использование субъекта Active Directory с клиентами концентратора событий

Библиотека удостоверений Azure предоставляет поддержку проверки подлинности Azure Active Directory, которую можно использовать для клиентских библиотек Azure, включая Центры событий.

Чтобы использовать субъект Active Directory, при создании клиента Центров событий указывается один из доступных учетных данных из Azure.Identity библиотеки. Кроме того, полное пространство имен Центров событий и имя нужного концентратора событий предоставляются вместо строки подключения Центров событий. В примерах показано EventHubProducerClient, но суть и форма одинаковы для всех клиентов.

var fullyQualifiedNamespace = "<< FULLY-QUALIFIED EVENT HUBS NAMESPACE (like something.servicebus.windows.net) >>";
var eventHubName = "<< NAME OF THE EVENT HUB >>";
var credential = new DefaultAzureCredential();

await using (var producer = new EventHubProducerClient(fullyQualifiedNamespace, eventHubName, credential))
{
    using EventDataBatch eventBatch = await producer.CreateBatchAsync();
    eventBatch.TryAdd(new EventData(new BinaryData("First")));
    eventBatch.TryAdd(new EventData(new BinaryData("Second")));

    await producer.SendAsync(eventBatch);
}

При использовании Azure Active Directory субъекту должна быть назначена роль, которая разрешает доступ к Центрам Azure Event Hubs Data Owner событий, например к роли . Дополнительные сведения об использовании авторизации Azure Active Directory с Центрами событий см. в соответствующей документации.

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

Подробные сведения об устранении неполадок см. в руководстве по устранению неполадок Центров событий.

Ведение журнала и диагностика

Клиентская библиотека Центров событий полностью инструментирована для ведения журнала сведений на различных уровнях детализации с помощью .NET EventSource для выдачи сведений. Ведение журнала выполняется для каждой операции и соответствует шаблону маркировки начальной точки операции, ее завершения и всех возникающих исключений. Дополнительные сведения, которые могут предоставлять аналитические сведения, также регистрируются в контексте связанной операции.

Клиентские журналы Центров событий доступны для любого EventListener пользователя, выбрав источник с именем Azure-Messaging-EventHubs или выбрав все источники с признаком AzureEventSource. Чтобы упростить запись журналов из клиентских библиотек Azure, библиотека, используемая Центрами событий, Azure.Core предлагает AzureEventSourceListener. Дополнительные сведения см. в статье Сбор журналов Центров событий с помощью AzureEventSourceListener.

Клиентская библиотека Центров событий также инструментируется для распределенной трассировки с помощью Application Insights или OpenTelemetry. Дополнительные сведения см. в примере диагностики Azure.Core.

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

Помимо вводных сценариев, клиентская библиотека Центры событий Azure предлагает поддержку дополнительных сценариев, которые помогут воспользоваться полным набором функций службы Центры событий Azure. Чтобы изучить некоторые из этих сценариев, клиентская библиотека Центров событий предлагает проект примеров, которые будут служить иллюстрацией для распространенных сценариев. Дополнительные сведения см. в примерах сведений .

Участие

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

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

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

Дополнительные сведения см. в нашем руководстве по участию .

Просмотры