Partage via

Migrer des applications d’Azure Functions version 1.x vers la version 4.x

  • Article

Important

Java n’est pas pris en charge par la version 1.x du runtime Azure Functions. Vous cherchez peut-être plutôt à migrer votre application Java de la version 3.x vers la version 4.x. Si vous migrez une application de fonction version 1.x, sélectionnez C# ou JavaScript ci-dessus.

Important

TypeScript n’est pas pris en charge par la version 1.x du runtime Azure Functions. Vous cherchez peut-être plutôt à migrer votre application TypeScript de la version 3.x vers la version 4.x. Si vous migrez une application de fonction version 1.x, sélectionnez C# ou JavaScript ci-dessus.

Important

PowerShell n’est pas pris en charge par la version 1.x du runtime Azure Functions. Vous cherchez peut-être plutôt à migrer votre application PowerShell de la version 3.x vers la version 4.x. Si vous migrez une application de fonction version 1.x, sélectionnez C# ou JavaScript ci-dessus.

Important

Python n’est pas pris en charge par la version 1.x du runtime Azure Functions. Vous cherchez peut-être plutôt à migrer votre application Python de la version 3.x vers la version 4.x. Si vous migrez une application de fonction version 1.x, sélectionnez C# ou JavaScript ci-dessus.

Important

La prise en charge de la version 1.x du runtime Azure Functions prendra fin le 14 septembre 2026. Nous vous recommandons vivement de migrer vos applications vers la version 4.x en suivant les instructions de cet article.

Cet article vous guide tout au long du processus de migration, de manière sécurisée, de votre application de fonction pour qu’elle s’exécute sur la version 4.x du runtime Functions. Étant donné que les instructions de migration du projet dépendent du langage, veillez à choisir votre langage de développement à l’aide du sélecteur en haut de l’article.

Si vous exécutez la version 1.x du runtime dans Azure Stack Hub, consultez d’abord les Considérations relatives à Azure Stack Hub .

Identifier les applications de fonction à migrer

Utilisez le script PowerShell suivant pour générer une liste d’applications de fonction dans votre abonnement qui ciblent actuellement la version 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

Choisissez votre version cible de .NET

Sur la version 1.x du runtime Functions, votre application de fonction C# cible .NET Framework.

Lorsque vous migrez votre application de fonction, vous avez la possibilité de choisir la version cible de .NET. Vous pouvez mettre à jour votre projet C# vers l’une des versions suivantes de .NET, qui sont prises en charge par Functions version 4.x :

Version de .NET Type de version de la politique de prise en charge officielle .NET Modèle de processus Functions1,2
.NET 9 Préversion3 Modèle de worker isolé
.NET 8 LTS (fin du support le 10 novembre 2026) Modèle de worker isolé,
Modèle In-process2
.NET 6 LTS (fin de la prise en charge le 12 novembre 2024) Modèle de worker isolé,
Modèle In-process2
.NET Framework 4.8 Consulter la stratégie Modèle de worker isolé

1 Le modèle de worker isolé prend en charge les versions LTS (Long Term Support) et STS (Standard Term Support) de .NET, ainsi que .NET Framework. Le modèle In-process ne prend en charge que les versions LTS de .NET, jusqu’à .NET 8. Pour une comparaison complète des caractéristiques et des fonctionnalités entre les deux modèles, consultez Différences entre les processus .NET in-process et les processus de travail isolés Azure Functions.

2 Le support du modèle In-process prendra fin le 10 novembre 2026. Pour plus d’informations, lisez cette annonce relative à la prise en charge. Pour continuer à bénéficier d’une prise en charge complète, vous devez migrer vos applications vers le modèle Worker isolé.

3 Pour plus d’informations sur le support, les restrictions actuelles et les instructions d’utilisation de la préversion, consultez les Préversions de .NET dans le modèle de Worker isolé.

Conseil

À moins que votre application ne dépende d’une bibliothèque ou d’une API uniquement disponible pour .NET Framework, nous vous recommandons de mettre à jour vers .NET 8 sur le modèle de travail isolé. De nombreuses applications de la version 1.x ciblent le .NET Framework uniquement, car c’était l’option disponible lors de leur création. Des fonctionnalités supplémentaires sont disponibles pour les versions plus récentes de .NET et, si votre application n’est pas contrainte de rester sur le .NET Framework en raison d’une dépendance, vous devez cibler une version plus récente. .NET 8 est la version entièrement publiée avec la fenêtre de support la plus longue à partir de .NET.

Bien que vous puissiez choisir d’utiliser le modèle in-process, cela n’est pas recommandé si cela peut être évité. La prise en charge du modèle in-process prendra fin le 10 novembre 2026 ; vous devrez donc passer au modèle Worker isolé avant cette date. Le faire lors de la migration vers la version 4.x réduira l’effort total requis, et le modèle Worker isolé offrira à votre application des avantages supplémentaires, notamment la capacité à cibler plus facilement les futures versions de .NET. Si vous passez au modèle Worker isolé, l’Assistant Mise à niveau .NET peut également gérer bon nombre des modifications de code nécessaires pour vous.

Ce guide ne présente pas d’exemples spécifiques pour .NET 6. Si vous devez cibler cette version, vous pouvez adapter les exemples .NET 8.

Préparation de la migration

Si ce n’est pas déjà fait, identifiez la liste des applications qui doivent être migrées dans votre abonnement Azure actuel à l’aide d’Azure PowerShell.

Avant de migrer une application vers la version 4.x du runtime Functions, vous devez effectuer les tâches suivantes :

  1. Passez en revue la liste des changements de comportement après la version 1.x. La migration de la version 1.x vers la version 4.x peut également affecter les liaisons.
  2. Effectuez les étapes décrites dans Migrer votre projet local pour migrer votre projet local vers la version 4.x.
  3. Après avoir migré votre projet, testez entièrement l’application localement à l’aide de la version 4.x d’Azure Functions Core Tools.
  4. Mettez à jour votre application de fonction dans Azure vers la nouvelle version. Si vous devez réduire les temps d’arrêt, utilisez un emplacement de préproduction pour tester et vérifier votre application migrée dans Azure sur la nouvelle version du runtime. Vous pouvez ensuite déployer votre application avec les paramètres de version mis à jour sur l’emplacement de production. Pour plus d’informations, consultez Mettre à jour à l’aide d’emplacements.
  5. Publiez votre projet migré vers l’application de fonction mise à jour.

Lorsque vous utilisez Visual Studio pour publier un projet version 4.x sur une application de fonction existante qui a une version inférieure, vous êtes invité à laisser Visual Studio mettre à jour l’application de fonction vers la version 4.x pendant le déploiement. Cette mise à jour utilise le même processus que celui défini dans Mettre à jour sans emplacements.

Migrer votre projet local

Les sections suivantes décrivent les mises à jour que vous devez apporter à vos fichiers projet C# pour qu’ils puissent s’exécuter sur l’une des versions prises en charge de .NET dans Functions version 4.x. Les mises à jour indiquées sont communes à la plupart des projets. Le code de votre projet peut nécessiter des mises à jour qui ne sont pas mentionnées dans cet article, en particulier lorsque vous utilisez des paquets NuGet personnalisés.

La migration d’une application de fonction C# de la version 1.x vers la version 4.x du runtime Functions vous oblige à apporter des modifications au code de votre projet. La plupart de ces modifications sont la conséquence de modifications apportées au langage C# et aux API .NET.

Choisissez l’onglet qui correspond à votre version cible de .NET et au modèle de processus souhaité (in-process ou processus Worker isolé).

Conseil

Si vous passez à une version LTS ou STS de .NET à l’aide du modèle Worker isolé, vous pouvez utiliser l’Assistant Mise à niveau .NET pour apporter automatiquement bon nombre des modifications mentionnées dans les sections suivantes.

Fichier projet

L'exemple suivant est un .csproj fichier de projet qui fonctionne avec la version 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>

Appliquez l’une des procédures suivantes pour mettre à jour ce fichier XML afin qu’il s’exécute dans Functions version 4.x :

Ces étapes supposent un projet C# local, et si votre application utilise plutôt un script C# (fichiers .csx), vous devez convertir en modèle de projet avant de continuer.

Les modifications suivantes sont requises dans le fichier projet XML .csproj :

  1. Définissez la valeur de PropertyGroup.TargetFramework en net8.0.

  2. Définissez la valeur de PropertyGroup.AzureFunctionsVersion en v4.

  3. Ajoutez l’élément OutputType suivant au PropertyGroup :

    <OutputType>Exe</OutputType>

  4. Dans la liste ItemGroup.PackageReference, remplacez la référence de package par Microsoft.NET.Sdk.Functions avec les références suivantes :

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

    Notez toute référence à d’autres packages dans les espaces de noms Microsoft.Azure.WebJobs.*. Vous remplacerez ces packages dans une étape ultérieure.

  5. Ajoutez le nouveau ItemGroup suivant :

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

Une fois ces modifications effectuées, votre projet mis à jour doit ressembler à l’exemple suivant :

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

Modifications apportées aux packages et aux espaces de noms

En fonction du modèle vers lequel vous migrez, vous pourriez avoir besoin de mettre à jour ou de modifier les packages que votre application référence. Lorsque vous adoptez les packages cibles, vous devrez mettre à jour l’espace de noms des instructions using et certains types que vous référencez. Vous pouvez voir l’effet de ces modifications d’espace de noms sur les instructions using contenues dans les exemples de modèles de déclencheur HTTP plus tard dans cet article.

Si ce n’est déjà fait, mettez à jour votre projet pour référencer les dernières versions stables de :

En fonction des déclencheurs et des liaisons que votre application utilise, elle pourrait avoir besoin de référencer un ensemble de packages différent. Le tableau suivant présente des remplacements à certaines des extensions les plus couramment utilisées :

Scénario Modifications apportées aux références de package
Déclencheur de minuteur Ajouter
Microsoft.Azure.Functions.Worker.Extensions.Timer
Liaisons de stockage Replace
Microsoft.Azure.WebJobs.Extensions.Storage
par
Microsoft.Azure.Functions.Worker.Extensions.Storage.Blobs,
Microsoft.Azure.Functions.Worker.Extensions.Storage.Queues et
Microsoft.Azure.Functions.Worker.Extensions.Tables
liaisons SSL Remplacez les références à
Microsoft.Azure.WebJobs.Extensions.Storage.Blobs
par la version la plus récente de
Microsoft.Azure.Functions.Worker.Extensions.Storage.Blobs
Liaisons de la file d’attente Remplacez les références à
Microsoft.Azure.WebJobs.Extensions.Storage.Queues
par la version la plus récente de
Microsoft.Azure.Functions.Worker.Extensions.Storage.Queues
Liaisons de tableau Remplacez les références à
Microsoft.Azure.WebJobs.Extensions.Tables
par la version la plus récente de
Microsoft.Azure.Functions.Worker.Extensions.Tables
Liaisons Cosmos DB Remplacez les références à
Microsoft.Azure.WebJobs.Extensions.CosmosDB
et/ou
Microsoft.Azure.WebJobs.Extensions.DocumentDB
par la version la plus récente de
Microsoft.Azure.Functions.Worker.Extensions.CosmosDB
Liaisons Service Bus Remplacez les références à
Microsoft.Azure.WebJobs.Extensions.ServiceBus
par la version la plus récente de
Microsoft.Azure.Functions.Worker.Extensions.ServiceBus
Liaisons Event Hubs Remplacez les références à
Microsoft.Azure.WebJobs.Extensions.EventHubs
par la version la plus récente de
Microsoft.Azure.Functions.Worker.Extensions.EventHubs
Liaisons Event Grid Remplacez les références à
Microsoft.Azure.WebJobs.Extensions.EventGrid
par la version la plus récente de
Microsoft.Azure.Functions.Worker.Extensions.EventGrid
Liaisons SignalR Service Remplacez les références à
Microsoft.Azure.WebJobs.Extensions.SignalRService
par la version la plus récente de
Microsoft.Azure.Functions.Worker.Extensions.SignalRService
Fonctions durables Remplacez les références à
Microsoft.Azure.WebJobs.Extensions.DurableTask
par la version la plus récente de
Microsoft.Azure.Functions.Worker.Extensions.DurableTask
Fonctions durables
(Fournisseur de stockage SQL)		 Remplacez les références à
Microsoft.DurableTask.SqlServer.AzureFunctions
par la version la plus récente de
Microsoft.Azure.Functions.Worker.Extensions.DurableTask.SqlServer
Fonctions durables
(Fournisseur de stockage Netherite)		 Remplacez les références à
Microsoft.Azure.DurableTask.Netherite.AzureFunctions
par la version la plus récente de
Microsoft.Azure.Functions.Worker.Extensions.DurableTask.Netherite
Liaisons SendGrid Remplacez les références à
Microsoft.Azure.WebJobs.Extensions.SendGrid
par la version la plus récente de
Microsoft.Azure.Functions.Worker.Extensions.SendGrid
Liaisons Kafka Remplacez les références à
Microsoft.Azure.WebJobs.Extensions.Kafka
par la version la plus récente de
Microsoft.Azure.Functions.Worker.Extensions.Kafka
Liaisons RabbitMQ Remplacez les références à
Microsoft.Azure.WebJobs.Extensions.RabbitMQ
par la version la plus récente de
Microsoft.Azure.Functions.Worker.Extensions.RabbitMQ
Injection de dépendances
et la configuration de démarrage		 Supprimez les références à
Microsoft.Azure.Functions.Extensions
(Le modèle Worker isolé fournit cette fonctionnalité par défaut.)

Consultez les Liaisons prises en charge pour la liste complète des extensions à prendre en compte, et référez-vous à la documentation de chaque extension pour obtenir des instructions d’installation complètes du modèle de processus isolé. Veillez à installer la dernière version stable de tous les packages que vous ciblez.

Conseil

Toutes les modifications apportées aux versions d’extension pendant ce processus peuvent aussi vous obliger à mettre à jour votre fichier host.json. Veillez à lire la documentation de chaque extension que vous utilisez. Par exemple, l’extension Service Bus a des changements cassants dans la structure entre les versions 4.x et 5.x. Pour plus d’informations, consultez la section Liaisons Azure Service Bus pour Azure Functions.

Votre application de modèle Worker isolé ne doit pas référencer de packages dans l’espace de noms Microsoft.Azure.WebJobs.* ni Microsoft.Azure.Functions.Extensions. S’il reste des références à ces derniers, elles doivent être supprimées.

Conseil

Votre application peut également dépendre des types de kits de développement logiciel (SDK) Azure, soit dans le cadre de vos déclencheurs et liaisons, soit en tant que dépendance autonome. Vous devez également en profiter pour les mettre à jour. Les dernières versions des extensions Functions fonctionnent avec les dernières versions du kit de développement logiciel (SDK) Azure pour .NET, presque tous les packages dont la forme est Azure.*.

Les liaisons Notification Hubs et Mobile Apps sont prises en charge uniquement dans la version 1.x du runtime. Lors de la mise à niveau vers la version 4.x du runtime, vous devez supprimer ces liaisons pour utiliser ces services directement à l’aide de leurs Kits de développement logiciel (SDK).

Fichier Program.cs

Dans la plupart des cas, la migration vous oblige à ajouter le fichier program.cs suivant à votre projet :

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

Cet exemple inclut l’intégration d’ASP.NET Core pour améliorer les performances et fournir un modèle de programmation familier lorsque votre application utilise des déclencheurs HTTP. Si vous n’avez pas l’intention d’utiliser des déclencheurs HTTP, vous pouvez remplacer l’appel à ConfigureFunctionsWebApplication par un appel à ConfigureFunctionsWorkerDefaults. Dans ce cas, vous pouvez supprimer la référence à Microsoft.Azure.Functions.Worker.Extensions.Http.AspNetCore de votre fichier projet. Toutefois, pour des performances optimales, même pour les fonctions avec d’autres types de déclencheurs, vous devez conserver ASP.NET Core comme FrameworkReference.

Le fichier Program.cs remplace n’importe quel fichier qui a l’attribut FunctionsStartup, qui est généralement un fichier Startup.cs. Dans les endroits où votre code FunctionsStartup référence IFunctionsHostBuilder.Services, vous pouvez à la place ajouter des instructions dans la méthode .ConfigureServices() de HostBuilder dans votre Program.cs. Pour en savoir plus sur l’utilisation de Program.cs, consultez Démarrage et configuration dans le guide de modèle Worker isolé.

Les exemples Program.cs par défaut ci-dessus incluent la configuration de l’intégration d’Application Insights pour le modèle Worker isolé. Dans votre Program.cs, vous devez également configurer tout filtrage des journaux qui doit s’appliquer aux journaux provenant du code dans votre projet. Dans le modèle Worker isolé, le fichier host.json contrôle uniquement les événements émis par le runtime hôte Functions. Si vous ne configurez pas de règles de filtrage dans Program.cs, vous constaterez peut-être des différences dans les niveaux de journalisation présents pour les différentes catégories de votre télémétrie.

Bien que vous puissiez enregistrer des sources de configuration personnalisées dans le cadre du HostBuilder, notez que celles-ci s’appliquent également uniquement au code de votre projet. La configuration des déclencheurs et des liaisons est également requise par la plateforme, et elle doit être fournie via les paramètres d’application, les références Key Vault ou les fonctionnalités de références App Configuration.

Une fois que vous avez déplacé tous les éléments FunctionsStartup existants vers le fichier Program.cs, vous pouvez supprimer l’attribut FunctionsStartup et la classe à laquelle elle a été appliquée.

Fichier host.json

Les paramètres du fichier host.json s’appliquent au niveau de l’application de fonction, à la fois localement et dans Azure. Dans la version 1.x, votre fichier host.json est vide ou contient des paramètres qui s’appliquent à toutes les fonctions de l’application de fonction. Pour plus d’informations, consultez Host.json v1. Si votre fichier host.json contient des valeurs de paramètre, passez en revue le format host.json v2 pour toute modification.

Pour une exécution sur la version 4.x, vous devez ajouter "version": "2.0" au fichier host.json. Vous devez également envisager d’ajouter logging à votre configuration, comme dans les exemples suivants :

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

Le fichier host.json contrôle uniquement la journalisation à partir du runtime de l’hôte Functions, et dans le modèle Worker isolé, certains de ces journaux proviennent directement de votre application, vous donnant plus de contrôle. Voir Gestion des niveaux de journaux dans le modèle de travailleur isolé pour plus de détails sur la façon de filtrer ces journaux.

Fichier local.settings.json

Le fichier local.settings.json est uniquement utilisé lors de l’exécution locale. Pour en savoir plus, consultez Fichier de paramètres locaux. Dans la version 1.x, le fichier local.settings.json a seulement deux valeurs requises :

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

Lorsque vous effectuez une migration vers la version 4.x, vérifiez que votre fichier local.settings.json contient au moins les éléments suivants :

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

Remarque

Lors de la migration d’un processus d’exécution In-process vers un processus d’exécution Worker isolé, vous devez passer la valeur FUNCTIONS_WORKER_RUNTIME à « dotnet-isolated ».

Modifications de nom de classe

Certaines classes principales ont changé de nom entre la version 1.x et la version 4.x. Ces modifications sont la conséquence de modifications apportées aux API .NET ou de différences entre l’exécution in-process et le processus Worker isolé. Le tableau suivant indique les classes principales .NET utilisées par Functions qui sont susceptibles de changer lors de la migration :

Version 1.x .NET 8
FunctionName (attribut) Function (attribut)
TraceWriter ILogger<T>, ILogger
HttpRequestMessage HttpRequestData, HttpRequest (à l’aide de l’intégration ASP.NET Core)
HttpResponseMessage HttpResponseData, IActionResult (à l’aide de l’intégration ASP.NET Core)

Il peut également y avoir des différences de nom de classe dans les liaisons. Pour plus d’informations, consultez les articles de référence relatifs aux liaisons en question.

Autres modifications du code

Cette section met en évidence d’autres modifications de code à prendre en compte lors de la migration. Ces modifications ne sont pas nécessaires à toutes les applications, mais vous devez évaluer si certaines sont pertinentes pour vos scénarios. Assurez-vous de vérifier les modifications de comportement après la version 1.x pour connaître les modifications supplémentaires que vous devrez peut-être apporter à votre projet.

Sérialisation JSON

Par défaut, le modèle Worker isolé utilise System.Text.Json pour la sérialisation JSON. Pour personnaliser les options de sérialiseur ou passer à JSON.NET (Newtonsoft.Json), consultez ces instructions.

Niveaux de journalisation et filtrage Application Insights

Les journaux peuvent être envoyés à Application Insights à partir du runtime de l’hôte Functions et du code de votre projet. Le host.json vous permet de configurer des règles pour la journalisation de l’hôte, mais pour contrôler les journaux provenant de votre code, vous devrez configurer des règles de filtrage dans le cadre de votre Program.cs. Voir Gestion des niveaux de journaux dans le modèle de travailleur isolé pour plus de détails sur la façon de filtrer ces journaux.

Modèle de déclencheur HTTP

La plupart des modifications de code entre la version 1.x et la version 4.x sont visibles dans les fonctions déclenchées par HTTP. Le modèle de déclencheur HTTP pour la version 1.x ressemble à l’exemple suivant :

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

Dans la version 4.x, le modèle de déclencheur HTTP ressemble à l’exemple suivant :

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"]}!");
        }
    }
}

Pour mettre à jour votre projet vers Azure Functions 4.x :

  1. Mettez à jour votre installation locale de Azure Functions Core Tools vers la version 4.x.

  2. Passez à l’une des versions Node.js prises en charge sur la version 4.x.

  3. Ajoutez des éléments version et extensionBundle au fichier host.json afin qu’il ressemble à l’exemple suivant :

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

    L’élément extensionBundle est obligatoire, car après la version 1.x, les liaisons sont conservées en tant que packages externes. Pour plus d’informations, consultez Bundles d’extension.

  4. Mettez à jour votre fichier local.settings.json afin qu’il comporte au moins les éléments suivants :

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

    Le paramètre AzureWebJobsStorage peut être l’émulateur de stockage Azurite ou un compte Stockage Azure réel. Pour plus d’informations, consultez Émulateur de stockage local.

Mettre à jour votre application de fonction dans Azure

Vous devez mettre à jour le runtime de l’hôte d’application de fonction dans Azure vers la version 4.x avant de publier votre projet migré. La version du runtime utilisée par l’hôte Functions est contrôlée par le paramètre d’application FUNCTIONS_EXTENSION_VERSION, mais dans certains cas d’autres paramètres doivent également être mis à jour. Les modifications de code et les modifications apportées aux paramètres d’application nécessitent le redémarrage de votre application de fonction.

Le moyen le plus simple de procéder consiste à mettre à jour sans emplacements, puis à republier votre projet d’application. Vous pouvez également réduire le temps d’arrêt dans votre application et simplifier la restauration en effectuant une mise à jour à l’aide d’emplacements.

Mettre à jour sans emplacements

Le moyen le plus simple de mettre à jour vers la version v4.x consiste à affecter la valeur ~4 au paramètre d’application FUNCTIONS_EXTENSION_VERSION sur votre application de fonction dans Azure. Vous devez suivre une procédure différente sur un site avec des emplacements.

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

Vous devez également définir un autre paramètre, qui diffère entre Windows et Linux.

Lors de l’exécution sur Windows, vous devez également activer .NET 6.0, qui est requis par la version 4.x du runtime.

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

.NET 6 est nécessaire pour les applications de fonction dans n’importe quel langage s’exécutant sur Windows.

Dans cet exemple, remplacez <APP_NAME> par le nom de votre application de fonction, et <RESOURCE_GROUP_NAME> par le nom du groupe de ressources.

Vous pouvez maintenant republier votre projet d’application qui a été migré pour s’exécuter sur la version 4.x.

Mettre à jour à l’aide d’emplacements

L’utilisation d’emplacements de déploiement est un bon moyen de mettre à jour votre application de fonction vers le runtime v4.x à partir d’une version précédente. À l’aide d’un emplacement de préproduction, vous pouvez exécuter votre application sur la nouvelle version du runtime dans l’emplacement de préproduction et basculer vers la production après vérification. Les emplacements permettent également de réduire les temps d’arrêt pendant la mise à jour. Si vous devez réduire au maximum les temps d’arrêt, suivez les étapes de Mise à jour avec un minimum de temps d’arrêt.

Une fois que vous avez vérifié votre application dans l’emplacement mis à jour, vous pouvez basculer l’application et les nouveaux paramètres de version en production. Cet échange nécessite un paramètre WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS=0 dans l’emplacement de production. La façon dont vous ajoutez ce paramètre affecte la durée de temps d’arrêt nécessaire pour la mise à jour.

Mise à jour standard

Si votre application de fonction avec emplacement peut gérer le temps d’arrêt d’un redémarrage complet, vous pouvez mettre à jour le paramètre WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS directement dans l’emplacement de production. Étant donné que la modification de ce paramètre directement dans l’emplacement de production entraîne un redémarrage qui a un impact sur la disponibilité, envisagez de procéder à cette modification au moment de la réduction du trafic. Vous pouvez ensuite permuter la version mise à jour à partir de l’emplacement de préproduction.

L’applet de commande PowerShell Update-AzFunctionAppSetting ne prend pas actuellement en charge les emplacements. Vous devez utiliser Azure CLI ou le portail Azure.

  1. Utilisez la commande suivante pour définir WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS=0 dans l’emplacement de production :

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

    Dans cet exemple, remplacez <APP_NAME> par le nom de votre application de fonction, et <RESOURCE_GROUP_NAME> par le nom du groupe de ressources. Cette commande entraîne le redémarrage de l’application dans l’emplacement de production.

  2. Utilisez la commande suivante pour définir également WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS dans l’emplacement de préproduction :

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

  3. Utilisez la commande suivante pour modifier FUNCTIONS_EXTENSION_VERSION et mettre à jour l’emplacement de préproduction vers la nouvelle version du runtime :

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

  4. La version 4.x du runtime Functions nécessite .NET 6 dans Windows. Sur Linux, les applications .NET doivent également être mises à jour vers .NET 6. Utilisez la commande suivante pour que le runtime puisse s’exécuter sur .NET 6 :

    Lors de l’exécution sur Windows, vous devez également activer .NET 6.0, qui est requis par la version 4.x du runtime.

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

    .NET 6 est nécessaire pour les applications de fonction dans n’importe quel langage s’exécutant sur Windows.

    Dans cet exemple, remplacez <APP_NAME> par le nom de votre application de fonction, et <RESOURCE_GROUP_NAME> par le nom du groupe de ressources.

  5. Si votre projet de code nécessite des mises à jour à exécuter sur la version 4.x, déployez ces mises à jour sur l’emplacement de préproduction maintenant.

  6. Vérifiez que votre application de fonction s’exécute correctement dans l’environnement intermédiaire mis à jour avant d’effectuer la permutation.

  7. Utilisez la commande suivante pour faire basculer l’emplacement de préproduction mis à jour en production :

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

Mise à jour avec un minimum de temps d’arrêt

Pour réduire le temps d’arrêt dans votre application de production, vous pouvez échanger le paramètre WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS de l’emplacement de préproduction en production. Après cela, vous pouvez permuter la version mise à jour à partir d’un emplacement de préproduction préchauffé.

  1. Utilisez la commande suivante pour définir WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS=0 dans l’emplacement de préproduction :

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

  2. Utilisez les commandes suivantes pour permuter l’emplacement avec le nouveau paramètre en production, et en même temps restaurer le paramètre de version dans l’emplacement de préproduction.

    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>

    Vous pouvez rencontrer des erreurs à partir de l’emplacement de préproduction pendant le délai entre l’échange et la version du runtime restaurée dans l’emplacement de préproduction. Cette erreur peut se produire, car avoir WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS=0 uniquement en préproduction pendant un échange supprime le paramètre FUNCTIONS_EXTENSION_VERSION dans l’emplacement de préproduction. Sans le paramètre de version, votre emplacement est dans un état incorrect. La mise à jour de la version dans l’emplacement de préproduction juste après l’échange doit remettre l’emplacement dans un état correct et vous pouvez restaurer vos modifications si nécessaire. Toutefois, toute restauration de l’échange vous oblige également à supprimer WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS=0 directement de l’emplacement de production avant le retour de l’échange pour éviter les mêmes erreurs de production que celles observées en préproduction. Cette modification dans le paramètre de production entraîne alors un redémarrage.

  3. Utilisez la commande suivante pour à nouveau définir WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS=0 dans l’emplacement de préproduction :

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

    À ce stade, WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS=0 est défini dans les deux emplacements.

  4. Utilisez la commande suivante pour modifier FUNCTIONS_EXTENSION_VERSION et mettre à jour l’emplacement de préproduction vers la nouvelle version du runtime :

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

  5. La version 4.x du runtime Functions nécessite .NET 6 dans Windows. Sur Linux, les applications .NET doivent également être mises à jour vers .NET 6. Utilisez la commande suivante pour que le runtime puisse s’exécuter sur .NET 6 :

    Lors de l’exécution sur Windows, vous devez également activer .NET 6.0, qui est requis par la version 4.x du runtime.

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

    .NET 6 est nécessaire pour les applications de fonction dans n’importe quel langage s’exécutant sur Windows.

    Dans cet exemple, remplacez <APP_NAME> par le nom de votre application de fonction, et <RESOURCE_GROUP_NAME> par le nom du groupe de ressources.

  6. Si votre projet de code nécessite des mises à jour à exécuter sur la version 4.x, déployez ces mises à jour sur l’emplacement de préproduction maintenant.

  7. Vérifiez que votre application de fonction s’exécute correctement dans l’environnement intermédiaire mis à jour avant d’effectuer la permutation.

  8. Utilisez la commande suivante pour faire basculer l’emplacement de préproduction mis à jour et préchauffé en production :

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

Changements de comportement après la version 1.x

Cette section détaille les modifications apportées après la version 1.x aux comportements des déclencheurs et des liaisons, ainsi qu’aux principales fonctionnalités et comportements de Functions.

Modifications dans les déclencheurs et les liaisons

À compter de la version 2.x, vous devez installer dans votre application les extensions pour les déclencheurs et les liaisons spécifiques utilisés par les fonctions. La seule exception concerne les déclencheurs HTTP et de la minuterie, qui ne nécessitent aucune extension. Pour plus d’informations, voir Inscrire et installer des extensions de liaison.

Il convient également de noter quelques modifications dans function.json ou dans les attributs de la fonction entre les versions. Par exemple, la propriété path d’Event Hubs est désormais eventHubName. Consultez le tableau des liaisons existantes. Il contient des liens vers de la documentation sur chaque liaison.

Changements apportés aux fonctionnalités

Quelques fonctionnalités ont été supprimées, mises à jour ou remplacées après la version 1.x. Cette section détaille les changements que vous voyez dans les versions ultérieures après avoir utilisé la version 1.x.

Les modifications suivantes ont été apportées à la version 2.x :

  • Les clés permettant d’appeler les points de terminaison HTTP sont toujours stockées et chiffrées dans le Stockage Blob Azure. Dans la version 1.x, les clés étaient stockées par défaut dans Azure Files. Lorsque vous migrez une application de la version 1.x vers la version 2.x, les secrets existants qui se trouvent dans Azure Files sont réinitialisés.

  • La version 2.x du runtime n’intègre aucune prise en charge des fournisseurs de webhooks. Cette modification a été apportée pour améliorer les performances. Vous pouvez continuer à utiliser des déclencheurs HTTP comme points de terminaison des webhooks.

  • Pour améliorer la surveillance, le tableau de bord WebJobs se trouvant dans le portail, qui a utilisé le paramètre AzureWebJobsDashboard, est remplacé par Azure Application Insights, qui utilise le paramètre APPINSIGHTS_INSTRUMENTATIONKEY. Pour plus d’informations, consultez Surveiller l’exécution des fonctions Azure.

  • Toutes les fonctions d’une application de fonction doivent partager le même langage. Lorsque vous créez une application de fonction, vous devez choisir une pile d’exécution pour l’application. La pile d’exécution est spécifiée par la valeur FUNCTIONS_WORKER_RUNTIME dans les paramètres de l’application. Cette exigence a été ajoutée pour améliorer l’empreinte mémoire et le temps de démarrage. Lorsque vous développez en local, vous devez également inclure ce paramètre dans le fichier local.settings.json.

  • Le délai d’expiration par défaut pour les fonctions dans un plan App Service est de 30 minutes. Vous pouvez modifier ce délai d’expiration manuellement et l’indiquer à nouveau comme étant illimité en utilisant le paramètre functionTimeout dans host.json.

  • Les limitations d’accès concurrentiel HTTP sont implémentées par défaut pour les fonctions de plan Consommation, avec une valeur par défaut de 100 requêtes simultanées par instance. Vous pouvez configurer ce comportement dans le paramètre maxConcurrentRequests du fichier host.json.

  • En raison des limitations de .NET Core, la prise en charge des fonctions de script F# (fichiers .fsx) a été supprimée. Les fonctions F# compilées (.fs) restent prises en charge.

  • Le format d’URL des webhooks de déclencheur Event Grid a été remplacé pour suivre ce modèle : https://{app}/runtime/webhooks/{triggerName}.

  • Les noms de certaines métriques personnalisées prédéfinies ont été modifiés après la version 1.x. Duration a été remplacé par MaxDurationMs, MinDurationMs et AvgDurationMs. Success Rate a également été renommé Success Rate.

Considérations relatives à Azure Stack Hub

App Service sur Azure Stack Hub ne prend pas en charge la version 4.x de Azure Functions. Lorsque vous planifiez une migration à partir de la version 1.x dans Azure Stack Hub, vous pouvez choisir l’une des options suivantes :

  • Migrez vers la version 4.x hébergée dans le cloud public Azure Functions en suivant les instructions de cet article. Au lieu de mettre à niveau votre application existante, vous devez créer une application à l’aide de la version 4.x, puis y déployer votre projet modifié.
  • Basculez vers webJobs hébergés sur un plan App Service dans Azure Stack Hub.

Étapes suivantes

En savoir plus sur les versions de Functions