Руководство по использованию пакета SDK для веб-заданий Azure для фоновой управляемой событиями обработки

  • Статья

Приступите к работе с пакетом SDK для веб-заданий Azure и Службой приложений Azure, чтобы предоставить веб-приложениям возможность выполнять фоновые и запланированные задачи, а также реагировать на события.

Используйте Visual Studio 2022, чтобы создать консольное приложение .NET Core, использующее пакет SDK для веб-заданий для реагирования на сообщения очереди службы хранилища Azure, а также чтобы запустить проект локально и развернуть его в Azure.

В этом учебнике рассматривается следующее.

  • Создание консольного приложения
  • Добавление функции
  • Локальное тестирование
  • Развернуть в Azure
  • Включение ведения журнала Application Insights.
  • Добавление привязок ввода-вывода.

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

Создание консольного приложения

Этот раздел начинается с создания проекта в Visual Studio 2022. Далее предстоит добавить инструменты для разработки Azure, публикации кода и функций, которые прослушивают триггеры, и для вызова этих функций. Наконец, вы настроите ведение журнала в консоли, что приведет к отключению устаревшего средства мониторинга и позволит использовать поставщик консоли с фильтрацией по умолчанию.

Примечание

Процедуры, описанные в этой статье, проверены путем создания консольного приложения .NET Core, которое работает на базе .NET 6.0.

Создание проекта

  1. В Visual Studio выберите Файл>Создать>Проект.

  2. В окне Создание проекта выберите Консольное приложение (C#) и нажмите кнопку Далее.

  3. В окне Настроить новый проект введите имя проекта WebJobsSDKSample и нажмите кнопку Далее.

  4. Выберите значение параметра Целевая платформа и нажмите кнопку Далее. Это руководство было проверено с использованием .NET 6.0.

Установка пакетов NuGet для веб-заданий

Установите последний пакет NuGet для веб-заданий. Этот пакет включает в себя Microsoft.Azure.WebJobs (пакет SDK для веб-заданий), который позволяет публиковать код функции в веб-заданиях в Службе приложений Azure.

  1. Получите последнюю стабильную версию 4.х пакета NuGet Microsoft.Azure.WebJobs.Extensions.

  2. В Visual Studio выберите Инструменты>Диспетчер пакетов NuGet.

  3. Щелкните Консоль диспетчера пакетов. Вы увидите список командлетов NuGet, ссылку на документацию и точку входа PM>.

  4. В следующей команде замените <4_X_VERSION> номером текущей версии, полученной на шаге 1.

    Install-Package Microsoft.Azure.WebJobs.Extensions -version <4_X_VERSION>

  5. Выполните команду в консоли диспетчера пакетов. Появится список расширений, которые будут установлены автоматически.

Создание узла

Узел представляет собой контейнер среды выполнения для функций, который ожидает сигналов от триггеров и вызывает функции. Следующий код создает узел, который реализует IHost, универсальный узел для ASP.NET Core.

  1. Выберите вкладку Program.cs, удалите существующее содержимое и добавьте следующие инструкции using:

    using System.Threading.Tasks;
using Microsoft.Extensions.Hosting;

  2. Также на вкладке Program.cs добавьте следующий код:

    namespace WebJobsSDKSample
{
    class Program
    {
        static async Task Main()
        {
            var builder = new HostBuilder();
            builder.ConfigureWebJobs(b =>
            {
                b.AddAzureStorageCoreServices();
            });
            var host = builder.Build();
            using (host)
            {
                await host.RunAsync();
            }
        }
    }
}

В ASP.NET Core конфигурации узла настраиваются путем вызова методов в экземпляре HostBuilder. Дополнительные сведения можно найти в статье Универсальный узел .NET. Метод расширения ConfigureWebJobs инициализирует узел веб-заданий. В ConfigureWebJobs инициализируйте определенные расширения привязок, например расширение привязки к службе хранилища, и задайте свойства этих расширений.

Включение журналирования консоли

Настройте ведение журнала консоли с использованием платформы ведения журналов для ASP.NET Core. Эта платформа, Microsoft.Extensions.Logging, включает в себя API, который работает с различными встроенными и сторонними поставщиками ведения журнала.

  1. Получите последнюю стабильную версию пакета NuGet Microsoft.Extensions.Logging.Console, которая включает в себя Microsoft.Extensions.Logging.

  2. В следующей команде замените <6_X_VERSION> номером текущей версии, полученной на шаге 1. Каждый тип пакета NuGet имеет уникальный номер версии.

    Install-Package Microsoft.Extensions.Logging.Console -version <6_X_VERSION>

  3. В консоли диспетчера пакетов введите номер текущей версии и выполните приведенную команду. Появится список расширений, которые будут установлены автоматически.

  4. На вкладке Program.cs добавьте следующую инструкцию using:

    using Microsoft.Extensions.Logging;

  5. На той же вкладке Program.cs добавьте метод ConfigureLogging в HostBuilder перед командой Build. Метод AddConsole добавляет в конфигурацию ведение журнала консоли.

    builder.ConfigureLogging((context, b) =>
{
    b.AddConsole();
});

    Метод Main теперь выглядит следующим образом:

    static async Task Main()
{
    var builder = new HostBuilder();
    builder.ConfigureWebJobs(b =>
            {
                b.AddAzureStorageCoreServices();
            });
    builder.ConfigureLogging((context, b) =>
            {
                b.AddConsole();
            });
    var host = builder.Build();
    using (host)
    {
        await host.RunAsync();
    }
}

    Он также приводит к следующим изменениям.

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

Теперь можно добавить функцию, которая активируется сообщениями из очереди службы хранилища Azure.

Добавление функции

Функция — это единица кода, которая выполняется по расписанию, активируется событиями или выполняется по запросу. Триггер ожидает передачи события службы. В контексте пакета SDK для веб-заданий активация триггера не относится к режиму развертывания. Управляемые событиями или запланированные веб-задания, созданные с помощью пакета SDK, всегда должны развертываться как непрерывные веб-задания в режиме Always on.

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

Установка расширения привязки Службы хранилища

Начиная с версии 3 пакета SDK для веб-заданий, для подключения к службам службы хранилища Azure необходимо установить отдельный пакет расширения привязки к службе хранилища.

Примечание

Начиная с версии 5.x, хранилище Microsoft.Azure.WebJobs.Extensions.Storage разделено по службам хранилища, и метод расширения AddAzureStorage() перенесен по типу службы.

  1. Получите последнюю стабильную версию пакета NuGet Microsoft.Azure.WebJobs.Extensions.Storage. Это версия 5.х.

  2. В следующей команде замените <5_X_VERSION> номером текущей версии, полученной на шаге 1. Каждый тип пакета NuGet имеет уникальный номер версии.

    Install-Package Microsoft.Azure.WebJobs.Extensions.Storage -Version <5_X_VERSION>

  3. В консоли диспетчера пакетов выполните приведенную команду, указав номер текущей версии в точке входа PM>.

  4. На вкладке Program.cs в метод расширения ConfigureWebJobs в экземпляр HostBuilder добавьте метод AddAzureStorageQueues (перед командой Build) для инициализации расширения службы хранилища. На этом этапе метод ConfigureWebJobs выглядит следующим образом:

    builder.ConfigureWebJobs(b =>
{
    b.AddAzureStorageCoreServices();
    b.AddAzureStorageQueues();
});

  5. Добавьте приведенный ниже код в метод Main после создания экземпляра builder:

    builder.UseEnvironment(EnvironmentName.Development);

    Выполнение в режиме разработки сокращает экспоненциальную задержку опроса очереди, которая может значительно увеличить время, затрачиваемое средой выполнения на поиск сообщения и вызов функции. Удалите эту строку кода или переключитесь в режим Production, когда завершите разработку и тестирование.

    Теперь метод Main должен выглядеть следующим образом:

    static async Task Main()
{
    var builder = new HostBuilder();
    builder.UseEnvironment(EnvironmentName.Development);
    builder.ConfigureLogging((context, b) =>
    {
        b.AddConsole();
    });
    builder.ConfigureWebJobs(b =>
    {
        b.AddAzureStorageCoreServices();
        b.AddAzureStorageQueues();
    });
    var host = builder.Build();
    using (host)
    {
        await host.RunAsync();
    }
}

Создание функции, активируемой очередью

Атрибут QueueTrigger вызывает в среде выполнения эту функцию при записи нового сообщения в очередь службы хранилища Azure с именем queue. Содержимое сообщения в очереди передается коду метода в параметре message. Тело метода реализуется при обработке данных триггера. В этом примере код просто записывает сообщение в журнал.

  1. В Обозревателе решений щелкните правой кнопкой мыши проект, а затем выберите Добавить>Новый элемент и щелкните Класс.

  2. Щелкните правой кнопкой мыши новый файл класса C# Functions.cs и выберите Добавить.

  3. В файле Functions.cs замените созданный шаблон следующим кодом:

    using Microsoft.Azure.WebJobs;
using Microsoft.Extensions.Logging;

namespace WebJobsSDKSample
{
    public class Functions
    {
        public static void ProcessQueueMessage([QueueTrigger("queue")] string message, ILogger logger)
        {
            logger.LogInformation(message);
        }
    }
}

    Класс Functions нужно пометить как public static, чтобы метод был доступен для среды выполнения. В приведенном выше примере кода при добавлении сообщения в очередь queue функция выполняется и строка message записывается в журналы. Отслеживаемая очередь находится в учетной записи хранения Azure по умолчанию, которая будет создана далее.

Параметр message не должен быть строкой. Также можно выполнить привязку к объекту JSON, массиву байтов или CloudQueueMessage. См. "Использование триггера очереди". Каждый тип привязки (например, очереди, BLOB-объекты или таблицы) обладает своим набором типов параметров привязки.

Создание учетной записи хранения Azure

Эмулятор хранения Azure, который работает локально, не обладает всеми возможностями, необходимыми пакету SDK WebJobs. Вы создадите учетную запись хранения в Azure и настроите ее использование в проекте.

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

Поиск и копирование строки подключения

Для настройки хранилища требуется строка подключения. Сохраните эту строку подключения для выполнения следующих шагов.

  1. Войдите на портал Azure, перейдите к своей учетной записи хранения и выберите Параметры.

  2. В разделе Параметры выберите Ключи доступа.

  3. В разделе Строка подключения для записи key1 щелкните значок Копировать в буфер обмена.

    ключ

Настройка хранилища для локального запуска

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

  1. Щелкните проект правой кнопкой мыши, выберите Добавить>Новый элемент… , выберите Файл конфигурации JSON JavaScript, присвойте новому файлу имя appsettings.json и щелкните Добавить.

  2. В новом файле добавьте поле AzureWebJobsStorage, как показано в следующем примере:

    {
    "AzureWebJobsStorage": "{storage connection string}"
}

  3. Замените значение {storage connection string} строкой подключения, скопированной ранее.

  4. Выберите файл appsettings.json в Обозревателе решений и в окне Свойства установите для действия Копировать в выходной каталог значение Копировать более позднюю версию.

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

Локальное тестирование

Выполните сборку и запустите проект локально. Создайте очередь сообщений для активации функции.

  1. На портале Azure перейдите к учетной записи хранения и выберите вкладку Очереди (1). Щелкните + Очередь (2) и введите queue в качестве имени очереди (3). Нажмите кнопку ОК (4).

    На этом рисунке показано, как создать новую очередь службы хранилища Azure.

  2. Щелкните новую очередь и выберите Добавить сообщение.

  3. В диалоговом окне Добавление сообщения введите Hello World! в качестве текста сообщения и нажмите кнопку ОК. В очереди есть новое сообщение.

    Создание очереди

  4. Нажмите клавиши CTRL+F5, чтобы запустить проект.

    В консоли показано, что среда выполнения обнаружила вашу функцию. Так как в функции ProcessQueueMessage использовался атрибут QueueTrigger, среда выполнения пакета веб-заданий ожидает передачи сообщений в очередь queue. При обнаружении нового сообщения в этой очереди среда выполнения вызывает функцию, передавая ей значение строки сообщения.

  5. Вернитесь к окну Очередь и обновите страницу. Сообщение исчезнет, так как оно уже обработано функцией, выполняемой локально.

  6. Закройте окно консоли.

Теперь пора опубликовать проект пакета SDK для веб-заданий в Azure.

Развернуть в Azure

В процессе развертывания создается экземпляр службы приложений, в котором будут выполняться ваши функции. При публикации консольного приложения .NET в Службе приложений Azure оно автоматически запускается как веб-задание. Дополнительные сведения о публикации см. в статье Разработка и развертывание веб-заданий с помощью Visual Studio.

Создание ресурсов Azure

  1. Щелкните правой кнопкой мыши проект в обозревателе решений и выберите пункт Опубликовать.

  2. В диалоговом окне Публикация выберите Azure в качестве параметра Целевой объект, а затем нажмите Далее.

  3. Выберите Веб-задания Azure в качестве параметра Указанный целевой объект, а затем нажмите Далее.

  4. Над элементом App Service instances (Экземпляры Службы приложений) нажмите кнопку со знаком плюс ( + ), чтобы открыть окно Create a new Azure WebJob (Создание веб-задания Azure).

  5. В диалоговом окне Служба приложений (Windows) задайте параметры размещения, которые указаны в следующей таблице.

    Параметр Рекомендуемое значение Описание
    имя; Глобально уникальное имя Имя, которое однозначно идентифицирует новое приложение-функцию.
    Подписка Выберите свою подписку Подписка Azure, которую нужно использовать.
    Группа ресурсов myResourceGroup Имя группы ресурсов, в которой будет создано приложение-функция. Чтобы создать группу ресурсов, выберите Создать.
    План размещения План службы приложений План службы приложений указывает расположение, размер и функции фермы веб-серверов, в которой размещается приложение. Вы можете сэкономить средства при размещении нескольких приложений, настроив совместное использование одного плана службы приложений в веб-приложениях. Планы службы приложений определяют регион, размер экземпляра, степень масштабирования и SKU ("Бесплатный", "Общий", "Базовый", "Стандартный" или "Премиум"). Выберите Создать, чтобы создать новый план службы приложений Уровни "Бесплатный" и "Базовый" не поддерживают функцию Always On, чтобы обеспечить непрерывную работу сайта.

    Диалоговое окно

  6. Выберите Создать, чтобы создать веб-задание и связанные с ним ресурсы в Azure с заданными параметрами, а также развернуть код проекта.

  7. Чтобы вернуться на страницу Публикация, выберите Готово.

Включение решения Always On

Для непрерывного веб-задания на сайте следует включить параметр Always on, чтобы ваши веб-задания выполнялись правильно. Если не включить режим Always on, среда выполнения будет переходить в состояние простоя после нескольких минут бездействия.

  1. На странице Публикация щелкните троеточие над элементом Размещение, чтобы отобразить действия раздела в профиле размещения, и выберите Открыть на портале Azure.

  2. В окне Параметры выберите Конфигурация>Общие настройки, задайте для параметра Always on значение Включено, после чего щелкните Сохранить и Продолжить, чтобы перезапустить сайт.

Публикация проекта

Теперь пора опубликовать проект веб-заданий с помощью веб-приложения, созданного в Azure.

  1. На странице Публикация в разделе Размещение нажмите кнопку "Изменить" и измените Тип веб-задания на Continuous, затем нажмите кнопку Сохранить. Это гарантирует, что веб-задание будет выполняться при добавлении сообщений в очередь. Активируемые веб-задания обычно используются только для ручных веб-перехватчиков.

    Измените тип веб-задания в окне публикации VS 2022.

  2. Нажмите кнопку Опубликовать в правом верхнем углу страницы Публикация. По завершении операции веб-задание будет выполняться в Azure.

Создание параметра приложения для подключения к хранилищу

Необходимо создать такой же параметр строки подключения к хранилищу в Azure, какой вы использовали локально в файле конфигурации appsettings.js. Это позволит более безопасно хранить строку подключения.

  1. На странице Публикация профиля щелкните троеточие над элементом Размещение, чтобы отобразить действия раздела в профиле размещения, и выберите Изменить параметры Службы приложений Azure.

  2. В разделе Параметры приложения выберите Добавить параметр.

  3. В окне Имя нового параметра приложения введите AzureWebJobsStorage и нажмите кнопку ОК.

  4. В поле Удаленный вставьте строку подключения из локального параметра и нажмите кнопку ОК.

Теперь строка подключения задана в приложении в Azure.

Активация функции в Azure

  1. Убедитесь, что приложение не выполняется локально. Закройте окно консоли, если оно все еще открыто. В противном случае локальный экземпляр может первым начать обрабатывать создаваемые вами сообщения в очереди.

  2. На странице Очередь в Visual Studio добавьте сообщение в очередь, как и раньше.

  3. Обновите страницу Очередь, после чего новое сообщение исчезнет, так как оно было обработано с помощью функции, работающей в Azure.

Включение ведения журнала Application Insights

При выполнении веб-здания в Azure невозможно отслеживать выполнение функции, просматривая выходные данные консоли. Чтобы иметь возможность отслеживать веб-задание, при публикации проекта следует создать связанный экземпляр Application Insights.

Создание экземпляра Application Insights

  1. На странице Публикация профиля щелкните троеточие над элементом Размещение, чтобы отобразить действия раздела в профиле размещения, и выберите Открыть на портале Azure.

  2. В веб-приложении в разделе Параметры выберите Application Insights и щелкните Включить Application Insights.

  3. Проверьте созданное имя ресурса для экземпляра и расположение, а затем нажмите кнопку Применить.

  4. В разделе Параметры выберите Конфигурация. Убедитесь, что создан новый ключ APPINSIGHTS_INSTRUMENTATIONKEY. Этот ключ используется для подключения экземпляра веб-задания к Application Insights.

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

Установите расширение Application Insights

  1. Получите последнюю стабильную версию пакета NuGet Microsoft.Azure.WebJobs.Logging.ApplicationInsights. Это версия 3.х.

  2. В следующей команде замените <3_X_VERSION> номером текущей версии, полученной на шаге 1. Каждый тип пакета NuGet имеет уникальный номер версии.

    Install-Package Microsoft.Azure.WebJobs.Logging.ApplicationInsights -Version <3_X_VERSION>

  3. В консоли диспетчера пакетов выполните приведенную команду, указав номер текущей версии в точке входа PM>.

Инициализация поставщика журнала Application Insights

Откройте файл Program.cs и добавьте приведенный ниже инициализатор в ConfigureLogging после вызова AddConsole:

// If the key exists in settings, use it to enable Application Insights.
string instrumentationKey = context.Configuration["APPINSIGHTS_INSTRUMENTATIONKEY"];
if (!string.IsNullOrEmpty(instrumentationKey))
{
    b.AddApplicationInsightsWebJobs(o => o.InstrumentationKey = instrumentationKey);
}

Теперь код метода Main должен выглядеть следующим образом:

static async Task Main()
{
    var builder = new HostBuilder();
    builder.UseEnvironment(EnvironmentName.Development);
    builder.ConfigureWebJobs(b =>
            {
                b.AddAzureStorageCoreServices();
                b.AddAzureStorage();
            });
    builder.ConfigureLogging((context, b) =>
            {
                b.AddConsole();

                // If the key exists in settings, use it to enable Application Insights.
                string instrumentationKey = context.Configuration["APPINSIGHTS_INSTRUMENTATIONKEY"];
                if (!string.IsNullOrEmpty(instrumentationKey))
                {
                    b.AddApplicationInsightsWebJobs(o => o.InstrumentationKey = instrumentationKey);
                }
            });
    var host = builder.Build();
    using (host)
    {
        await host.RunAsync();
    }
}

Это действие позволит инициализировать поставщик журнала Application Insights с фильтрацией по умолчанию. При локальном выполнении вся информация и журналы более высокого уровня выводятся как в консоль, так и в Application Insights.

Повторная публикация проекта и активация функции

  1. Щелкните правой кнопкой мыши проект в обозревателе решений и выберите пункт Опубликовать.

  2. Используйте портал Azure для создания сообщения очереди, как это было сделано ранее, но в качестве текста сообщения введите Hello App Insights!.

  3. На странице Публикация профиля щелкните троеточие над элементом Размещение, чтобы отобразить действия раздела в профиле размещения, и выберите Открыть на портале Azure.

  4. В веб-приложении в разделе Параметры выберите Application Insights и щелкните Просмотреть данные Application Insights.

  5. Выберите Поиск, а затем выберите See all data in the last 24 hours (Просмотреть все данные за последние 24 часа).

    Выбор команды

  6. Если вы не видите сообщение Hello App Insights!, выберите периодическое обновление в течение нескольких минут. (Журналы не появляются немедленно, так как клиенту Application Insights требуется некоторое время на запись обрабатываемых журналов на диск.)

    Журналы в Application Insights

Добавление привязок ввода-вывода.

Привязки упрощают код для чтения и записи данных. Привязка входных данных упрощает код чтения данных. Привязки выходных данных упрощают код записи данных.

Добавление привязок

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

  1. В Functions.cs добавьте using:

    using System.IO;

  2. Замените метод ProcessQueueMessage следующим кодом:

    public static void ProcessQueueMessage(
    [QueueTrigger("queue")] string message,
    [Blob("container/{queueTrigger}", FileAccess.Read)] Stream myBlob,
    [Blob("container/copy-{queueTrigger}", FileAccess.Write)] Stream outputBlob,
    ILogger logger)
{
    logger.LogInformation($"Blob name:{message} \n Size: {myBlob.Length} bytes");
    myBlob.CopyTo(outputBlob);
}

    В этом коде queueTrigger — это выражение привязки, что означает, что его значение определяется во время выполнения. Во время выполнения оно содержит сообщение в очереди.

    Этот код использует выходные привязки для создания копии файла, определенного сообщением очереди. Копия файла имеет префикс copy-.

  3. На вкладке Program.cs в метод расширения ConfigureWebJobs добавьте метод AddAzureStorageBlobs для экземпляра HostBuilder (перед командой Build), чтобы инициализировать расширение службы хранилища. На этом этапе метод ConfigureWebJobs выглядит следующим образом:

    builder.ConfigureWebJobs(b =>
{
    b.AddAzureStorageCoreServices();
    b.AddAzureStorageQueues();
    b.AddAzureStorageBlobs();
});

  4. Создайте контейнер BLOB-объектов в учетной записи хранения.

    а. На портале Azure перейдите на вкладку Контейнеры в разделе Хранилище данных и выберите + Контейнер.

    b. В диалоговом окне Создать контейнер для имени контейнера введите container, а затем нажмите кнопку Создать.

  5. Отправьте файл Program.cs в контейнер больших двоичных объектов. (Этот файл используется здесь для примера; вы можете передать любой текстовый файл и создавать сообщение в очереди с его именем.)

    а. Выберите созданный контейнер.

    b. Нажмите кнопку Отправить.

    Кнопка отправки BLOB-объекта

    c. Найдите и выберите файл Program.cs, а затем нажмите кнопку OK.

Повторная публикация проекта

  1. Щелкните правой кнопкой мыши проект в обозревателе решений и выберите пункт Опубликовать.

  2. В диалоговом окне Публикация убедитесь, что выбран текущий профиль, а затем щелкните Опубликовать. Подробные результаты публикации выводятся в окно Вывод.

  3. Создайте сообщение в ранее созданной очереди с Program.cs в качестве текста сообщения.

    Сообщение в очереди на основе сценария Program.cs

  4. Копия файла (copy-Program.cs) появится в контейнере BLOB-объектов.

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

В этом руководстве описано, как создать, запустить и развернуть проект пакета SDK для веб-заданий версии 3.x.

Подробнее о пакете SDK веб-заданий