Compartir a través de

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

  • Artículo

Azure Functions versión 4.x es una versión muy compatible con la versión 3.x. Muchas aplicaciones se deben migrar de forma segura a la versión 4.x sin ningún cambio importante en el código. Para más información sobre las versiones del runtime de Functions, vea Introducción a las versiones de runtime de Azure Functions.

Importante

Desde el 13 de diciembre de 2022, las aplicaciones de funciones que se ejecutan en las versiones 2.x y 3.x del entorno de ejecución de Azure Functions han alcanzado el final del soporte extendido. Para más información, vea Versiones retiradas.

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.

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 versiones 2.x o 3.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 '*3*')
     {
          $AppInfo.Add($App.Name, $App.ApplicationSettings["FUNCTIONS_EXTENSION_VERSION"])
     }
}

$AppInfo

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

En la versión 3.x del entorno de ejecución de Functions, la aplicación de funciones de C# tiene como destino .NET Core 3.1 mediante el modelo en proceso o .NET 5 mediante el modelo de trabajo aislado.

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 Functions1,2
.NET 9 STS (finales de soporte técnico 12 de mayo de 2026) Modelo de trabajo aislado
.NET 8 LTS (final del soporte técnico 10 de noviembre de 2026) Modelo de trabajo aislado,
Modelo In-Process2
.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 In-Process solo admite versiones LTS de .NET, que terminan con .NET 8. 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 El soporte técnico finaliza 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

Se recomienda actualizar a .NET 8 en el modelo de trabajo aislado. .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 9. Si necesita tener como destino esa versión, puede adaptar los ejemplos del modelo de trabajo aislado 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. Revise la lista de cambios importantes entre las versiones 3.x y 4.x.
  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. Ejecute el validador previo a la actualización en la aplicación hospedada en Azure y resuelva los problemas identificados.
  5. 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.
  6. 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

Las instrucciones de actualización pueden variar de un idioma a otro. Si no ve su lenguaje, selecciónelo en el selector de la parte superior del artículo.

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 ejemplo siguiente es un archivo de proyecto .csproj que usa .NET Core 3.1 en la versión 3.x:

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>netcoreapp3.1</TargetFramework>
    <AzureFunctionsVersion>v3</AzureFunctionsVersion>
  </PropertyGroup>
  <ItemGroup>
    <PackageReference Include="Microsoft.NET.Sdk.Functions" Version="3.0.13" />
  </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 también deba actualizar 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.*.

Archivo program.cs

Al realizar la migrar para que se ejecute en un proceso de trabajo aislado, debe agregar 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 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.

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

Archivo host.json

No se requieren cambios en el código del archivo host.json. Sin embargo, si la configuración de Application Insights proviene de este archivo del proyecto de modelo en proceso, es posible que quiera realizar cambios adicionales en el archivo Program.cs. 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.

Cambios en el nombre de clase

Algunas clases clave cambiaron los nombres entre las versiones. 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:

.NET Core 3.1 .NET 5 .NET 8
FunctionName (atributo) Function (atributo) Function (atributo)
ILogger ILogger ILogger, ILogger<T>
HttpRequest HttpRequestData HttpRequestData, HttpRequest (usando integración ASP.NET Core)
IActionResult HttpResponseData HttpResponseData, IActionResult (usando integración ASP.NET Core)
FunctionsStartup (atributo) Usa Program.cs en su lugar Usa Program.cs en su lugar

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 importantes entre las versiones 3.x y 4.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

Las diferencias entre el proceso de trabajo en proceso y el proceso de trabajo aislado se pueden ver en las funciones desencadenadas por HTTP. La plantilla de desencadenador HTTP para la versión 3.x (en proceso) tiene un aspecto similar al del siguiente ejemplo:

using System;
using System.IO;
using System.Threading.Tasks;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Extensions.Http;
using Microsoft.AspNetCore.Http;
using Microsoft.Extensions.Logging;
using Newtonsoft.Json;

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

            string name = req.Query["name"];

            string requestBody = await new StreamReader(req.Body).ReadToEndAsync();
            dynamic data = JsonConvert.DeserializeObject(requestBody);
            name = name ?? data?.name;

            string responseMessage = string.IsNullOrEmpty(name)
                ? "This HTTP triggered function executed successfully. Pass a name in the query string or in the request body for a personalized response."
                : $"Hello, {name}. This HTTP triggered function executed successfully.";

            return new OkObjectResult(responseMessage);
        }
    }
}

La plantilla de desencadenador HTTP para la versión migrada 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. Actualice la agrupación de extensiones de Azure Functions de la aplicación a la versión 2.x o superior. Para más información, consulte Cambios importantes.

  1. Si es necesario, vaya a una de las versiones de Java compatibles con la versión 4.x.

  2. Actualice el archivo POM.xml de la aplicación para modificar la configuración FUNCTIONS_EXTENSION_VERSION en ~4, como en el ejemplo siguiente:

    <configuration>
    <resourceGroup>${functionResourceGroup}</resourceGroup>
    <appName>${functionAppName}</appName>
    <region>${functionAppRegion}</region>
    <appSettings>
        <property>
            <name>WEBSITE_RUN_FROM_PACKAGE</name>
            <value>1</value>
        </property>
        <property>
            <name>FUNCTIONS_EXTENSION_VERSION</name>
            <value>~4</value>
        </property>
    </appSettings>
</configuration>
  1. Si es necesario, vaya a una de las versiones de Node.js compatibles con la versión 4.x.
  1. Aproveche esta oportunidad para actualizar a PowerShell 7.2, lo que se recomienda. Para obtener más información, consulte Versiones de PowerShell.
  1. Si usa Python 3.6, migre a una de las versiones admitidas.

Ejecución del validador previo a la actualización

Azure Functions proporciona un validador previo a la actualización para ayudarle a identificar posibles problemas al migrar la aplicación de funciones a la versión 4.x. Para ejecutar el validador previo a la actualización:

  1. Vaya a la aplicación de funciones en Azure Portal.

  2. Abra la hoja Diagnosticar y solucionar problemas.

  3. En Diagnósticos de la aplicación de funciones, empiece a escribir Functions 4.x Pre-Upgrade Validator y, luego, selecciónelo en la lista.

  4. Una vez completada la validación, revise las recomendaciones y solucione los problemas de la aplicación. Si necesita realizar cambios en la aplicación, asegúrese de validar los cambios con la versión 4.x del entorno de ejecución de Functions, ya sea localmente mediante Azure Functions Core Tools v4 o mediante un espacio de ensayo.

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 importantes entre 3.x y 4.x

A continuación se indican los principales cambios importantes que se deben tener en cuenta antes de actualizar una aplicación 3.x a 4.x, incluidos los cambios importantes específicos de cada idioma. Para obtener una lista completa, consulte las incidencias del repositorio de Azure Functions en GitHub que tienen la etiqueta Breaking Change: Approved (Cambio importante: aprobado).

Si no ve su lenguaje de programación, selecciónelo en la parte superior de la página.

Tiempo de ejecución

  • Azure Functions Proxies es una característica heredada en las versiones 1.x a 3.x del entorno de ejecución de Azure Functions. La compatibilidad con Functions Proxies se puede volver a habilitar en la versión 4.x para que pueda actualizar correctamente las aplicaciones de funciones a la versión más reciente del entorno de ejecución. Tan pronto como sea posible, debe cambiar a la integración de las aplicaciones de funciones con Azure API Management. API Management le permite aprovechar un conjunto más completo de características para definir, proteger, administrar y monetizar las API basadas en Functions. Para más información, consulte Integración de API Management. Para obtener información sobre cómo volver a habilitar la compatibilidad con Proxies en la versión 4.x de Functions, consulte Volver a habilitar Proxies en Functions v4.x.

  • El registro en Azure Storage con AzureWebJobsDashboard ya no se admite en la versión 4.x. En su lugar, debe usar Application Insights. (#1923)

  • Azure Functions 4.x ahora aplica requisitos de versión mínima para las extensiones. Actualice a la versión más reciente de las extensiones afectadas. Para lenguajes que no son .NET, actualice a la versión 2.x del conjunto de extensiones o a una versión posterior. (#1987)

  • Ahora, en 4.x se aplican tiempos de espera predeterminado y máximo para aplicaciones de funciones que se ejecutan en Linux en un plan de consumo. (#1915)

  • Azure Functions 4.x usa Azure.Identity y Azure.Security.KeyVault.Secrets para el proveedor de Key Vault y ha dejado de usar Microsoft.Azure.KeyVault. Para obtener más información sobre cómo configurar las opciones de la aplicación de funciones, vea la opción Key Vault en Administración del almacenamiento de claves. (#2048)

  • Las aplicaciones de funciones que comparten cuentas de almacenamiento no se inician si sus identificadores de host son iguales. Para más información, vea Consideraciones sobre el id. de host. (#2049)

  • Azure Functions 4.x admite versiones más recientes de .NET. Consulte Idiomas admitidos en Azure Functions para obtener una lista completa de las versiones.

  • InvalidHostServicesException ahora es un error irrecuperable. (#2045)

  • EnableEnhancedScopes se habilita de forma predeterminada. (#1954)

  • Quite HttpClient como servicio registrado. (#1911)

  • Use un cargador de clase única en Java 11. (#1997)

  • Detenga la carga de archivos JAR de trabajo en Java 8. (#1991)

  • Las versiones de Node.js 10 y 12 no se admiten en Azure Functions 4.x. (#1999)

  • La serialización de salida en aplicaciones de Node.js se actualizó para solucionar las incoherencias anteriores. (#2007)

  • Se ha actualizado el recuento de subprocesos predeterminado. Las funciones que no son seguras para subprocesos o que tienen un uso elevado de memoria pueden resultar afectadas. (#1962)

  • Python 3.6 no se admite en Azure Functions 4.x. (#1999)

  • La transferencia de memoria compartida está habilitada de manera predeterminada. (#1973)

  • Se ha actualizado el recuento de subprocesos predeterminado. Las funciones que no son seguras para subprocesos o que tienen un uso elevado de memoria pueden resultar afectadas. (#1962)

Pasos siguientes

Más información sobre las versiones de Functions