Migración de aplicaciones de la versión 1.x a la versión 4.x de Azure Functions

  • Artículo

Importante

Java no es compatible con la versión 1.x del tiempo de ejecución de Azure Functions. Quizás, en su lugar, quieres migrar la aplicación Java de la versión 3.x a la versión 4.x. Si vas a migrar una aplicación de funciones de la versión 1.x, selecciona C# o JavaScript anteriormente.

Importante

Typescript no es compatible con la versión 1.x del tiempo de ejecución de Azure Functions. Quizás, en su lugar, quieres migrar tu aplicación TypeScript de la versión 3.x a la versión 4.x. Si vas a migrar una aplicación de funciones de la versión 1.x, selecciona C# o JavaScript anteriormente.

Importante

PowerShell no es compatible con la versión 1.x del tiempo de ejecución de Azure Functions. Quizás, en su lugar, quieres migrar tu aplicación PowerShell de la versión 3.x a la versión 4.x. Si vas a migrar una aplicación de funciones de la versión 1.x, selecciona C# o JavaScript anteriormente.

Importante

Python no es compatible con la versión 1.x del tiempo de ejecución de Azure Functions. Quizás, en su lugar, quieres migrar tu aplicación Python de la versión 3.x a la versión 4.x. Si vas a migrar una aplicación de funciones de la versión 1.x, selecciona C# o JavaScript anteriormente.

Importante

La compatibilidad con la versión 1.x del entorno de ejecución de Azure Functions finalizará el 14 de septiembre de 2026. Le recomendamos encarecidamente que migre las aplicaciones a la versión 4.x siguiendo las instrucciones de este artículo.

En este artículo se explica el proceso de migración segura de la aplicación de funciones para que se ejecute en la versión 4.x del runtime de Functions. Dado que las instrucciones de migración del proyecto dependen del lenguaje, asegúrese de elegir el lenguaje de desarrollo en el selector de la parte superior del artículo.

Si ejecuta la versión 1.x del entorno de ejecución en Azure Stack Hub, consulte Consideraciones para Azure Stack Hub en primer lugar.

Identificación de las aplicaciones de funciones que se deben migrar

Utilice el siguiente script de PowerShell para generar una lista de aplicaciones de funciones de su suscripción que actualmente tienen como destino las versión 1.x:

$Subscription = '<YOUR SUBSCRIPTION ID>' 

Set-AzContext -Subscription $Subscription | Out-Null

$FunctionApps = Get-AzFunctionApp

$AppInfo = @{}

foreach ($App in $FunctionApps)
{
     if ($App.ApplicationSettings["FUNCTIONS_EXTENSION_VERSION"] -like '*1*')
     {
          $AppInfo.Add($App.Name, $App.ApplicationSettings["FUNCTIONS_EXTENSION_VERSION"])
     }
}

$AppInfo

Elección de la versión .NET de destino

En la versión 1.x del runtime de Functions, la aplicación de funciones de C# tiene como destino .NET Framework.

Al migrar la aplicación de funciones, tiene la oportunidad de elegir la versión de destino de .NET. Puede actualizar el proyecto de C# a una de las siguientes versiones de .NET compatibles con la versión 4.x de Functions:

Versión de .NET Tipo de versión de directiva de soporte técnico oficial de .NET Modelo de proceso de Functions 1,3
.NET 82 LTS Modelo de trabajo aislado
.NET 7 STS (finales de soporte técnico 14 de mayo de 2024) Modelo de trabajo aislado
.NET 6 LTS (finales de soporte técnico 12 de noviembre de 2024) Modelo de trabajo aislado,
Modelo en proceso3
.NET Framework 4.8 Consulte la directiva Modelo de trabajo aislado

1 El modelo de trabajo aislado admite las versiones de Soporte técnico a largo plazo (LTS) y Soporte técnico de términos estándar (STS) (STS) de .NET, así como .NET Framework. El modelo en proceso solo admite versiones LTS de .NET. Para obtener una comparación completa de características y funcionalidades entre los dos modelos, consulte Diferencias entre el proceso en proceso y el proceso de trabajador aislado .NET Azure Functions.

2 .NET 8 aún no se admite en el modelo en proceso, aunque está disponible en el modelo de trabajo aislado. Para obtener información sobre los planes de .NET 8, incluidas las opciones futuras para el modelo dentro del proceso, consulte la publicación Actualización de la hoja de ruta de Azure Functions.

3El soporte técnico finalizará para el modelo en proceso el 10 de noviembre de 2026. Para más información, consulte este anuncio de soporte. Para seguir teniendo soporte técnico completo, debería migrar sus aplicaciones al modelo de trabajo aislado.

Sugerencia

A menos que la aplicación dependa de una biblioteca o API solo disponible para .NET Framework, recomendamos actualizar a .NET 8 en el modelo de trabajo aislado. Muchas aplicaciones de la versión 1.x solo tienen como destino .NET Framework porque es lo que estaba disponible cuando se crearon. Hay funcionalidades adicionales disponibles para versiones más recientes de .NET, y si su aplicación no está obligada a permanecer en .NET Framework debido a una dependencia, debería tener como destino una versión más reciente. .NET 8 es la versión totalmente publicada con la ventana de soporte más larga de .NET.

Aunque puede optar por usar el modelo en proceso, no es recomendable, si se puede evitar. El soporte técnico finalizará para el modelo en proceso el 10 de noviembre de 2026, por lo que deberá pasar al modelo de trabajo aislado antes de esta fecha. Si lo hace, al migrar a la versión 4.x, se reducirá el esfuerzo total necesario y el modelo de trabajo aislado proporcionará a la aplicación ventajas adicionales, incluida la capacidad de tener como destino versiones futuras de .NET más fácilmente. Si va a pasar al modelo de trabajo aislado, el Asistente de actualización de .NET también puede encargarse de muchos de los cambios de código necesarios.

Esta guía no presenta ejemplos específicos para .NET 7 o .NET 6 en el modelo de trabajo aislado. Si necesita tener como destino estas versiones, puede adaptar los ejemplos de modelos de trabajo aislados de .NET 8.

Preparación para la migración

Si aún no lo ha hecho, identifique la lista de aplicaciones que necesitan migrarse en la suscripción actual de Azure mediante Azure PowerShell.

Antes de migrar una aplicación a la versión 4.x del runtime de Functions, debe realizar las siguientes tareas:

  1. Revisa la lista de cambios de comportamiento después de la versión 1.x. La migración de la versión 1.x a la versión 4.x también puede afectar a los enlaces.
  2. Complete los pasos descritos en Migración del proyecto local para migrar el proyecto local a la versión 4.x.
  3. Tras migrar el proyecto, pruebe completamente la aplicación localmente con la versión 4.x de Azure Functions Core Tools.
  4. Actualiza la aplicación de funciones en Azure a la nueva versión. Si necesita minimizar el tiempo de inactividad, considere la posibilidad de usar un espacio de ensayo para probar y comprobar la aplicación migrada en Azure en la nueva versión de runtime. Después, puede implementar la aplicación con la configuración de versión actualizada en el espacio de producción. Para más información, consulte Actualización mediante ranuras.
  5. Publique el proyecto migrado en la aplicación de funciones actualizada.

Al usar Visual Studio para publicar un proyecto de versión 4.x en una aplicación de funciones existente de una versión inferior, se le pedirá que permita que Visual Studio actualice la aplicación de funciones a la versión 4.x durante la implementación. Esta actualización usa el mismo proceso definido en Actualización sin ranuras.

Migración del proyecto local

En las secciones siguientes se describen las actualizaciones que debe realizar en los archivos de proyecto de C# para poder ejecutarse en una de las versiones compatibles de .NET en Functions versión 4.x. Las actualizaciones que se muestran son comunes a la mayoría de los proyectos. El código del proyecto podría requerir actualizaciones que no se mencionan en este artículo, especialmente cuando se usan paquetes NuGet personalizados.

La migración de una aplicación de funciones de C# de la versión 1.x a la versión 4.x del entorno de ejecución de Functions requiere que realice cambios en el código del proyecto. Muchos de estos cambios son el resultado de los cambios en el lenguaje C# y las API de .NET.

Elija la pestaña que coincida con la versión de destino de .NET y el modelo de proceso deseado (proceso de trabajo en proceso o aislado).

Sugerencia

Si va a pasar a una versión LTS o STS de .NET, el Asistente para actualización de .NET se puede usar para realizar automáticamente muchos de los cambios mencionados en las siguientes secciones.

Archivo del proyecto

El siguiente ejemplo es un archivo de proyecto .csproj que funciona con la versión 1.x:

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net48</TargetFramework>
    <AzureFunctionsVersion>v1</AzureFunctionsVersion>
  </PropertyGroup>
  <ItemGroup>
    <PackageReference Include="Microsoft.NET.Sdk.Functions" Version="1.0.24" />
  </ItemGroup>
  <ItemGroup>
    <Reference Include="Microsoft.CSharp" />
  </ItemGroup>
  <ItemGroup>
    <None Update="host.json">
      <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
    </None>
    <None Update="local.settings.json">
      <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
      <CopyToPublishDirectory>Never</CopyToPublishDirectory>
    </None>
  </ItemGroup>
</Project>

Use uno de los procedimientos siguientes para actualizar este archivo XML para que se ejecute en la versión 4.x de Functions:

Estos pasos suponen un proyecto de C# local y, si se usa la aplicación en lugar de usar el script de C# (archivos .csx), debe convertir al modelo de proyecto antes de continuar.

Los siguientes cambios son necesarios en el archivo de proyecto XML .csproj:

  1. Establezca el valor de PropertyGroup.De TargetFramework a net8.0.

  2. Establezca el valor de PropertyGroup.De AzureFunctionsVersion a v4.

  3. Agregue el elemento OutputType siguiente a PropertyGroup:

    <OutputType>Exe</OutputType>

  4. En la lista ItemGroup.PackageReference, reemplace la referencia de paquete a Microsoft.NET.Sdk.Functions por las referencias siguientes:

      <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" />

    Anote las referencias a otros paquetes de los espacios de nombres de Microsoft.Azure.WebJobs.*. Reemplazará estos paquetes en un paso posterior.

  5. Agregue el nuevo ItemGroup siguiente:

    <ItemGroup>
  <Using Include="System.Threading.ExecutionContext" Alias="ExecutionContext"/>
</ItemGroup>

Después de realizar estos cambios, el proyecto actualizado debe tener un aspecto similar al del ejemplo siguiente:

<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>

Cambios en el paquete y el espacio de nombres

Según el modelo al que vaya a migrar, es posible que deba actualizar o cambiar los paquetes a los que hace referencia la aplicación. Al adoptar los paquetes de destino, es posible que tenga que actualizar el espacio de nombres de las instrucciones "using" y algunos tipos a los que haga referencia. Puede ver el efecto de estos cambios de espacio de nombres en las instrucciones using en los ejemplos de plantilla de desencadenadores HTTP más adelante en este artículo.

Si aún no lo ha hecho, actualice el proyecto para hacer referencia a las versiones estables más recientes de:

Dependiendo de los desencadenadores y enlaces que use la aplicación, es posible que la aplicación tenga que hacer referencia a un conjunto diferente de paquetes. En la tabla siguiente se muestran los reemplazos de algunas de las extensiones más usadas:

Escenario Cambios en las referencias de paquete
Desencadenador de temporizador Sumar
Microsoft.Azure.Functions.Worker.Extensions.Timer
Enlaces de Storage Sustituya
Microsoft.Azure.WebJobs.Extensions.Storage
con
Microsoft.Azure.Functions.Worker.Extensions.Storage.Blobs,
Microsoft.Azure.Functions.Worker.Extensions.Storage.Queues y
Microsoft.Azure.Functions.Worker.Extensions.Tables
Enlaces de blob Reemplace las referencias a
Microsoft.Azure.WebJobs.Extensions.Storage.Blobs
con la versión más reciente de
Microsoft.Azure.Functions.Worker.Extensions.Storage.Blobs
Enlaces de cola Reemplace las referencias a
Microsoft.Azure.WebJobs.Extensions.Storage.Queues
con la versión más reciente de
Microsoft.Azure.Functions.Worker.Extensions.Storage.Queues
Enlaces de tabla Reemplace las referencias a
Microsoft.Azure.WebJobs.Extensions.Tables
con la versión más reciente de
Microsoft.Azure.Functions.Worker.Extensions.Tables
Enlaces de Cosmos DB Reemplace las referencias a
Microsoft.Azure.WebJobs.Extensions.CosmosDB
y/o
Microsoft.Azure.WebJobs.Extensions.DocumentDB
con la versión más reciente de
Microsoft.Azure.Functions.Worker.Extensions.CosmosDB
Enlaces de Service Bus Reemplace las referencias a
Microsoft.Azure.WebJobs.Extensions.ServiceBus
con la versión más reciente de
Microsoft.Azure.Functions.Worker.Extensions.ServiceBus
Enlaces de Event Hubs Reemplace las referencias a
Microsoft.Azure.WebJobs.Extensions.EventHubs
con la versión más reciente de
Microsoft.Azure.Functions.Worker.Extensions.EventHubs
Enlaces de Event Grid Reemplace las referencias a
Microsoft.Azure.WebJobs.Extensions.EventGrid
con la versión más reciente de
Microsoft.Azure.Functions.Worker.Extensions.EventGrid
Enlaces de SignalR Service Reemplace las referencias a
Microsoft.Azure.WebJobs.Extensions.SignalRService
con la versión más reciente de
Microsoft.Azure.Functions.Worker.Extensions.SignalRService
Funciones duraderas Reemplace las referencias a
Microsoft.Azure.WebJobs.Extensions.DurableTask
con la versión más reciente de
Microsoft.Azure.Functions.Worker.Extensions.DurableTask
Funciones duraderas
(proveedor de almacenamiento de SQL)		 Reemplace las referencias a
Microsoft.DurableTask.SqlServer.AzureFunctions
con la versión más reciente de
Microsoft.Azure.Functions.Worker.Extensions.DurableTask.SqlServer
Funciones duraderas
(proveedor de almacenamiento Netherite)		 Reemplace las referencias a
Microsoft.Azure.DurableTask.Netherite.AzureFunctions
con la versión más reciente de
Microsoft.Azure.Functions.Worker.Extensions.DurableTask.Netherite
Enlaces de SendGrid Reemplace las referencias a
Microsoft.Azure.WebJobs.Extensions.SendGrid
con la versión más reciente de
Microsoft.Azure.Functions.Worker.Extensions.SendGrid
Enlaces de Kafka Reemplace las referencias a
Microsoft.Azure.WebJobs.Extensions.Kafka
con la versión más reciente de
Microsoft.Azure.Functions.Worker.Extensions.Kafka
Enlaces de RabbitMQ Reemplace las referencias a
Microsoft.Azure.WebJobs.Extensions.RabbitMQ
con la versión más reciente de
Microsoft.Azure.Functions.Worker.Extensions.RabbitMQ
Inserción de dependencia
y configuración de inicio		 Elimine las referencias a
Microsoft.Azure.Functions.Extensions
(El modelo de trabajo aislado proporciona esta funcionalidad de forma predeterminada).

Consulte Enlaces admitidos para obtener una lista completa de extensiones que se deben tener en cuenta y consulte la documentación de cada extensión para obtener instrucciones de instalación completas para el modelo de proceso aislado. Asegúrese de instalar la versión estable más reciente de los paquetes de destino.

Sugerencia

Los cambios en las versiones de extensión durante este proceso pueden requerir que actualice también el archivo host.json. Asegúrese de leer la documentación de cada extensión que use. Por ejemplo, la extensión de Service Bus tiene cambios importantes en la estructura entre las versiones 4.x y 5.x. Para más información, consulte Enlaces de Azure Service Bus para Azure Functions.

La aplicación del modelo de trabajo aislado no debe hacer referencia a ningún paquete en los espacios de nombres de Microsoft.Azure.WebJobs.* o Microsoft.Azure.Functions.Extensions. Si quedan referencias a estos, debe quitarlas.

Sugerencia

La aplicación también puede depender de los tipos de SDK de Azure, ya sea como parte de los desencadenadores y enlaces o como una dependencia independiente. Debería aprovechar esta oportunidad para actualizar también esto. Las versiones más recientes de las extensiones de Functions funcionan con las versiones más recientes del SDK de Azure para .NET, casi todos los paquetes para los que el formato es Azure.*.

Los enlaces de Notification Hubs y Mobile Apps solo se admiten en la versión 1.x del entorno de ejecución. Al actualizar a la versión 4.x del entorno de ejecución, debe quitar estos enlaces para trabajar con estos servicios directamente mediante sus SDK.

Archivo program.cs

En la mayoría de los casos, la migración requiere que agregue el siguiente archivo program.cs al proyecto:

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();

En este ejemplo se incluye la integración de ASP.NET Core para mejorar el rendimiento y proporcionar un modelo de programación familiar cuando la aplicación usa desencadenadores HTTP. Si no pretende usar desencadenadores HTTP, puede reemplazar la llamada a ConfigureFunctionsWebApplication por una llamada a ConfigureFunctionsWorkerDefaults. Si lo hace, puede quitar la referencia a Microsoft.Azure.Functions.Worker.Extensions.Http.AspNetCore del archivo del proyecto. Sin embargo, para obtener el mejor rendimiento, incluso para las funciones con otros tipos de desencadenador, debe mantener FrameworkReference en ASP.NET Core.

El archivo Program.cs reemplazará cualquier archivo que tenga el atributo FunctionsStartup, que suele ser un archivo Startup.cs. En los lugares donde su código FunctionsStartup haría referencia a IFunctionsHostBuilder.Services, puede agregar en su lugar instrucciones dentro del método .ConfigureServices() del HostBuilder en su Program.cs. Para más información sobre cómo trabajar con Program.cs, consulte Inicio y configuración en la guía del modelo de trabajo aislado.

Los ejemplos de Program.cs predeterminados anteriores incluyen la configuración de la integración de Application Insights para el modelo de trabajo aislado. En su Program.cs, también debe configurar cualquier filtrado de registros que se aplique a los registros procedentes del código del proyecto. En el modelo de trabajo aislado, el archivo host.json solo controla los eventos emitidos por el entorno de ejecución del host de Functions. Si no configura reglas de filtrado en Program.cs, es posible que perciba diferencias en los niveles de registro presentes para varias categorías en la telemetría.

Aunque puede registrar orígenes de configuración personalizados como parte de HostBuilder, tenga en cuenta que se aplican de forma similar solo al código del proyecto. La plataforma también necesita la configuración de desencadenador y enlace, y esto se debe proporcionar a través de las características de configuración de la aplicación, las referencias de Key Vault o las referencias de App Configuration.

Una vez que haya trasladado todo de cualquier FunctionsStartup existente al archivo Program.cs, podrá eliminar el atributo FunctionsStartup y la clase a la que se aplicó.

Archivo host.json

La configuración del archivo host.json se aplica en el nivel de aplicación de función, tanto localmente como en Azure. En la versión 1.x, el archivo host.json está vacío o contiene algunas opciones de configuración que se aplican a todas las funciones de la aplicación de funciones. Para más información, consulta Host.json v1. Si el archivo host.json tiene valores de configuración, revisa el formato host.json v2 para ver los cambios.

Para ejecutarse en la versión 4.x, debes agregar "version": "2.0" al archivo host.json. También debes considerar la posibilidad de agregar logging a la configuración, como en los ejemplos siguientes:

{
    "version": "2.0",
    "logging": {
        "applicationInsights": {
            "samplingSettings": {
                "isEnabled": true,
                "excludedTypes": "Request"
            },
            "enableLiveMetricsFilters": true
        }
    }
}

El archivo host.json solo controla el registro desde el entorno de ejecución del host de Functions y, en el modelo de trabajo aislado, algunos de estos registros proceden directamente de la aplicación, lo cual proporciona más control. Consulte Administración de niveles de registro en el modelo de trabajo aislado para obtener más información sobre cómo filtrar estos registros.

Archivo local.settings.json

El archivo local.settings.json solo se usa en la ejecución local. Para obtener información, consulte Archivo de configuración local. En la versión 1.x, el archivo local.settings.json solo tiene dos valores necesarios:

{
    "IsEncrypted": false,
    "Values": {
        "AzureWebJobsStorage": "AzureWebJobsStorageConnectionStringValue",
        "AzureWebJobsDashboard": "AzureWebJobsStorageConnectionStringValue"
    }
}

Al actualizar a la versión 4.x, asegúrese de que el archivo local.settings.json tiene al menos los siguientes elementos:

{
    "IsEncrypted": false,
    "Values": {
        "AzureWebJobsStorage": "AzureWebJobsStorageConnectionStringValue",
        "FUNCTIONS_WORKER_RUNTIME": "dotnet-isolated"
    }
}

Nota:

Al migrar de una ejecución en proceso a una ejecución en un proceso de trabajo aislado, debe cambiar el valor de FUNCTIONS_WORKER_RUNTIME a “dotnet-isolated”.

Cambios en el nombre de clase

Algunas clases clave cambiaron los nombres entre la versión 1.x y la versión 4.x. Estos cambios son el resultado de los cambios en las API de .NET o en diferencias entre el proceso en proceso y el proceso de trabajo aislado. En la tabla siguiente se indican las clases de .NET clave usadas por Functions que podrían cambiar al migrar:

Versión 1.x .NET 8
FunctionName (atributo) Function (atributo)
TraceWriter ILogger<T>, ILogger
HttpRequestMessage HttpRequestData, HttpRequest (usando integración ASP.NET Core)
HttpResponseMessage HttpResponseData, IActionResult (usando integración ASP.NET Core)

También puede haber diferencias de nombre de clase en los enlaces. Para más información, consulte los artículos de referencia de los enlaces concretos.

Otros cambios de código

En esta sección se resaltan otros cambios de código que se deben tener en cuenta a medida que se trabaja por la migración. No todas las aplicaciones necesitan estos cambios, pero debe evaluar si alguno es relevante para sus escenarios. Asegúrese de comprobar Cambios de comportamiento a partir de la versión 1.x para ver los cambios adicionales que debe realizar en el proyecto.

Serialización de JSON

De forma predeterminada, el modelo de trabajo aislado usa System.Text.Json para la serialización de JSON. Para personalizar las opciones del serializador o cambiar a JSON.NET (Newtonsoft.Json), consulte estas instrucciones.

Filtrado y niveles de registro de Application Insights

Los registros se pueden enviar a Application Insights desde el entorno de ejecución del host de Functions y el código del proyecto. host.json permite configurar reglas para el registro de host, pero para controlar los registros procedentes del código, deberá configurar reglas de filtrado como parte de Program.cs. Consulte Administración de niveles de registro en el modelo de trabajo aislado para obtener más información sobre cómo filtrar estos registros.

Plantilla de desencadenador HTTP

La mayoría de los cambios de código entre la versión 1.x y la versión 4.x se pueden ver en las funciones desencadenadas por HTTP. La plantilla de desencadenador HTTP para la versión 1.x tiene un aspecto similar al del siguiente ejemplo:

using System.Linq;
using System.Net;
using System.Net.Http;
using System.Threading.Tasks;
using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Extensions.Http;
using Microsoft.Azure.WebJobs.Host;

namespace Company.Function
{
    public static class HttpTriggerCSharp
    {
        [FunctionName("HttpTriggerCSharp")]
        public static async Task<HttpResponseMessage> 
            Run([HttpTrigger(AuthorizationLevel.AuthLevelValue, "get", "post", 
            Route = null)]HttpRequestMessage req, TraceWriter log)
        {
            log.Info("C# HTTP trigger function processed a request.");

            // parse query parameter
            string name = req.GetQueryNameValuePairs()
                .FirstOrDefault(q => string.Compare(q.Key, "name", true) == 0)
                .Value;

            if (name == null)
            {
                // Get request body
                dynamic data = await req.Content.ReadAsAsync<object>();
                name = data?.name;
            }

            return name == null
                ? req.CreateResponse(HttpStatusCode.BadRequest, 
                    "Please pass a name on the query string or in the request body")
                : req.CreateResponse(HttpStatusCode.OK, "Hello " + name);
        }
    }
}

En la versión 4.x, la plantilla de desencadenador HTTP tiene un aspecto similar al del siguiente ejemplo:

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

namespace Company.Function
{
    public class HttpTriggerCSharp
    {
        private readonly ILogger<HttpTriggerCSharp> _logger;

        public HttpTriggerCSharp(ILogger<HttpTriggerCSharp> logger)
        {
            _logger = 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"]}!");
        }
    }
}

Para actualizar el proyecto a Azure Functions 4.x:

  1. Actualice la instalación local de Azure Functions Core Tools a la versión 4.x.

  2. Dirígete a una de las versiones de Node.js compatibles con la versión 4.x.

  3. Agrega ambos elementos version y extensionBundle al archivo host.json para que tenga un aspecto similar al ejemplo siguiente:

    {
    "version": "2.0",
    "extensionBundle": {
        "id": "Microsoft.Azure.Functions.ExtensionBundle",
        "version": "[3.3.0, 4.0.0)"
    }
}

    El elemento extensionBundle es necesario porque después de la versión 1.x, los enlaces se mantienen como paquetes externos. Para obtener más información, consulta Conjuntos de extensión.

  4. Actualiza el archivo local.settings.json para que tenga al menos los siguientes elementos:

    {
    "IsEncrypted": false,
    "Values": {
        "AzureWebJobsStorage": "UseDevelopmentStorage=true",
        "FUNCTIONS_WORKER_RUNTIME": "node"
    }
}

    La AzureWebJobsStorage configuración puede ser el emulador de almacenamiento de Azurite o una cuenta de almacenamiento de Azure real. Para más información, consulte Emulador de almacenamiento local.

Actualización de la aplicación de funciones en Azure

Debe actualizar el runtime del host de la aplicación de funciones en Azure a la versión 4.x antes de publicar el proyecto migrado. La versión de runtime usada por el host de Functions se controla mediante la configuración FUNCTIONS_EXTENSION_VERSION de la aplicación, pero en algunos casos también se deben actualizar otras configuraciones. Tanto los cambios de código como los cambios en la configuración de la aplicación requieren el reinicio de la aplicación de funciones.

La manera más fácil es actualizar sin ranuras y volver a publicar el proyecto de la aplicación. También puede minimizar el tiempo de inactividad de la aplicación y simplificar la reversión mediante la actualización con ranuras.

Actualización sin ranuras

La manera más sencilla de actualizar a la versión v4.x es establecer la configuración de aplicación FUNCTIONS_EXTENSION_VERSION en ~4 en la aplicación de funciones de Azure. En un sitio con ranuras, debe seguir un procedimiento diferente.

az functionapp config appsettings set --settings FUNCTIONS_EXTENSION_VERSION=~4 -g <RESOURCE_GROUP_NAME> -n <APP_NAME>

Durante la actualización, también debe establecer otras configuraciones, que son diferentes en Windows y en Linux.

Cuando se ejecuta en Windows, también debe habilitar .NET 6.0, que requiere la versión 4.x del entorno de ejecución.

az functionapp config set --net-framework-version v6.0 -g <RESOURCE_GROUP_NAME> -n <APP_NAME>

.NET 6 es necesario para las aplicaciones de funciones en cualquier lenguaje que se ejecute en Windows.

En este ejemplo, reemplace <APP_NAME> por el nombre de la aplicación de funciones y <RESOURCE_GROUP_NAME> por el nombre del grupo de recursos.

Ahora puede volver a publicar el proyecto de la aplicación que se ha migrado para ejecutarse en la versión 4.x.

Migración mediante espacios

El uso de ranuras de implementación es una buena manera de actualizar la aplicación de funciones al runtime v4.x desde una versión anterior. Mediante un espacio de ensayo, puede ejecutar la aplicación en la nueva versión del entorno de ejecución en la ranura de ensayo y cambiar a producción después de la comprobación. Las ranuras también proporcionan una manera de minimizar el tiempo de inactividad durante la actualización. Si necesita minimizar el tiempo de inactividad, siga los pasos descritos en Actualización de tiempo de inactividad mínimo.

Después de comprobar la aplicación en la ranura actualizada, puede pasar la aplicación y la nueva configuración de la versión a producción. Este cambio requiere la configuración WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS=0 en el espacio de producción. La forma de agregar esta configuración afecta a la cantidad de tiempo de inactividad necesario para la actualización.

Actualización estándar

Si la aplicación de funciones habilitada para ranuras puede controlar el tiempo de inactividad de un reinicio completo, puede actualizar la configuración WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS directamente en el espacio de producción. Dado que cambiar esta configuración directamente en el espacio de producción provoca un reinicio que afecta a la disponibilidad, considere la posibilidad de realizar este cambio cuando hay poco tráfico. Después, puede cambiar la versión actualizada desde el espacio de ensayo.

El cmdlet de PowerShell Update-AzFunctionAppSetting no admite actualmente ranuras. Puede usar Azure Portal o la CLI de Azure.

  1. Use el siguiente comando para establecer WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS=0 en el espacio de producción:

    az functionapp config appsettings set --settings WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS=0  -g <RESOURCE_GROUP_NAME>  -n <APP_NAME>

    En este ejemplo, reemplace <APP_NAME> por el nombre de la aplicación de funciones y <RESOURCE_GROUP_NAME> por el nombre del grupo de recursos. Este comando hace que la aplicación que se ejecuta en el espacio de producción se reinicie.

  2. Use el siguiente comando para establecer también WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS en el espacio de ensayo:

    az functionapp config appsettings set --settings WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS=0 -g <RESOURCE_GROUP_NAME>  -n <APP_NAME> --slot <SLOT_NAME>

  3. Use el siguiente comando para cambiar FUNCTIONS_EXTENSION_VERSION y actualizar el espacio de ensayo a la nueva versión del entorno de ejecución:

    az functionapp config appsettings set --settings FUNCTIONS_EXTENSION_VERSION=~4 -g <RESOURCE_GROUP_NAME>  -n <APP_NAME> --slot <SLOT_NAME>

  4. La versión 4.x del entorno de ejecución de Functions requiere .NET 6 en Windows. En Linux, las aplicaciones .NET también deben actualizarse a .NET 6. Use el siguiente comando para que el entorno de ejecución pueda ejecutarse en .NET 6:

    Cuando se ejecuta en Windows, también debe habilitar .NET 6.0, que requiere la versión 4.x del entorno de ejecución.

    az functionapp config set --net-framework-version v6.0 -g <RESOURCE_GROUP_NAME> -n <APP_NAME>

    .NET 6 es necesario para las aplicaciones de funciones en cualquier lenguaje que se ejecute en Windows.

    En este ejemplo, reemplace <APP_NAME> por el nombre de la aplicación de funciones y <RESOURCE_GROUP_NAME> por el nombre del grupo de recursos.

  5. Si el proyecto de código necesita actualizaciones para ejecutarse en la versión 4.x, implemente esas actualizaciones en el espacio de ensayo ahora.

  6. Antes de realizar el cambio, confirme que la aplicación de funciones se ejecuta correctamente en el entorno de ensayo actualizado.

  7. Use el siguiente comando para cambiar el espacio de ensayo actualizado a producción:

    az functionapp deployment slot swap -g <RESOURCE_GROUP_NAME>  -n <APP_NAME> --slot <SLOT_NAME> --target-slot production

Actualización de tiempo de inactividad mínimo

Para minimizar el tiempo de inactividad de la aplicación de producción, puede cambiar la configuración WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS del espacio de ensayo a producción. Después, puede cambiar la versión actualizada desde un espacio de ensayo ya preparado.

  1. Use el siguiente comando para establecer WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS=0 en el espacio de ensayo:

    az functionapp config appsettings set --settings WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS=0 -g <RESOURCE_GROUP_NAME>  -n <APP_NAME> --slot <SLOT_NAME>

  2. Use los siguientes comandos para cambiar la ranura con la nueva configuración a producción y, al mismo tiempo, restaurar la configuración de versión en el espacio de ensayo.

    az functionapp deployment slot swap -g <RESOURCE_GROUP_NAME>  -n <APP_NAME> --slot <SLOT_NAME> --target-slot production
az functionapp config appsettings set --settings FUNCTIONS_EXTENSION_VERSION=~3 -g <RESOURCE_GROUP_NAME>  -n <APP_NAME> --slot <SLOT_NAME>

    Es posible que aparezcan errores del espacio de ensayo entre que se produce el cambio y se restaura la versión en tiempo de ejecución en el entorno de ensayo. Este error puede ocurrir porque tener WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS=0 solo en el entorno de ensayo durante un intercambio quita la configuración FUNCTIONS_EXTENSION_VERSION en el entorno de ensayo. Sin la configuración de versión, la ranura está en un estado incorrecto. La actualización de la versión en el espacio de ensayo justo después del intercambio volverá a colocar la ranura en buen estado. Además, si es necesario, se pueden revertir los cambios. Sin embargo, cualquier reversión del cambio también requiere que se quite WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS=0 directamente de producción antes del intercambio para evitar los mismos errores en producción vistos en el entorno de ensayo. Este cambio en la configuración de producción provocaría un reinicio.

  3. Use el siguiente comando para volver a establecer WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS=0 en el espacio de ensayo:

    az functionapp config appsettings set --settings WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS=0 -g <RESOURCE_GROUP_NAME>  -n <APP_NAME> --slot <SLOT_NAME>

    En este momento, ambas ranuras tienen establecido WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS=0.

  4. Use el siguiente comando para cambiar FUNCTIONS_EXTENSION_VERSION y actualizar el espacio de ensayo a la nueva versión del entorno de ejecución:

    az functionapp config appsettings set --settings FUNCTIONS_EXTENSION_VERSION=~4 -g <RESOURCE_GROUP_NAME>  -n <APP_NAME> --slot <SLOT_NAME>

  5. La versión 4.x del entorno de ejecución de Functions requiere .NET 6 en Windows. En Linux, las aplicaciones .NET también deben actualizarse a .NET 6. Use el siguiente comando para que el entorno de ejecución pueda ejecutarse en .NET 6:

    Cuando se ejecuta en Windows, también debe habilitar .NET 6.0, que requiere la versión 4.x del entorno de ejecución.

    az functionapp config set --net-framework-version v6.0 -g <RESOURCE_GROUP_NAME> -n <APP_NAME>

    .NET 6 es necesario para las aplicaciones de funciones en cualquier lenguaje que se ejecute en Windows.

    En este ejemplo, reemplace <APP_NAME> por el nombre de la aplicación de funciones y <RESOURCE_GROUP_NAME> por el nombre del grupo de recursos.

  6. Si el proyecto de código necesita actualizaciones para ejecutarse en la versión 4.x, implemente esas actualizaciones en el espacio de ensayo ahora.

  7. Antes de realizar el cambio, confirme que la aplicación de funciones se ejecuta correctamente en el entorno de ensayo actualizado.

  8. Use el comando siguiente para cambiar el espacio de ensayo actualizado y preparado previamente a producción:

    az functionapp deployment slot swap -g <RESOURCE_GROUP_NAME>  -n <APP_NAME> --slot <SLOT_NAME> --target-slot production

Cambios de comportamiento después de la versión 1.x

En esta sección se detallan los cambios realizados después de la versión 1.x en los comportamientos de desencadenador y enlace, así como en las características y comportamientos principales de Functions.

Cambio en los desencadenadores y los enlaces

A partir de la versión 2.x, debe instalar las extensiones para desencadenadores y enlaces específicos que las funciones de la aplicación utilizan. La única excepción son los desencadenadores HTTP y el temporizador, que no requieren extensión. Para más información, consulte la sección sobre Registro e instalación de extensiones de enlace.

También hay algunos cambios en function.json o los atributos de la función de una versión a otra. Por ejemplo, la propiedad path de Event Hubs es ahora eventHubName. Consulte la tabla de enlaces existentes para vínculos a la documentación de cada enlace.

Cambios en las características y la funcionalidad

Se han quitado, actualizado o reemplazado algunas características después de la versión 1.x. En esta sección se describen los cambios que se observan en versiones posteriores después de haber utilizado la versión 1.x.

En la versión 2.x se han realizado los siguientes cambios:

  • Las claves para llamar a los puntos de conexión HTTP siempre se almacenan cifradas en Azure Blob Storage. En la versión 1.x, se almacenaban en Azure Files de manera predeterminada. Cuando se migra una aplicación de la versión 1.x a la 2.x, se restablecen los secretos existentes que se encuentran en Azure Files.

  • La versión 2.x del entorno de ejecución no incluye compatibilidad integrada con proveedores de webhooks. Este cambio se realizó para mejorar el rendimiento. Todavía puede usar desencadenadores HTTP como puntos de conexión para los webhooks.

  • Para mejorar la supervisión, el panel de WebJobs del portal, que usaba la configuración AzureWebJobsDashboard se reemplaza por Azure Application Insights, que usa la configuración APPINSIGHTS_INSTRUMENTATIONKEY. Para más información, consulte Supervisión de Azure Functions.

  • Todas las funciones de una aplicación de función deben compartir el mismo lenguaje. Al crear una aplicación de función, debe elegir una pila del entorno de ejecución para la aplicación. La pila del entorno de ejecución se especifica con el valor FUNCTIONS_WORKER_RUNTIME en la configuración de la aplicación. Este requisito se agregó para mejorar el tiempo de inicio y la superficie de memoria. Al desarrollar localmente, también debe incluir esta configuración en el archivo local.settings.json.

  • El tiempo de espera predeterminado para las funciones en un plan de App Service ha cambiado a 30 minutos. Puede cambiar manualmente el tiempo de espera de vuelta a ilimitado mediante la configuración functionTimeout de host.json.

  • Se implementan de forma predeterminada limitaciones de simultaneidad HTTP para las funciones del plan de consumo, cuyo valor predeterminado es de 100 solicitudes simultáneas por instancia. Puede cambiar este comportamiento en la configuración maxConcurrentRequests del archivo host.json.

  • A causa de las limitaciones de .NET Core, se ha eliminado la compatibilidad con las funciones de script (archivos .fsx) de F#. Todavía se admiten las funciones compiladas de F# (.fs).

  • Ha cambiado el formato de dirección URL de los webhooks de desencadenador de Event Grid para seguir este patrón: https://{app}/runtime/webhooks/{triggerName}.

  • Los nombres de algunas métricas personalizadas predefinidas se han cambiado después de la versión 1.x. Duration se ha reemplazado por MaxDurationMs, MinDurationMsy AvgDurationMs. También se ha cambiado el nombre de Success Rate a Success Rate.

Consideraciones sobre Azure Stack Hub

App Service en Azure Stack Hub no admite la versión 4.x de Azure Functions. Al planificar una migración a partir de la versión 1.x en Azure Stack Hub, puede elegir una de las siguientes opciones:

  • Migrar a la versión 4.x hospedada en la nube pública de Azure Functions siguiendo las instrucciones de este artículo. En lugar de actualizar la aplicación existente, crearía una nueva aplicación con la versión 4.x y, a continuación, implementaría el proyecto modificado en ella.
  • Cambiar a WebJobs hospedado en un plan de App Service en Azure Stack Hub.

Pasos siguientes

Más información sobre las versiones de Functions