Перенос приложений C# из внутрипроцессной модели в изолированную рабочую модель

В этой статье описывается процесс безопасной миграции приложения-функции .NET из модели in-process в модель изолированная рабочая модель. Для получения сведений о различиях на высоком уровне между этими моделями см. сравнение режимов выполнения.

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

• Мигрировать приложения из Функции Azure версии 2.x и 3.x на версию 4.x
• Перенос приложений из Функции Azure версии 1.x на версию 4.x

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

Определение приложений Azure Functions для миграции

Используйте следующий скрипт Azure PowerShell для создания списка приложений-функций в подписке, которые в настоящее время используют модель внутрипроцессного процесса.

Скрипт использует подписку, на которую в настоящее время настроен Azure PowerShell. Вы можете изменить подписку, сначала запустив Set-AzContext -Subscription '<YOUR SUBSCRIPTION ID>' и заменив <YOUR SUBSCRIPTION ID> идентификатором подписки, которую вы хотите оценить.

$FunctionApps = Get-AzFunctionApp

$AppInfo = @{}

foreach ($App in $FunctionApps)
{
     if ($App.Runtime -eq 'dotnet')
     {
          $AppInfo.Add($App.Name, $App.Runtime)
     }
}

$AppInfo

Выбор целевой версии .NET

В среде выполнения функций версии 4.x приложение-функция .NET нацелено на .NET 6 или .NET 8 при использовании внутрипроцессной модели.

При переносе приложения-функции у вас есть возможность выбрать целевую версию .NET. Проект C# можно обновить до одной из следующих версий .NET, поддерживаемых функциями версии 4.x:

¹ Модель изолированного работника поддерживает версии с долгосрочной поддержкой (LTS) и стандартной поддержкой (STS) .NET, а также .NET Framework. Модель in-process поддерживает только выпуски LTS .NET, заканчивающиеся .NET 8. Полное сравнение возможностей и функциональности двух моделей см. в разделе Различия между внутрипроцессными и изолированными рабочими процессами .NET Функции Azure.

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

³ Ранее ожидалось, что поддержка .NET 9 завершится 12 мая 2026 года. В течение периода обслуживания .NET 9 команда .NET расширила поддержку версий STS до 24 месяцев, начиная с версии .NET 9. Дополнительные сведения см. в записи блога.

В этом руководстве нет конкретных примеров для .NET 10 или .NET 9. Если вам нужно ориентировать одну из этих версий, можно адаптировать примеры для .NET 8.

Подготовка к переносу

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

Чтобы перенести приложение, выполните следующие действия.

1. Перенесите локальный проект в изолированную рабочую модель, выполнив действия, описанные в разделе "Миграция локального проекта".
2. После переноса проекта полностью протестируйте приложение локально с помощью версии 4.x Функции Azure Core Tools.
3. Обновите ваше приложение-функцию в Azure до изолированной модели.

Перенос локального проекта

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

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

проектный файл

В следующем примере представлен файл проекта .csproj, использующий .NET 8 в версии 4.x:

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net8.0</TargetFramework>
    <AzureFunctionsVersion>v4</AzureFunctionsVersion>
    <RootNamespace>My.Namespace</RootNamespace>
  </PropertyGroup>
  <ItemGroup>
    <PackageReference Include="Microsoft.NET.Sdk.Functions" Version="4.1.1" />
  </ItemGroup>
  <ItemGroup>
    <None Update="host.json">
      <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
    </None>
    <None Update="local.settings.json">
      <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
      <CopyToPublishDirectory>Never</CopyToPublishDirectory>
    </None>
  </ItemGroup>
</Project>

Используйте одну из следующих процедур, чтобы обновить этот XML-файл для запуска в изолированной рабочей модели:

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net8.0</TargetFramework>
    <AzureFunctionsVersion>v4</AzureFunctionsVersion>
    <RootNamespace>My.Namespace</RootNamespace>
    <OutputType>Exe</OutputType>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
  </PropertyGroup>
  <ItemGroup>
    <FrameworkReference Include="Microsoft.AspNetCore.App" />
    <PackageReference Include="Microsoft.Azure.Functions.Worker" Version="1.21.0" />
    <PackageReference Include="Microsoft.Azure.Functions.Worker.Sdk" Version="1.17.2" />
    <PackageReference Include="Microsoft.Azure.Functions.Worker.Extensions.Http.AspNetCore" Version="1.2.1" />
    <PackageReference Include="Microsoft.ApplicationInsights.WorkerService" Version="2.22.0" />
    <PackageReference Include="Microsoft.Azure.Functions.Worker.ApplicationInsights" Version="1.2.0" />
    <!-- Other packages may also be in this list -->
  </ItemGroup>
  <ItemGroup>
    <None Update="host.json">
      <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
    </None>
    <None Update="local.settings.json">
      <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
      <CopyToPublishDirectory>Never</CopyToPublishDirectory>
    </None>
  </ItemGroup>
  <ItemGroup>
    <Using Include="System.Threading.ExecutionContext" Alias="ExecutionContext"/>
  </ItemGroup>
</Project>

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net48</TargetFramework>
    <AzureFunctionsVersion>v4</AzureFunctionsVersion>
    <RootNamespace>My.Namespace</RootNamespace>
    <OutputType>Exe</OutputType>
  </PropertyGroup>
  <ItemGroup>
      <PackageReference Include="Microsoft.Azure.Functions.Worker" Version="1.21.0" />
      <PackageReference Include="Microsoft.Azure.Functions.Worker.Sdk" Version="1.16.4" />
      <PackageReference Include="Microsoft.Azure.Functions.Worker.Extensions.Http" Version="3.1.0" />
      <PackageReference Include="Microsoft.ApplicationInsights.WorkerService" Version="2.22.0" />
      <PackageReference Include="Microsoft.Azure.Functions.Worker.ApplicationInsights" Version="1.2.0" />
    <!-- Other packages may also be in this list -->
  </ItemGroup>
  <ItemGroup>
    <None Update="host.json">
      <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
    </None>
    <None Update="local.settings.json">
      <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
      <CopyToPublishDirectory>Never</CopyToPublishDirectory>
    </None>
  </ItemGroup>
  <ItemGroup>
    <Folder Include="Properties\" />
  </ItemGroup>
</Project>

Изменение целевой платформы проекта также может потребовать изменений в частях цепочки инструментов за пределами кода проекта. Например, в VS Code может потребоваться обновить azureFunctions.deploySubpath параметр расширения с помощью параметров пользователя или vscode/settings.json файла проекта. Проверьте наличие зависимостей от версии платформы, которая может существовать вне кода проекта, как часть шагов сборки или конвейера CI/CD.

Ссылки на пакеты

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

Если вы еще не сделали этого, обновите проект, чтобы ссылаться на последние стабильные версии:

• Майкрософт.Azure. Functions.Worker
• Майкрософт.Azure. Functions.Worker.Sdk

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

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

Приложение изолированной рабочей модели не должно ссылаться на пакеты в пространствах имен Майкрософт.Azure.WebJobs.* или Майкрософт.Azure.Functions.Extensions. Если у вас есть оставшиеся ссылки на них, их следует удалить.

файл Program.cs

При миграции на выполнение в изолированном рабочем процессе необходимо добавить в проект файл Program.cs со следующим содержимым:

using Microsoft.Azure.Functions.Worker;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;

var host = new HostBuilder()
    .ConfigureFunctionsWebApplication()
    .ConfigureServices(services => {
        services.AddApplicationInsightsTelemetryWorkerService();
        services.ConfigureFunctionsApplicationInsights();
    })
    .Build();

host.Run();

using Microsoft.Extensions.Hosting;
using Microsoft.Azure.Functions.Worker;

namespace Company.FunctionApp
{
    internal class Program
    {
        static void Main(string[] args)
        {
            FunctionsDebugger.Enable();

            var host = new HostBuilder()
                .ConfigureFunctionsWorkerDefaults()
                .ConfigureServices(services => {
                    services.AddApplicationInsightsTelemetryWorkerService();
                    services.ConfigureFunctionsApplicationInsights();
                })
                .Build();
            host.Run();
        }
    }
}

Файл Program.cs заменяет любой файл с FunctionsStartup атрибутом, который обычно является файлом Startup.cs. В местах, где ваш код FunctionsStartup будет ссылаться на IFunctionsHostBuilder.Services, можно вместо этого добавить инструкции в метод .ConfigureServices() класса HostBuilder в вашем файле Program.cs. Дополнительные сведения о работе с Program.cs см. в руководстве по запуску и настройке в изолированной рабочей модели.

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

Хотя вы можете зарегистрировать пользовательские источники конфигурации в рамках HostBuilderпрограммы, они аналогично применяются только к коду в проекте. Платформа также нуждается в настройке триггера и привязки, и это следует предоставлять с помощью параметров приложения, ссылок на Key Vault или ссылок на App Configuration.

После того как вы переместите все из любых существующих FunctionsStartup в файл Program.cs, можно удалить атрибут FunctionsStartup и класс, к которому он был применён.

Изменения подписи функции

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

• Атрибут функции, который также задает имя функции
• Как функция получает ILogger/ILogger<T>
• Атрибуты и параметры триггера и привязки

В остальной части этого раздела показано, как выполнить все эти действия.

Атрибуты функций

Атрибут Function в изолированной рабочей модели заменяет FunctionName атрибут. Новый атрибут имеет ту же сигнатуру, и единственное различие в имени. Поэтому вы можете просто выполнить замену строки в проекте.

Ведение журнала

В модели внутрипроцессного процесса можно включить необязательный ILogger параметр для функции или использовать внедрение зависимостей для получения ILogger<T>. Если приложение уже использовало внедрение зависимостей, то те же механизмы работают в изолированной рабочей модели.

Однако для любых функций, зависящих от ILogger параметра метода, необходимо внести изменения. Мы рекомендуем использовать внедрение зависимостей для получения ILogger<T>. Чтобы перенести механизм ведения журнала функции, выполните следующие действия.

1. В классе функции добавьте свойство private readonly ILogger<MyFunction> _logger;, заменив MyFunction на имя вашего класса функции.

2. Создайте конструктор для класса-функции, который принимает ILogger<T> в качестве параметра.

   public MyFunction(ILogger<MyFunction> logger) {
       _logger = logger;
   }
   

   Замените оба экземпляра MyFunction в предыдущем фрагменте кода именем класса функции.

3. Для операций ведения журнала в коде функции замените ссылки на параметр ILogger параметром _logger.

4. ILogger Удалите параметр из подписи функции.

Дополнительные сведения см. в разделе "Ведение журнала" в изолированной рабочей модели.

Изменения триггера и привязки

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

1. Удалите все инструкции using Майкрософт.Azure.WebJobs;.

2. Добавьте инструкцию using Майкрософт.Azure.Functions.Worker;.

3. Для каждого атрибута привязки измените имя атрибута, как указано в справочной документации, которую можно найти в индексе поддерживаемых привязок . Как правило, имена атрибутов изменяются следующим образом:

   • Триггеры обычно остаются именованными так же. Например, QueueTrigger это имя атрибута для обеих моделей.
   • Входные привязки обычно требуют Input добавления в их имя. Например, если в модели внутрипроцессной модели использовался атрибут входной CosmosDB привязки, атрибут теперь будет иметь значение CosmosDBInput.
   • Выходные привязки обычно требуют добавления Output к их имени. Например, если в модели внутрипроцессной модели использовался атрибут выходной Queue привязки, теперь этот атрибут будет иметь значение QueueOutput.

4. Обновите параметры атрибута, чтобы отразить изолированную версию рабочей модели, как указано в справочной документации привязки.

   Например, в внутрипроцессной модели выходная привязка BLOB представлена атрибутом [Blob(...)], который включает свойство Access. В модели изолированного рабочего объект Blob будет выходным атрибутом [BlobOutput(...)]. Привязка больше не требует Access свойства, чтобы этот параметр можно было удалить. Так [Blob("sample-images-sm/{fileName}", FileAccess.Write, Connection = "MyStorageConnection")] стало бы [BlobOutput("sample-images-sm/{fileName}", Connection = "MyStorageConnection")].

5. Перемещение выходных привязок из списка параметров функции. Если у вас есть только одна выходная привязка, это можно применить к типу возвращаемой функции. Если у вас несколько выходных данных, создайте новый класс со свойствами для каждого вывода и примените атрибуты к этим свойствам. Дополнительные сведения см. в разделе "Несколько выходных привязок".

6. Ознакомьтесь со справочной документацией по каждой привязке для типов, к которых можно привязаться. В некоторых случаях может потребоваться изменить тип. Для выходных привязок, если используется IAsyncCollector<T>версия модели в процессе, ее можно заменить привязкой к массиву целевого типа: T[] Вы также можете заменить выходную привязку клиентским объектом для службы, которую он представляет, либо использовать его в качестве типа для входной привязки, если это доступно, либо внедрить клиента самостоятельно.

7. Если функция содержит IBinder параметр, удалите его. Замените функциональность клиентским объектом службы, который он представляет, либо как тип привязки для входной привязки, если он доступен, либо путем внедрения клиента самостоятельно.

8. Обновите код функции, чтобы работать с любыми новыми типами.

файл local.settings.json

Файл local.settings.json используется только при локальном запуске. Дополнительные сведения см. в файле локальных параметров.

При переходе от выполнения процесса в том же пространстве к выполнению в изолированном рабочем процессе, необходимо изменить значение FUNCTIONS_WORKER_RUNTIME на dotnet-isolated. Убедитесь, что файлlocal.settings.json содержит по крайней мере следующие элементы:

{
    "IsEncrypted": false,
    "Values": {
        "AzureWebJobsStorage": "UseDevelopmentStorage=true",
        "FUNCTIONS_WORKER_RUNTIME": "dotnet-isolated"
    }
}

Значение, которое AzureWebJobsStorage вы хотите использовать, может отличаться. Изменить его значение в рамках миграции не нужно.

файл host.json

Изменения в файлеhost.json не требуются. Однако если конфигурация Application Insights находится в этом файле из проекта модели в процессе, может потребоваться внести дополнительные изменения в файл Program.cs . Файлhost.json управляет ведением журнала только из среды выполнения узла функций и в изолированной рабочей модели некоторые из этих журналов приходят непосредственно из приложения, что дает вам больше контроля. Дополнительные сведения об фильтрации этих журналов см. в статье "Управление уровнями журналов в изолированной рабочей модели ".

Другие изменения кода

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

Сериализация JSON

По умолчанию изолированная рабочая модель использует System.Text.Json для сериализации JSON. Чтобы настроить параметры сериализатора или переключиться на JSON.NET (Newtonsoft.Json), см. статью Customization JSON serialization.

Уровни журналов Application Insights и фильтрация

Журналы можно отправлять в Application Insights как из среды выполнения функций, так и из кода вашего проекта. host.json позволяет настраивать правила ведения журнала узлов, но управлять журналами, поступающими из кода, необходимо настроить правила фильтрации в рамках Program.cs. Дополнительные сведения об фильтрации этих журналов см. в статье "Управление уровнями журналов в изолированной рабочей модели ".

Примеры миграций функций

Пример триггера HTTP

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

using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Extensions.Http;
using Microsoft.Extensions.Logging;

namespace Company.Function
{
    public static class HttpTriggerCSharp
    {
        [FunctionName("HttpTriggerCSharp")]
        public static IActionResult Run(
            [HttpTrigger(AuthorizationLevel.Function, "get", Route = null)] HttpRequest req,
            ILogger log)
        {
            log.LogInformation("C# HTTP trigger function processed a request.");

            return new OkObjectResult($"Welcome to Azure Functions, {req.Query["name"]}!");
        }
    }
}

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

using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Azure.Functions.Worker;
using Microsoft.Extensions.Logging;

namespace Company.Function
{
    public class HttpTriggerCSharp(ILogger<HttpTriggerCSharp> logger)
    {
        [Function("HttpTriggerCSharp")]
        public IActionResult Run(
            [HttpTrigger(AuthorizationLevel.Function, "get")] HttpRequest req)
        {
            logger.LogInformation("C# HTTP trigger function processed a request.");

            return new OkObjectResult($"Welcome to Azure Functions, {req.Query["name"]}!");
        }
    }
}

using Microsoft.Azure.Functions.Worker;
using Microsoft.Azure.Functions.Worker.Http;
using Microsoft.Extensions.Logging;
using System.Net;

namespace Company.Function
{
    public class HttpTriggerCSharp(ILogger<HttpTriggerCSharp> logger)
    {
        [Function("HttpTriggerCSharp")]
        public HttpResponseData Run([HttpTrigger(AuthorizationLevel.Function, "get")] HttpRequestData req)
        {
            logger.LogInformation("C# HTTP trigger function processed a request.");

            var response = req.CreateResponse(HttpStatusCode.OK);
            response.Headers.Add("Content-Type", "text/plain; charset=utf-8");

            response.WriteString($"Welcome to Azure Functions, {req.Query["name"]}!");

            return response;
        }
    }
}

Обновление приложения-функции в Azure

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

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

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

2. Измените конфигурацию промежуточного (непроизводственного) слота, установив значение FUNCTIONS_WORKER_RUNTIME для параметра приложения dotnet-isolated, чтобы использовать изолированную модель рабочих процессов. FUNCTIONS_WORKER_RUNTIMEне следует помечать как параметр слота.

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

   Если у вас есть автоматизированное развертывание инфраструктуры, например, конвейер CI/CD, убедитесь, что автоматизация также актуализируется, чтобы FUNCTIONS_WORKER_RUNTIME оставался на значении dotnet-isolated и был нацелен на правильную версию .NET.

3. Опубликуйте перенесенный проект в промежуточный (непроизводный) слот приложения-функции.

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

4. Убедитесь, что приложение работает должным образом в промежуточном (непроизводивом) слоте.

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

6. Убедитесь, что приложение работает должным образом в рабочем слоте.

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

Следующий шаг