Partager via

Guide pour l’exécution d’Azure Functions C# dans le modèle de worker isolé

Cet article présente l’utilisation d’Azure Functions dans .NET à l’aide du modèle worker isolé. Ce modèle permet à votre projet de cibler des versions de .NET indépendamment des autres composants d'exécution. Pour plus d’informations sur les versions .NET spécifiques prises en charge, consultez Version prise en charge.

Utilisez les liens suivants pour commencer immédiatement à créer des fonctions de modèles Worker isolés .NET.

Prise en main Les concepts Exemples

Pour en savoir plus sur le déploiement d’un projet de modèle worker isolé sur Azure, consultez Déployer sur Azure Functions.

Avantages du modèle Worker isolé

Vous pouvez exécuter vos fonctions de bibliothèque de classes .NET en deux modes : dans le même processus que le runtime hôte Functions (in-process) ou dans un processus worker isolé. Lorsque vos fonctions .NET sont exécutées dans un processus worker isolé, vous pouvez tirer parti des avantages suivants :

  • Moins de conflits : vos fonctions s’exécutant dans un processus distinct, les assemblys utilisés dans votre application ne sont pas en conflit avec des versions différentes des mêmes assemblys utilisés par le processus hôte.
  • Contrôle total du processus : vous contrôlez le démarrage de l’application, ce qui signifie que vous pouvez gérer les configurations utilisées et l’intergiciel démarré.
  • Injection de dépendances standard : étant donné que vous contrôlez totalement le processus, vous pouvez utiliser les comportements .NET actuels pour injecter des dépendances et incorporer l’intergiciel dans votre application de fonction.
  • Flexibilité de la version .NET : l’exécution en dehors du processus hôte signifie que vos fonctions peuvent s’exécuter sur des versions de .NET non prises en charge en mode natif par le runtime Functions, y compris le .NET Framework.

Si vous avez une application de fonction C# existante qui s’exécute in-process, vous devez migrer votre application pour tirer parti de ces avantages. Pour plus d’informations, consultez Migrer des applications .NET du modèle in-process vers le modèle Worker isolé.

Pour obtenir une comparaison complète des deux modèles, consultez Différences entre les processus .NET in-process et les processus Worker isolés Azure Functions.

Versions prises en charge

Les versions du runtime Functions prennent en charge des versions spécifiques de .NET. Pour en savoir plus sur les versions de Functions, consultez Vue d’ensemble des versions du runtime Azure Functions. La prise en charge de version dépend également de si vos fonctions s’exécutent au sein d’un processus ou dans un processus Worker isolé.

Remarque

Pour savoir comment modifier la version du runtime Functions utilisée par votre application de fonction, consultez Afficher et mettre à jour la version actuelle du runtime.

Le tableau suivant montre le niveau le plus élevé de .NET ou .NET Framework qui peut être utilisé avec une version spécifique de Functions.

Version du runtime Functions Modèle Worker isolé Modèle In-process4
Functions 4.x1 .NET 105
.NET 9.0
.NET 8.0
.NET Framework 4.82		 .NET 8.0
Fonctions 1.x3 n/a .NET Framework 4.8

1 .NET 6 était précédemment pris en charge sur les deux modèles, mais a atteint la fin du support officiel le 12 novembre 2024. .NET 7 a été précédemment pris en charge sur le modèle de travail isolé, mais a atteint la fin du support officiel le 14 mai 2024.

2 Le processus de génération nécessite également le kit de développement logiciel (SDK) .NET.

3 La prise en charge de la version 1.x du runtime Azure Functions prendra fin le 14 septembre 2026. Pour plus d’informations, lisez cette annonce relative à la prise en charge. Pour une prise en charge complète continue, vous devez migrer vos applications vers la version 4.x.

4 La prise en charge 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é.

5 Vous ne pouvez pas exécuter d’applications .NET 10 sur Linux dans le plan Consommation. Pour s’exécuter sur Linux, vous devez utiliser plutôt le plan Flex Consumption.

Pour obtenir les dernières informations sur les versions Azure Functions, notamment sur la suppression des versions mineures les plus anciennes, surveillez les annonces Azure App Service.

Structure de projet

Un projet .NET pour Azure Functions qui utilise le modèle worker isolé est essentiellement un projet d’application console .NET qui cible un runtime .NET pris en charge. Les fichiers suivants sont les fichiers de base requis dans n’importe quel projet isolé .NET :

  • Fichier projet C# (.csproj) définissant le projet et les dépendances.
  • Fichier Program.cs correspondant au point d’entrée de l’application.
  • Tous les fichiers de code définissant vos fonctions.
  • Fichier host.json qui définit la configuration partagée par les fonctions de votre projet.
  • Fichier local.settings.json qui définit les variables d’environnement utilisées par votre projet lors de l’exécution locale sur votre ordinateur.

Pour obtenir des exemples complets, consultez l’exemple de projet .NET 8 et l’exemple de projet .NET Framework 4.8.

Références de package

Un projet .NET pour Azure Functions qui utilise le modèle worker isolé emploie un ensemble unique de packages, à la fois pour les fonctionnalités principales et pour les extensions de liaison.

Packages principaux

Pour exécuter vos fonctions .NET dans un processus de travail isolé, vous avez besoin des packages suivants :

Les versions minimales de ces packages dépendent de votre version .NET cible :

Version de .NET Microsoft.Azure.Functions.Worker Microsoft.Azure.Functions.Worker.Sdk
.NET 10 2.50.0 ou version ultérieure 2.0.5 ou version ultérieure
.NET 9 2.0.0 ou version ultérieure 2.0.0 ou version ultérieure
.NET 8 1.16.0 ou version ultérieure 1.11.0 ou version ultérieure
.NET Framework 1.16.0 ou version ultérieure 1.11.0 ou version ultérieure

Version 2.x

Les versions 2.x des packages principaux modifient les infrastructures prises en charge et prennent en charge les nouvelles API .NET de ces versions ultérieures. Lors de la mise à jour vers les versions 2.x, notez les changements suivants :

  • À compter de la version 2.0.0 de Microsoft.Azure.Functions.Worker.Sdk :
  • À compter de la version 2.0.0 de Microsoft.Azure.Functions.Worker :
    • Cette version ajoute la prise en charge de IHostApplicationBuilder. Certains exemples de ce guide incluent des onglets pour afficher des alternatives avec IHostApplicationBuilder. Ces exemples nécessitent les versions 2.x.
    • La validation de l’étendue du fournisseur de services est incluse par défaut si l’exécution a lieu dans un environnement de développement. Ce comportement correspond à celui d’ASP.NET Core.
    • L’option EnableUserCodeException est activée par défaut. La propriété est désormais marquée comme étant obsolète.
    • L’option IncludeEmptyEntriesInMessagePayload est activée par défaut. Lorsque cette option est activée, les charges utiles des déclencheurs qui représentent des collections incluent toujours des entrées vides. Par exemple, si un message est envoyé sans corps, une entrée vide est toujours présente string[] pour les données du déclencheur. L’inclusion d’entrées vides facilite le référencement croisé avec les tableaux de métadonnées que la fonction peut également référencer. Vous pouvez désactiver ce comportement en définissant IncludeEmptyEntriesInMessagePayload sur false dans la configuration du service WorkerOptions.
    • La classe ILoggerExtensions est renommée FunctionsLoggerExtensions. Le changement de nom évite une erreur d’appel ambiguë lors de l’utilisation de LogMetric() sur une instance ILogger.
    • Pour les applications qui utilisent HttpResponseData, la méthode WriteAsJsonAsync() ne définit plus le code 200 OK d’état. Dans la version 1.x, ce comportement a dépassé les autres codes d’erreur que vous avez définis.
  • Les versions 2.x suppriment la prise en charge de .NET 5 TFM.

Packages d'extension

Comme les fonctions de processus de travail isolé de .NET utilisent différents types de liaison, elles nécessitent un ensemble unique de paquets d’extension de liaison.

Vous trouverez ces packages d’extension sous Microsoft.Azure.Functions.Worker.Extensions.

Démarrage et configuration

Lorsque vous utilisez le modèle de Worker isolé, vous avez accès au démarrage de votre application de fonction, qui se trouve généralement dans Program.cs. Vous devez créer et démarrer votre propre instance d’hôte. Ainsi, vous disposez également d’un accès direct au pipeline de configuration de votre application. Avec le processus de travail isolé .NET Functions, vous pouvez beaucoup plus facilement ajouter des configurations, injecter des dépendances et exécuter votre propre intergiciel.

Pour utiliser IHostApplicationBuilder, votre application doit utiliser la version 2.x ou ultérieure des packages principaux.

Le code suivant présente un exemple de pipeline IHostApplicationBuilder :

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

var builder = FunctionsApplication.CreateBuilder(args);

builder.Services
    .AddApplicationInsightsTelemetryWorkerService()
    .ConfigureFunctionsApplicationInsights();

builder.Logging.Services.Configure<LoggerFilterOptions>(options =>
    {
        // The Application Insights SDK adds a default logging filter that instructs ILogger to capture only Warning and more severe logs. Application Insights requires an explicit override.
        // Log levels can also be configured using appsettings.json. For more information, see https://learn.microsoft.com/azure/azure-monitor/app/worker-service#ilogger-logs
        LoggerFilterRule defaultRule = options.Rules.FirstOrDefault(rule => rule.ProviderName
            == "Microsoft.Extensions.Logging.ApplicationInsights.ApplicationInsightsLoggerProvider");
        if (defaultRule is not null)
        {
            options.Rules.Remove(defaultRule);
        }
    });

var host = builder.Build();

Avant d’appeler Build() sur le IHostApplicationBuilder, vous devez :

  • Si vous souhaitez utiliser l’intégration ASP.NET Core, appelez builder.ConfigureFunctionsWebApplication().
  • Si vous écrivez votre application en F#, vous devrez peut-être inscrire certaines extensions de liaison. Consultez la documentation de configuration de l’extension Blobs, de l’extension Tables et de l’extension Cosmos DB lorsque vous envisagez d’utiliser ces extensions dans une application F#.
  • Configurez les services ou la configuration de l'application dont votre projet a besoin. Pour plus d’informations, consultez Configuration.
  • Si vous envisagez d’utiliser Application Insights, vous devez appeler AddApplicationInsightsTelemetryWorkerService() et ConfigureFunctionsApplicationInsights() sur la propriété Services du générateur. Consultez Limites d’Application Insights pour plus d’informations.

Si votre projet cible .NET Framework 4.8, vous devez également ajouter FunctionsDebugger.Enable(); avant de créer une ressource HostBuilder. Il doit s’agir de la première ligne de votre méthode Main(). Pour plus d’informations, consultez Débogage lors du ciblage du .NET Framework.

IHostApplicationBuilder permet de générer et de retourner une instance IHost entièrement initialisée que vous exécutez de façon asynchrone pour démarrer votre application de fonction.

await host.RunAsync();

Paramétrage

Le type de générateur que vous utilisez détermine la façon dont vous configurez l’application.

Utilisez la FunctionsApplication.CreateBuilder() méthode pour ajouter les paramètres requis pour l’exécution de l’application de fonction. La méthode inclut les fonctionnalités suivantes :

  • Ensemble de convertisseurs par défaut.
  • Définissez la valeur par défaut de JsonSerializerOptions sur ignorer la casse des noms de propriétés.
  • Intégration à la journalisation Azure Functions.
  • Fonctionnalités et intergiciel de liaison de sortie.
  • Intergiciel d’exécution de fonction.
  • Prise en charge par défaut de gRPC.
  • Appliquez d’autres valeurs par défaut à partir de Host.CreateDefaultBuilder().

Vous avez accès au pipeline du générateur. Vous pouvez donc définir n’importe quelle configuration spécifique à l’application lors de l’initialisation. Vous pouvez appeler des méthodes d’extension sur la propriété Configuration du générateur pour ajouter les sources de configuration requises par votre code. Pour plus d’informations sur la configuration des applications, consultez Configuration dans ASP.NET Core.

Ces configurations s’appliquent uniquement au code worker que vous créez. Ils n’influencent pas directement la configuration de l’hôte Functions ou des déclencheurs et des liaisons. Pour apporter des modifications à l’hôte de fonctions ou à la configuration de déclencheur et de liaison, utilisez le fichierhost.json.

Remarque

Les sources de configuration personnalisées ne peuvent pas être utilisées pour la configuration des déclencheurs et des liaisons. La configuration du déclencheur et de la liaison doit être disponible pour la plateforme Functions, pas seulement votre code d’application. Vous pouvez fournir cette configuration via les fonctionnalités Paramètres d’application, Références Key Vault ou Références App Configuration.

Injection de dépendances

Le modèle Worker isolé utilise des mécanismes .NET standard pour l’injection de services.

Lorsque vous utilisez un IHostApplicationBuilder, utilisez sa propriété Services pour accéder à IServiceCollection. L’exemple suivant injecte une dépendance de service singleton :

builder.Services.AddSingleton<IHttpResponderService, DefaultHttpResponderService>();

Le code nécessite using Microsoft.Extensions.DependencyInjection;. Pour plus d’informations, consultez Injection de dépendances dans ASP.net Core.

Inscrire des clients Azure

Utilisez l’injection de dépendances pour interagir avec d’autres services Azure. Vous pouvez injecter des clients à partir du Kit de développement logiciel (SDK) Azure pour .NET à l’aide du package Microsoft.Extensions.Azure. Après avoir installé le package, inscrivez les clients en appelant AddAzureClients() pour la collection de services dans Program.cs. L’exemple suivant configure un client nommé pour les blobs Azure :

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

var builder = FunctionsApplication.CreateBuilder(args);

builder.Services
    .AddAzureClients(clientBuilder =>
        {
            clientBuilder.AddBlobServiceClient(builder.Configuration.GetSection("MyStorageConnection"))
                .WithName("copierOutputBlob");
        });

builder.Build().Run();

L’exemple suivant montre comment utiliser ces types d'enregistrement et SDK pour copier le contenu blob en tant que flux d’un conteneur vers un autre en utilisant un client injecté :

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

namespace MyFunctionApp
{
    public class BlobCopier
    {
        private readonly ILogger<BlobCopier> _logger;
        private readonly BlobContainerClient _copyContainerClient;

        public BlobCopier(ILogger<BlobCopier> logger, IAzureClientFactory<BlobServiceClient> blobClientFactory)
        {
            _logger = logger;
            _copyContainerClient = blobClientFactory.CreateClient("copierOutputBlob").GetBlobContainerClient("samples-workitems-copy");
            _copyContainerClient.CreateIfNotExists();
        }

        [Function("BlobCopier")]
        public async Task Run([BlobTrigger("samples-workitems/{name}", Connection = "MyStorageConnection")] Stream myBlob, string name)
        {
            await _copyContainerClient.UploadBlobAsync(name, myBlob);
            _logger.LogInformation($"Blob {name} copied!");
        }

    }
}

L’exemple ILogger<T> suivant est également obtenu via l’injection de dépendances. Il est donc enregistré automatiquement. Pour en savoir plus sur les options de configuration de journalisation, consultez Journalisation.

Conseil

L’exemple utilise une chaîne littérale pour le nom du client dans le Program.cs et dans la fonction. Au lieu de cela, envisagez d’utiliser une chaîne de constante partagée définie sur la classe de fonction. Par exemple, vous pouvez ajouter public const string CopyStorageClientName = nameof(_copyContainerClient);, puis référencer BlobCopier.CopyStorageClientName dans les deux emplacements. Vous pouvez également définir le nom de la section de configuration avec la fonction, plutôt que dans Program.cs.

Intergiciel

Le modèle de Worker isolé prend également en charge l’inscription d’intergiciel, à nouveau à l’aide d’un modèle similaire à ce qui existe dans ASP.NET. Ce modèle vous donne la possibilité d’injecter une logique dans le pipeline d’appel, et avant et après l’exécution des fonctions.

La méthode d’extension ConfigureFunctionsWorkerDefaults a une surcharge qui vous permet d’inscrire votre propre intergiciel, comme vous le voyez dans l’exemple suivant.

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

var builder = FunctionsApplication.CreateBuilder(args);

// Register our custom middlewares with the worker
builder
    .UseMiddleware<ExceptionHandlingMiddleware>()
    .UseMiddleware<MyCustomMiddleware>()
    .UseWhen<StampHttpHeaderMiddleware>((context) =>
    {
        // We want to use this middleware only for http trigger invocations.
        return context.FunctionDefinition.InputBindings.Values
                        .First(a => a.Type.EndsWith("Trigger")).Type == "httpTrigger";
    });

builder.Build().Run();

La UseWhen méthode d’extension inscrit un intergiciel qui s’exécute de manière conditionnelle. Vous devez passer un prédicat qui retourne une valeur booléenne à cette méthode. L’intergiciel participe au pipeline de traitement d’appel lorsque le prédicat retourne true.

Les méthodes d’extension suivantes sur FunctionContext facilitent l’utilisation des intergiciels dans le modèle isolé.

Méthode Descriptif
GetHttpRequestDataAsync Obtient l’instance HttpRequestData lorsqu’elle est appelée par un déclencheur HTTP. Cette méthode retourne une instance de ValueTask<HttpRequestData?>, ce qui est utile lorsque vous souhaitez lire les données de message, telles que les en-têtes de requête et les cookies.
GetHttpResponseData Obtient l’instance HttpResponseData lorsqu’elle est appelée par un déclencheur HTTP.
GetInvocationResult Obtient une instance de InvocationResult, qui représente le résultat de l’exécution de la fonction actuelle. Utilisez la propriété Value pour obtenir ou définir la valeur en fonction des besoins.
GetOutputBindings Obtient les entrées de liaison de sortie pour l’exécution de la fonction actuelle. Chaque entrée dans les résultats de cette méthode est de type OutputBindingData. Vous pouvez utiliser la propriété Value pour obtenir ou définir la valeur en fonction des besoins.
BindInputAsync Lie un élément de liaison d’entrée pour l’instance demandée BindingMetadata. Par exemple, utilisez cette méthode lorsque vous avez une fonction avec une liaison d’entrée BlobInput qui doit être utilisée par votre intergiciel.

Cet exemple montre une implémentation d’intergiciel qui lit l’instance HttpRequestData et met à jour l’instance pendant l’exécution HttpResponseData de la fonction :

internal sealed class StampHttpHeaderMiddleware : IFunctionsWorkerMiddleware
{
    public async Task Invoke(FunctionContext context, FunctionExecutionDelegate next)
    {
        var requestData = await context.GetHttpRequestDataAsync();

        string correlationId;
        if (requestData!.Headers.TryGetValues("x-correlationId", out var values))
        {
            correlationId = values.First();
        }
        else
        {
            correlationId = Guid.NewGuid().ToString();
        }

        await next(context);

        context.GetHttpResponseData()?.Headers.Add("x-correlationId", correlationId);
    }
}

Cet intergiciel vérifie la présence d’un en-tête de requête spécifique (x-correlationId). Lorsque l’en-tête est présent, l’intergiciel utilise la valeur de cet en-tête pour marquer un en-tête de réponse. Sinon, il génère une nouvelle valeur GUID et utilise cette valeur pour tamponner l’en-tête de réponse.

Conseil

Le modèle présenté précédemment lors de la définition des en-têtes de réponse après await next(context) peut ne pas fonctionner de manière fiable dans tous les scénarios. Ce problème est particulièrement vrai lors de l’utilisation d’ASP.NET intégration core ou dans certaines configurations d’exécution où le flux de réponse a peut-être déjà été envoyé. Pour vous assurer que les en-têtes sont correctement définis, envisagez de récupérer la réponse à partir de context.GetInvocationResult().Value et définissez-les avant que la réponse ne soit retournée par votre fonction, plutôt que de tenter de les modifier dans un middleware une fois l’exécution de la fonction terminée.

Pour obtenir un exemple plus complet de l’utilisation d’un intergiciel personnalisé dans votre application de fonction, consultez l'exemple de référence d’intergiciel personnalisé.

Personnalisation de la sérialisation JSON

Par défaut, le modèle de worker isolé utilise System.Text.Json. Vous pouvez personnaliser le comportement du sérialiseur en configurant les services dans le cadre de votre fichier Program.cs. Cette section traite de la sérialisation à usage général et n’influence pas la sérialisation JSON du déclencheur HTTP avec ASP.NET intégration Core, que vous devez configurer séparément.

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

var builder = FunctionsApplication.CreateBuilder(args);

builder.ConfigureFunctionsWebApplication();

builder.Services.Configure<JsonSerializerOptions>(jsonSerializerOptions =>
    {
        jsonSerializerOptions.PropertyNamingPolicy = JsonNamingPolicy.CamelCase;
        jsonSerializerOptions.DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull;
        jsonSerializerOptions.ReferenceHandler = ReferenceHandler.Preserve;

        // override the default value
        jsonSerializerOptions.PropertyNameCaseInsensitive = false;
    });

builder.Build().Run();

Pour utiliser JSON.NET (Newtonsoft.Json) pour la sérialisation, installez le Microsoft.Azure.Core.NewtonsoftJson package. Ensuite, dans votre inscription de service, réaffectez la propriété Serializer sur la configuration WorkerOptions. L’exemple suivant montre cette configuration à l’aide de ConfigureFunctionsWebApplication, mais elle fonctionne également avec ConfigureFunctionsWorkerDefaults.

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

var builder = FunctionsApplication.CreateBuilder(args);

builder.ConfigureFunctionsWebApplication();

builder.Services.Configure<WorkerOptions>(workerOptions =>
    {
        var settings = NewtonsoftJsonObjectSerializer.CreateJsonSerializerSettings();
        settings.ContractResolver = new CamelCasePropertyNamesContractResolver();
        settings.NullValueHandling = NullValueHandling.Ignore;

        workerOptions.Serializer = new NewtonsoftJsonObjectSerializer(settings);
    });

builder.Build().Run();

Méthodes reconnues en tant que fonctions

Une méthode de fonction est une méthode publique d’une classe publique avec un attribut Function appliqué à la méthode et un attribut déclencheur appliqué à un paramètre d’entrée, comme illustré dans l’exemple suivant :

[Function(nameof(QueueInputOutputFunction))]
[QueueOutput("output-queue")]
public string[] QueueInputOutputFunction([QueueTrigger("input-queue")] Album myQueueItem, FunctionContext context)

L’attribut de déclencheur spécifie le type de déclencheur et lie les données d’entrée à un paramètre de méthode. L’exemple de fonction précédent est déclenché par un message de file d’attente et le message de file d’attente est passé à la méthode dans le myQueueItem paramètre.

L’attribut Function marque une méthode comme point d’entrée de la fonction. Le nom doit être unique dans un projet, commencer par une lettre et contenir uniquement des lettres, des chiffres et _-, jusqu’à 127 caractères. Les modèles de projets créent souvent une méthode nommée Run, mais le nom de la méthode peut être n’importe quel nom de méthode C# valide. La méthode doit être un membre public d’une classe publique. Il doit généralement s’agir d’une méthode d’instance afin que les services puissent être transmis via l’injection de dépendances.

Paramètres de fonction

Voici quelques-uns des paramètres que vous pouvez inclure dans le cadre d’une signature de méthode de fonction :

  • Des liaisons, qui sont marquées comme telles en décorant les paramètres en tant qu’attributs. La fonction doit contenir exactement un paramètre de déclencheur.
  • Un objet de contexte d’exécution, qui fournit des informations sur l’appel actuel.
  • Un jeton d’annulation, utilisé pour l’arrêt approprié.

Contexte d’exécution

Dans le modèle worker isolé, le processus worker transmet un objet FunctionContext à vos méthodes de fonction. Cet objet vous permet d’obtenir une instance ILogger à écrire dans les journaux d’activité en appelant la méthode GetLogger et en fournissant une chaîne categoryName. Vous pouvez utiliser ce contexte pour obtenir un ILogger sans avoir à utiliser l’injection de dépendances. Pour plus d’informations, consultez Journalisation.

Jetons d’annulation

Une fonction peut accepter un paramètre cancellationToken , qui permet au système d’exploitation de notifier votre code lorsque la fonction est sur le point d’être arrêtée. Vous pouvez utiliser cette notification pour vous assurer que la fonction ne s’arrête pas de manière inattendue et laisse les données dans un état incohérent.

Les fonctions .NET qui s’exécutent dans un processus worker isolé prennent en charge les jetons d’annulation. L’exemple suivant déclenche une exception lorsqu’une demande d’annulation est reçue :

[Function(nameof(ThrowOnCancellation))]
public async Task ThrowOnCancellation(
    [EventHubTrigger("sample-workitem-1", Connection = "EventHubConnection")] string[] messages,
    FunctionContext context,
    CancellationToken cancellationToken)
{
    _logger.LogInformation("C# EventHub {functionName} trigger function processing a request.", nameof(ThrowOnCancellation));

    foreach (var message in messages)
    {
        cancellationToken.ThrowIfCancellationRequested();
        await Task.Delay(6000); // task delay to simulate message processing
        _logger.LogInformation("Message '{msg}' was processed.", message);
    }
}

L’exemple suivant effectue des actions de nettoyage lorsqu’une demande d’annulation est reçue :

[Function(nameof(HandleCancellationCleanup))]
public async Task HandleCancellationCleanup(
    [EventHubTrigger("sample-workitem-2", Connection = "EventHubConnection")] string[] messages,
    FunctionContext context,
    CancellationToken cancellationToken)
{
    _logger.LogInformation("C# EventHub {functionName} trigger function processing a request.", nameof(HandleCancellationCleanup));

    foreach (var message in messages)
    {
        if (cancellationToken.IsCancellationRequested)
        {
            _logger.LogInformation("A cancellation token was received, taking precautionary actions.");
            // Take precautions like noting how far along you are with processing the batch
            _logger.LogInformation("Precautionary activities complete.");
            break;
        }

        await Task.Delay(6000); // task delay to simulate message processing
        _logger.LogInformation("Message '{msg}' was processed.", message);
    }
}

Scénarios qui entraînent l’annulation

Le jeton d’annulation est signalé lorsque l’appel de fonction est annulé. Plusieurs raisons peuvent entraîner une annulation, et ces raisons varient selon le type de déclencheur utilisé. Voici quelques raisons courantes :

  • Déconnexion du client : le client qui appelle votre fonction se déconnecte. Cette raison est la plus probable pour les fonctions de déclencheur HTTP.
  • Redémarrage de l’application de fonction : vous ou la plateforme redémarrez (ou arrêtez) l’application de fonction en même temps qu’un appel est demandé. Un redémarrage peut se produire en raison de mouvements d’instances de travail, de mises à jour d’instances de travail ou de mise à l’échelle.

Considérations relatives à l’annulation

  • Les appels en cours lors d’un événement de redémarrage peuvent être relancés en fonction de la manière dont ils ont été déclenchés. Pour plus d’informations, consultez la documentation de nouvelle tentative.

  • L’hôte envoie l’appel au worker même si le jeton d’annulation est annulé avant que l’hôte ne puisse envoyer la demande d’appel au worker.

  • Si vous ne souhaitez pas que les appels pré-annulés soient envoyés au worker, ajoutez la SendCanceledInvocationsToWorker propriété à votre host.json fichier pour désactiver ce comportement.

    Cet exemple montre un host.json fichier qui utilise cette propriété :

    {
    "version": "2.0",
    "SendCanceledInvocationsToWorker": "false"
}

  • Configurer SendCanceledInvocationsToWorker sur false pourrait entraîner une FunctionInvocationCanceled exception avec le log suivant :

    L’annulation a été demandée. La demande d'invocation avec l'ID « {invocationId} » est annulée et ne sera pas envoyée au travailleur.

    Cette exception se produit lorsque le jeton d’annulation est annulé (suite à l’un des événements décrits précédemment) avant que l’hôte envoie une demande d’appel entrante au worker. Cette exception peut être ignorée en toute sécurité et est attendue lorsque SendCanceledInvocationsToWorker est false.

Liaisons

Définissez des liaisons à l’aide d’attributs sur les méthodes, les paramètres et les types de retour. Les liaisons peuvent fournir des données sous forme de chaînes, de tableaux et de types sérialisables, telles que des objets de classe anciens simples (POCO). Pour certaines extensions de liaison, vous pouvez également lier à des types propres au service définis dans des kits SDK de service.

Pour les déclencheurs HTTP, consultez la section Déclencheur HTTP.

Pour un ensemble complet d’exemples de référence qui utilisent des déclencheurs et des liaisons avec des fonctions de processus de travail isolé, voir l’exemple de référence des extensions de liaison.

Liaisons d’entrée

Une fonction peut avoir zéro ou plusieurs liaisons d’entrée qui transmettent des données à la fonction. Comme les déclencheurs, vous définissez des liaisons d’entrée en appliquant un attribut de liaison à un paramètre d’entrée. Lorsque la fonction s’exécute, le runtime tente d’obtenir les données spécifiées dans la liaison. Les données demandées dépendent souvent des informations fournies par le déclencheur via des paramètres de liaison.

Liaisons de sortie

Pour écrire dans une liaison de sortie, vous devez appliquer un attribut de liaison de sortie à la méthode de fonction. Cet attribut définit la manière d’écrire vers le service lié. La valeur de retour de la méthode est écrite dans la liaison de sortie. Par exemple, l’exemple suivant écrit une valeur de chaîne dans une file d’attente de messages nommée output-queue à l’aide d’une liaison de sortie :

[Function(nameof(QueueInputOutputFunction))]
[QueueOutput("output-queue")]
public string[] QueueInputOutputFunction([QueueTrigger("input-queue")] Album myQueueItem, FunctionContext context)
{
    // Use a string array to return more than one message.
    string[] messages = {
        $"Album name = {myQueueItem.Name}",
        $"Album songs = {myQueueItem.Songs}"};

    _logger.LogInformation("{msg1},{msg2}", messages[0], messages[1]);

    // Queue Output messages
    return messages;
}

Liaisons de sortie multiples

Les données écrites dans une liaison de sortie correspondent toujours à la valeur renvoyée de la fonction. S’il vous faut écrire dans plusieurs liaisons de sortie, vous devez créer un type de retour personnalisé. Ce type de retour doit présenter l’attribut de liaison de sortie appliqué à une ou plusieurs propriétés de la classe. L’exemple suivant illustre une fonction déclenchée par HTTP qui utilise l’intégration ASP.NET Core et écrit à la fois dans la réponse HTTP et dans une liaison de sortie de file d’attente :

public class MultipleOutputBindings
{
    private readonly ILogger<MultipleOutputBindings> _logger;

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

    [Function("MultipleOutputBindings")]
    public MyOutputType Run([HttpTrigger(AuthorizationLevel.Function, "post")] HttpRequest req)
    {
        _logger.LogInformation("C# HTTP trigger function processed a request.");
        var myObject = new MyOutputType
        {
            Result = new OkObjectResult("C# HTTP trigger function processed a request."),
            MessageText = "some output"
        };
        return myObject;
    }

    public class MyOutputType
    {
        [HttpResult]
        public IActionResult Result { get; set; }

        [QueueOutput("myQueue")]
        public string MessageText { get; set; }
    }
}

Lorsque vous utilisez des types de retour personnalisés pour plusieurs liaisons de sortie avec l’intégration ASP.NET Core, vous devez ajouter l’attribut [HttpResult] à la propriété qui fournit le résultat. L’attribut HttpResult est disponible lorsque vous utilisez SDK 1.17.3-preview2 ou version ultérieure , ainsi que version 3.2.0 ou ultérieure de l’extension HTTP et version 1.3.0 ou ultérieure de l’extension ASP.NET Core.

Types de SDK

Pour certains types de liaison spécifiques au service, vous pouvez fournir des données de liaison en utilisant des types à partir de SDK de service et d'infrastructures. Ces types offrent des fonctionnalités au-delà de ce qu’une chaîne sérialisée ou un ancien objet CLR (POCO) peut fournir. Pour utiliser les types plus récents, mettez à jour votre projet pour utiliser des versions plus récentes des dépendances principales.

Dépendance Exigence de version
Microsoft.Azure.Functions.Worker 1.18.0 ou version ultérieure
Microsoft.Azure.Functions.Worker.Sdk 1.13.0 ou version ultérieure

Lorsque vous testez des types de SDK localement sur votre ordinateur, vous devez également utiliser Azure Functions Core Tools version 4.0.5000 ou ultérieure. Vous pouvez vérifier votre version actuelle à l’aide de la func --version commande.

Chaque extension de liaison a également sa propre exigence de version minimale, qui est décrite dans les articles de référence de l’extension. Ces extensions de liaison prennent actuellement en charge les types de SDK :

Extension Les types Niveau du support
Stockage Blob Azure BlobClient
BlobContainerClient
BlockBlobClient
PageBlobClient
AppendBlobClient		 Déclencheur : GA
Entrée : GA
Azure Cosmos DB CosmosClient
Database
Container		 Entrée : GA
Azure Event Grid CloudEvent
EventGridEvent		 Déclencheur : GA
Azure Event Hubs EventData
EventHubProducerClient		 Déclencheur : GA
Stockage de files d'attente Azure QueueClient
QueueMessage		 Déclencheur : GA
Azure Service Bus ServiceBusClient
ServiceBusReceiver
ServiceBusSender
ServiceBusMessage		 Déclencheur : GA
Stockage de tables Azure TableClient
TableEntity		 Entrée : GA

Considérations relatives aux types de SDK :

  • Lorsque vous utilisez des expressions de liaison qui s’appuient sur des données de déclencheur, les types de SDK pour le déclencheur lui-même ne peuvent pas être utilisés.
  • Pour les scénarios de sortie où vous pouvez utiliser un type de KIT de développement logiciel (SDK), créez et travaillez directement avec des clients sdk au lieu d’utiliser une liaison de sortie.
  • Le déclencheur Azure Cosmos DB utilise le flux de modification Azure Cosmos DB et expose les éléments de flux de modification en tant que types sérialisables JSON. Par conséquent, les types de SDK ne sont pas pris en charge pour ce déclencheur.

Déclencheur HTTP

Le déclencheur HTTP permettent d’invoquer une fonction par une requête HTTP. Vous pouvez utiliser deux approches différentes :

  • Modèle d’intégration ASP.NET Core qui utilise des concepts connus des développeurs ASP.NET Core
  • Un modèle intégré qui ne nécessite pas de dépendances supplémentaires et utilise des types personnalisés pour les requêtes et les réponses HTTP Cette approche est conservée à des fins de compatibilité descendante avec les applications Worker isolé .NET antérieures.

Intégration ASP.NET Core

Cette section montre comment utiliser les objets de requête et de réponse HTTP sous-jacents à l’aide de types de ASP.NET Core, notamment HttpRequest, HttpResponse et IActionResult. Ce modèle n’est pas disponible pour les applications ciblant le .NET Framework, qui doivent plutôt utiliser le modèle intégré.

Remarque

Ce modèle n’expose pas toutes les fonctionnalités de ASP.NET Core. Plus précisément, il ne fournit pas d’accès au pipeline d’intergiciels et aux fonctionnalités de routage ASP.NET Core. L’intégration ASP.NET Core vous oblige à utiliser des packages mis à jour.

Pour activer l’intégration ASP.NET Core pour HTTP :

  1. Ajoutez une référence dans votre projet au package Microsoft.Azure.Functions.Worker.Extensions.Http.AspNetCore, version 1.0.0 ou ultérieure.

  2. Mettez à jour votre projet de façon à utiliser ces versions de package spécifiques :

  3. Dans votre fichier Program.cs, mettez à jour la configuration du générateur d’hôte pour appeler ConfigureFunctionsWebApplication(). Cette méthode remplace ConfigureFunctionsWorkerDefaults() si vous auriez utilisé cette méthode autrement. L’exemple suivant montre une configuration minimale sans autres personnalisations :

    Remarque

    Votre application doit référencer la version 2.0.0 ou ultérieure de Microsoft.Azure.Functions.Worker.Extensions.Http.AspNetCore pour utiliser l’intégration ASP.NET Core avec IHostApplicationBuilder.

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

var builder = FunctionsApplication.CreateBuilder(args);

builder.ConfigureFunctionsWebApplication();    

builder.Build().Run();

  4. Mettez à jour les fonctions déclenchées par HTTP existantes de façon à utiliser les types ASP.NET Core. Cet exemple montre le HttpRequest standard et un IActionResult utilisé pour une fonction « hello, world » simple :

    [Function("HttpFunction")]
public IActionResult Run(
    [HttpTrigger(AuthorizationLevel.Anonymous, "get")] HttpRequest req)
{
    return new OkObjectResult($"Welcome to Azure Functions, {req.Query["name"]}!");
}

Sérialisation JSON avec intégration ASP.NET Core

ASP.NET Core a sa propre couche de sérialisation et n’est pas affectée par la personnalisation de la configuration de sérialisation générale. Pour personnaliser le comportement de sérialisation utilisé pour vos déclencheurs HTTP, vous devez inclure un appel .AddMvc() dans le cadre de l’inscription de service. Le IMvcBuilder retourné peut être utilisé pour modifier les paramètres de sérialisation JSON d’ASP.NET Core.

Vous pouvez continuer à utiliser HttpRequestData et HttpResponseData pendant l’utilisation de l’intégration ASP.NET, bien que nous recommandions d’utiliser HttpRequest et IActionResult à la place pour la plupart des applications. L’utilisation de HttpRequestData/HttpResponseData n’implique par la couche de sérialisation ASP.NET Core et s’appuie à la place sur la configuration générale de sérialisation du Worker pour l’application. Toutefois, quand l’intégration ASP.NET Core est activée, il est possible que vous deviez toujours ajouter la configuration. Le comportement par défaut à partir de ASP.NET Core consiste à interdire les E/S synchrones. Pour utiliser un sérialiseur personnalisé qui ne prend pas en charge les E/S asynchrones, par NewtonsoftJsonObjectSerializerexemple, vous devez activer les E/S synchrones pour votre application en configurant le KestrelServerOptions.

L’exemple suivant montre comment configurer JSON.NET (Newtonsoft.Json) et le package NuGet Microsoft.AspNetCore.Mvc.NewtonsoftJson pour la sérialisation en utilisant cette approche :

using Microsoft.AspNetCore.Server.Kestrel.Core;
using Microsoft.Azure.Functions.Worker;
using Microsoft.Azure.Functions.Worker.Builder;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;

var builder = FunctionsApplication.CreateBuilder(args);

builder.ConfigureFunctionsWebApplication();

builder.Services
    .AddApplicationInsightsTelemetryWorkerService()
    .ConfigureFunctionsApplicationInsights();

builder.Services.AddMvc().AddNewtonsoftJson();

// Only needed if using HttpRequestData/HttpResponseData and a serializer that doesn't support asynchronous IO
// builder.Services.Configure<KestrelServerOptions>(options => options.AllowSynchronousIO = true);

builder.Build().Run();

Modèle HTTP intégré

Dans le modèle intégré, le système convertit le message de requête HTTP entrant en objet HttpRequestData qu’il transmet à la fonction. Cet objet fournit les données de la requête, notamment Headers, Cookies, Identities, URL, et éventuellement un message Body. Cet objet représente la requête HTTP, mais n’est pas directement connecté à l’écouteur HTTP sous-jacent ou au message reçu.

De même, la fonction retourne un objet HttpResponseData, qui fournit les données utilisées pour créer la réponse HTTP, notamment le message StatusCode, Headers et éventuellement un message Body.

L’exemple suivant montre l’utilisation de HttpRequestData et HttpResponseData :

[Function(nameof(HttpFunction))]
public static HttpResponseData Run([HttpTrigger(AuthorizationLevel.Anonymous, "get", "post", Route = null)] HttpRequestData req,
    FunctionContext executionContext)
{
    var logger = executionContext.GetLogger(nameof(HttpFunction));
    logger.LogInformation("message logged");

    var response = req.CreateResponse(HttpStatusCode.OK);
    response.Headers.Add("Content-Type", "text/plain; charset=utf-8");
    response.WriteString("Welcome to .NET isolated worker !!");

    return response;
}

Exploitation forestière

Vous pouvez écrire dans les journaux en utilisant une instance ILogger<T> ou ILogger. Vous pouvez obtenir l’enregistreur d’événements via l’injection de dépendances d’un ILogger<T> ou d’un ILoggerFactory :

public class MyFunction {
    
    private readonly ILogger<MyFunction> _logger;
    
    public MyFunction(ILogger<MyFunction> logger) {
        _logger = logger;
    }
    
    [Function(nameof(MyFunction))]
    public void Run([BlobTrigger("samples-workitems/{name}", Connection = "")] string myBlob, string name)
    {
        _logger.LogInformation($"C# Blob trigger function Processed blob\n Name: {name} \n Data: {myBlob}");
    }

}

Vous pouvez également obtenir l’enregistreur d’événements à partir d’un objet FunctionContext passé à votre fonction. Appelez la méthode GetLogger<T> ou GetLogger, en passant une valeur de chaîne qui correspond au nom de la catégorie dans laquelle les journaux d’activité sont écrits. La catégorie correspond généralement au nom de la fonction spécifique à partir de laquelle les journaux sont écrits. Pour plus d’informations sur les catégories, consultez l’article de surveillance.

Utilisez les méthodes de ILogger<T> et ILogger pour écrire différents niveaux de journalisation, comme LogWarning ou LogError. Pour plus d’informations sur les niveaux de journalisation, consultez l’article relatif à la surveillance. Vous pouvez personnaliser les niveaux de journal pour les composants ajoutés à votre code en inscrivant des filtres :

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

var builder = FunctionsApplication.CreateBuilder(args);

builder.ConfigureFunctionsWebApplication();

// Registers IHttpClientFactory.
// By default this sends a lot of Information-level logs.
builder.Services.AddHttpClient();

// Disable IHttpClientFactory Informational logs.
// Note -- you can also remove the handler that does the logging: https://github.com/aspnet/HttpClientFactory/issues/196#issuecomment-432755765 
builder.Logging.AddFilter("System.Net.Http.HttpClient", LogLevel.Warning);
    
builder.Build().Run();

Dans le cadre de la configuration de votre application dans Program.cs, vous pouvez également définir le comportement de la façon dont les erreurs sont exposées à vos journaux. Le comportement par défaut dépend du type de générateur que vous utilisez.

Lorsque vous utilisez un IHostApplicationBuilder, les exceptions levées par votre code transitent par le système sans modification. Vous n’avez pas besoin d’une autre configuration.

Application Insights

Vous pouvez configurer votre application de processus isolée pour envoyer des journaux directement à Application Insights. Cette configuration remplace le comportement par défaut de transmission des journaux via l’hôte. À moins que vous utilisiez Aspire, configurez une intégration directe avec Application Insights, car cela vous donne le contrôle sur la manière dont ces journaux sont émis.

L’intégration d’Application Insights n’est pas activée par défaut dans toutes les expériences de configuration. Certains modèles créent des projets Functions avec les packages nécessaires et le code de démarrage commentés. Si vous souhaitez utiliser l’intégration Application Insights, supprimez les marques de commentaire ces lignes dans Program.cs et dans le fichier .csproj du projet. Les instructions contenues dans le reste de cette section décrivent également comment activer l’intégration.

Si votre projet fait partie d’une orchestration Aspire, il utilise OpenTelemetry pour la supervision à la place. N’activez pas l’intégration directe d’Application Insights dans les projets Aspire. Au lieu de cela, configurez l’exportateur Azure Monitor OpenTelemetry dans le cadre du projet de service par défaut. Si votre projet Functions utilise l’intégration d’Application Insights dans un contexte Aspire, des erreurs d’application apparaissent au démarrage.

Installer des packages

Pour écrire des journaux directement dans Application Insights à partir de votre code, ajoutez des références à ces packages dans votre projet :

Exécutez les commandes suivantes pour ajouter ces références à votre projet :

dotnet add package Microsoft.ApplicationInsights.WorkerService
dotnet add package Microsoft.Azure.Functions.Worker.ApplicationInsights

Configurer le démarrage

Après avoir installé les packages, appelez AddApplicationInsightsTelemetryWorkerService() et ConfigureFunctionsApplicationInsights() pendant la configuration du service dans votre Program.cs fichier, comme illustré dans l’exemple suivant :

using Microsoft.Azure.Functions.Worker;
using Microsoft.Azure.Functions.Worker.Builder;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
    
var builder = FunctionsApplication.CreateBuilder(args);

builder.Services
    .AddApplicationInsightsTelemetryWorkerService()
    .ConfigureFunctionsApplicationInsights();

builder.Build().Run();

L’appel à ConfigureFunctionsApplicationInsights() ajoute un ITelemetryModule qui écoute un ActivitySource défini par Functions. Ce module crée les données de télémétrie de dépendance requises pour prendre en charge le suivi distribué. Pour plus d’informations sur AddApplicationInsightsTelemetryWorkerService() et sur son utilisation, consultez Application Insights pour les applications Service Worker.

Gérer les niveaux de journalisation

Important

L’hôte Functions et le worker de processus isolé .NET ont une configuration distincte pour les niveaux de journalisation. Toute configuration Application Insights dans host.json n’affecte pas la journalisation à partir du worker, et de même, la configuration dans votre code worker n’a pas d’impact sur la journalisation à partir de l’hôte. Appliquez des modifications aux deux emplacements si votre scénario nécessite une personnalisation aux deux couches.

Le reste de votre application continue de fonctionner avec ILogger et ILogger<T>. Toutefois, par défaut, le Kit de développement logiciel (SDK) Application Insights ajoute un filtre de journalisation qui indique à l’enregistreur d’événements de capturer uniquement des avertissements et des journaux plus graves. Vous pouvez configurer les niveaux de journalisation dans le processus worker isolé de l’une des méthodes suivantes :

Mode de configuration Avantages
Dans votre code Favorise une séparation plus claire entre les configurations côté hôte et côté travailleur.
Utilisation de appsettings.json Utile lorsque vous souhaitez définir différents niveaux de journal pour différentes catégories sans avoir à modifier votre code.

Pour désactiver le comportement par défaut et capturer tous les niveaux de journal, supprimez la règle de filtre dans le cadre de la configuration du service :

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

var builder = FunctionsApplication.CreateBuilder(args);

builder.Services
    .AddApplicationInsightsTelemetryWorkerService()
    .ConfigureFunctionsApplicationInsights();

builder.Logging.Services.Configure<LoggerFilterOptions>(options =>
    {
        LoggerFilterRule defaultRule = options.Rules.FirstOrDefault(rule => rule.ProviderName
            == "Microsoft.Extensions.Logging.ApplicationInsights.ApplicationInsightsLoggerProvider");
        if (defaultRule is not null)
        {
            options.Rules.Remove(defaultRule);
        }
    });

builder.Build().Run();

Pour plus d’informations sur la configuration de la journalisation, consultez Journalisation dans .NET et Application Insights pour les applications Worker Service.

Optimisations des performances

Cette section décrit les options que vous pouvez activer pour améliorer les performances autour du démarrage à froid.

En général, votre application doit utiliser les dernières versions de ses dépendances principales. Au minimum, mettez à jour votre projet comme suit :

  1. Mettez à niveau Microsoft.Azure.Functions.Worker vers la version 1.19.0 ou ultérieure.
  2. Mettez à niveau Microsoft.Azure.Functions.Worker.Sdk vers la version 1.16.4 ou une version ultérieure.
  3. Ajoutez une référence de framework à Microsoft.AspNetCore.App, sauf si votre application cible .NET Framework.

L’extrait suivant montre cette configuration dans le contexte d’un fichier projet :

  <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.16.4" />
  </ItemGroup>

Espaces réservés

Les espaces réservés sont une fonctionnalité de plateforme qui améliore le démarrage à froid pour les applications ciblant .NET 6 ou une version ultérieure. Pour utiliser cette optimisation, vous devez activer explicitement les espaces réservés en procédant comme suit :

  1. Mettez à jour la configuration de votre projet de façon à utiliser les dernières versions de dépendances, comme indiqué dans la section précédente.

  2. Définissez le paramètre d’application WEBSITE_USE_PLACEHOLDER_DOTNETISOLATED sur 1. Utilisez la commande az functionapp config appsettings set :

    az functionapp config appsettings set -g <groupName> -n <appName> --settings 'WEBSITE_USE_PLACEHOLDER_DOTNETISOLATED=1'

    Dans cet exemple, remplacez <groupName> par le nom de votre groupe de ressources, et <appName> par le nom de votre application de fonction.

  3. Vérifiez que la propriété netFrameworkVersion de l’application de fonction correspond à l’infrastructure cible de votre projet, qui doit être .NET 6 ou version ultérieure. Utilisez cette commande az functionapp config set :

    az functionapp config set -g <groupName> -n <appName> --net-framework-version <framework>

    Dans cet exemple, remplacez également <framework> par la chaîne de version appropriée, telle que v8.0, en fonction de votre version cible de .NET.

  4. Vérifiez que votre application de fonction est configurée pour utiliser un processus 64 bits. Utilisez cette commande az functionapp config set :

    az functionapp config set -g <groupName> -n <appName> --use-32bit-worker-process false

Important

Lorsque vous définissez WEBSITE_USE_PLACEHOLDER_DOTNETISOLATED sur 1, vous devez configurer correctement toutes les autres applications de fonctions. Autrement, votre application de fonction risque de ne pas démarrer.

Exécuteur optimisé

L’exécuteur de fonction est un composant de la plateforme qui provoque l’exécution d’appels. Une version optimisée de ce composant est activée par défaut à partir de la version 1.16.2 du Kit de développement logiciel (SDK). Aucune configuration supplémentaire n’est nécessaire.

ReadyToRun

Vous pouvez compiler votre application de fonction en tant que binaires ReadyToRun. ReadyToRun est une forme de compilation anticipée qui peut améliorer les performances de démarrage afin de réduire l’effet des démarrages à froid lors de l’exécution dans un Plan de consommation. ReadyToRun est disponible dans .NET 6 et versions ultérieures et requiert laversion 4.0 ou ultérieure d’Azure Functions Runtime.

ReadyToRun vous oblige à générer le projet contre l’architecture de runtime de l’application d’hébergement. Lorsque ces architectures ne sont pas alignées, votre application rencontre une erreur au démarrage. Sélectionnez votre identificateur de runtime dans ce tableau :

Système d’exploitation L’application est une application 32 bits1 Identificateur de runtime
Fenêtres Vrai win-x86
Fenêtres Faux win-x64
Linux Vrai N/A (non pris en charge)
Linux Faux linux-x64

1 Seules les applications 64 bits sont éligibles à d’autres optimisations des performances.

Pour vérifier si votre application Windows est 32 bits ou 64 bits, exécutez la commande CLI suivante, en remplaçant <group_name> par le nom de votre groupe de ressources et <app_name> par le nom de votre application. Une sortie « true » indique que l’application est en 32 bits et « false » indique 64 bits.

 az functionapp config show -g <group_name> -n <app_name> --query "use32BitWorkerProcess"

Vous pouvez modifier votre application en 64 bits avec la commande suivante, en utilisant les mêmes substitutions :

az functionapp config set -g <group_name> -n <app_name> --use-32bit-worker-process false`

Pour compiler votre projet en tant que ReadyToRun, mettez à jour votre fichier projet en ajoutant les éléments <PublishReadyToRun> et <RuntimeIdentifier>. Les exemples suivants montrent une configuration de publication sur une application de fonction Windows 64 bits.

<PropertyGroup>
  <TargetFramework>net8.0</TargetFramework>
  <AzureFunctionsVersion>v4</AzureFunctionsVersion>
  <RuntimeIdentifier>win-x64</RuntimeIdentifier>
  <PublishReadyToRun>true</PublishReadyToRun>
</PropertyGroup>

Si vous ne souhaitez pas définir le <RuntimeIdentifier> dans le cadre du fichier projet, vous pouvez également configurer ce paramètre directement dans le processus de publication. Par exemple, avec une application de fonction Windows 64 bits, la commande CLI .NET est :

dotnet publish --runtime win-x64

Dans Visual Studio, définissez l'option Environnement d'exécution cible dans le profil de publication sur l'identificateur correct d'exécution. Lorsqu’il est défini sur la valeur par défaut Portable, ReadyToRun n’est pas utilisé.

Déployer sur Azure Functions

Lorsque vous déployez votre projet de code de fonction sur Azure, il doit s’exécuter dans une application de fonction ou dans un conteneur Linux. Vous devez créer l’application de fonction et d’autres ressources Azure requises avant de déployer votre code.

Vous pouvez également déployer votre application de fonction dans un conteneur Linux. Pour plus d’informations, consultez Utilisation des conteneurs et d’Azure Functions.

Créer des ressources Azure

Vous pouvez créer votre application de fonction et d’autres ressources requises dans Azure à l’aide de l’une des méthodes suivantes :

  • Visual Studio : Visual Studio peut créer des ressources pour vous pendant le processus de publication de code.
  • Visual Studio Code : Visual Studio Code peut se connecter à votre abonnement, créer les ressources nécessaires à votre application, puis publier votre code.
  • Azure CLI : Utilisez Azure CLI pour créer les ressources requises dans Azure.
  • Azure PowerShell : Utilisez Azure PowerShell pour créer les ressources requises dans Azure.
  • Modèles de déploiement : utilisez des modèles ARM et des fichiers Bicep pour automatiser le déploiement des ressources requises sur Azure. Vérifiez que votre modèle inclut tous les paramètres requis.
  • Portail Azure : Créez les ressources requises dans le portail Azure.

Publication de votre application

Après avoir créé votre application de fonction et d’autres ressources requises dans Azure, déployez le projet de code sur Azure à l’aide de l’une des méthodes suivantes :

Pour plus d’informations, consultez Technologies de déploiement dans Azure Functions.

Charge utile de déploiement

La plupart des méthodes de déploiement utilisent une archive zip. Si vous créez vous-même l’archive zip, elle doit suivre la structure décrite dans cette section. Si ce n’est pas le cas, votre application peut rencontrer des erreurs au démarrage.

La charge utile de déploiement doit correspondre à la sortie d’une commande dotnet publish, mais sans le dossier parent englobant. L’archive zip doit être effectuée à partir des fichiers suivants :

  • .azurefunctions/
  • extensions.json
  • functions.metadata
  • host.json
  • worker.config.json
  • Exécutable de votre projet (application console)
  • Autres fichiers et répertoires de prise en charge homologues à cet exécutable

Le processus de génération génère ces fichiers et vous ne devez pas les modifier directement.

Conseil

Vous pouvez utiliser la func pack commande dans Core Tools pour générer correctement une archive zip pour le déploiement. La prise en charge de func pack est actuellement en préversion.

Lors de la préparation d’une archive zip pour le déploiement, compressez uniquement le contenu du répertoire de sortie, et non le répertoire englobant lui-même. Lorsque l’archive est extraite dans le répertoire de travail actif, les fichiers répertoriés précédemment doivent être immédiatement visibles.

Composants requis pour le déploiement

Pour exécuter des fonctions .NET dans le modèle worker isolé dans Azure, vous devez répondre à quelques exigences. Les exigences dépendent du système d’exploitation :

Lorsque vous créez votre application de fonction dans Azure à l’aide des méthodes de la section précédente, ces paramètres requis sont ajoutés pour vous. Lorsque vous créez ces ressources à l’aide de modèles ARM ou de fichiers Bicep pour l’automatisation, vous devez veiller à les définir dans le modèle.

Aspire

Aspire est une pile avisée qui simplifie le développement d’applications distribuées dans le cloud. Vous pouvez inscrire des projets de modèle de Worker isolé dans des orchestrations Aspire 13. Pour plus d’informations, consultez Azure Functions avec Aspire .

Débogage

Lors d’une exécution locale à l’aide de Visual Studio ou Visual Studio Code, vous pouvez déboguer votre projet de Worker isolé .NET normalement. Toutefois, il existe deux scénarios de débogage qui ne fonctionnent pas comme prévu.

Débogage distant avec Visual Studio

Étant donné que votre application de processus worker isolé s’exécute en dehors du runtime Functions, vous devez attacher le débogueur distant à un processus distinct. Pour en savoir plus sur le débogage à l’aide de Visual Studio, consultez Débogage à distance.

Débogage lors du ciblage du .NET Framework

Si votre projet isolé cible .NET Framework 4.8, vus devez effectuer des étapes manuelles pour activer le débogage. Ces étapes ne sont pas nécessaires si vous utilisez un autre cadre cible.

La première opération de votre application doit être un appel à FunctionsDebugger.Enable();. Cela se produit dans la méthode Main() avant d’initialiser une ressource HostBuilder. Votre fichier Program.cs doit ressembler à ceci :

using System;
using System.Diagnostics;
using Microsoft.Extensions.Hosting;
using Microsoft.Azure.Functions.Worker;
using NetFxWorker;

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

            var host = FunctionsApplication
                .CreateBuilder(args)
                .Build();

            host.Run();
        }
    }
}

Ensuite, vous devez attacher manuellement le processus à l’aide d’un débogueur .NET Framework. Visual Studio ne le fait pas encore automatiquement pour les applications .NET Framework à processus worker isolé, et l'opération « Start Debugging » doit être évitée.

Dans le répertoire de votre projet (ou son répertoire de sortie de build), exécutez :

func host start --dotnet-isolated-debug

Cela démarre votre Worker, et le processus s’arrête avec le message suivant :

Azure Functions .NET Worker (PID: <process id>) initialized in debug mode. Waiting for debugger to attach...

Où <process id> est l’ID de votre processus Worker. Vous pouvez maintenant utiliser Visual Studio pour attacher manuellement le processus. Pour obtenir des instructions sur cette opération, consultez Comment attacher un débogueur à un processus en cours d’exécution.

Une fois le débogueur attaché, l’exécution du processus reprend et vous pourrez procéder au débogage.

Préversions de .NET

Avant une version en disponibilité générale, une version .NET peut être mise en production à l’état Préversion ou Mise en service. Pour en savoir plus sur ces états, reportez-vous à stratégie de support officiel .NET.

Bien qu'il soit possible de cibler une version donnée à partir d'un projet Functions local, les applications de fonction hébergées dans Azure peuvent ne pas disposer de cette version. Azure Functions ne peut être utilisé qu’avec les versions Préversion ou Mise en service indiquées dans cette section.

Azure Functions ne fonctionne actuellement pas avec les versions « Préversion » ou « Mise en service » .NET. Reportez-vous à Versions prises en charge pour obtenir la liste des versions en disponibilité générale que vous pouvez utiliser.

Utilisation d’un Kit de développement logiciel (SDK) .NET en préversion

Pour utiliser Azure Functions avec une version de la préversion de .NET, vous devez mettre à jour votre projet en procédant comme suit :

  1. Installation de la version adéquate du Kit de développement logiciel (SDK) .NET dans votre développement
  2. Modification du paramètre TargetFramework dans votre fichier .csproj

Lors du déploiement sur votre application de fonction dans Azure, vous devez également vérifier que l’infrastructure est à la disposition de l’application. Pendant la période de préversion, des outils et expériences peuvent ne pas exposer la nouvelle version préliminaire en tant qu’option. Si vous ne voyez pas la préversion incluse dans le portail Azure, par exemple, vous pouvez utiliser l’API REST, les fichiers Bicep ou Azure CLI pour configurer la version manuellement.

Pour les applications hébergées sur Windows, utilisez la commande Azure CLI suivante. Remplacez <groupName> par le nom du groupe de ressources, puis remplacez <appName> par le nom de votre application de fonction. Remplacez <framework> par la chaîne de version appropriée, comme v8.0.

az functionapp config set -g <groupName> -n <appName> --net-framework-version <framework>

Considérations relatives à l’utilisation des versions de la préversion de .NET

Gardez ces considérations à l’esprit lors de l’utilisation de Functions avec des versions de la préversion de .NET :

  • Lorsque vous créez vos fonctions dans Visual Studio, vous devez utiliser Visual Studio Insiders, qui prend en charge la création de projets Azure Functions avec des sdk en préversion .NET.

  • Vérifiez que vous disposez des derniers outils et modèles Functions. Pour mettre à jour vos outils :

    1. Accédez auxoptions>, choisissez Azure Functions sous Projets et Solutions>Autres paramètres.
    2. Sélectionnez Rechercher les mises à jour et installez les mises à jour comme indiqué.

  • Pendant une période de préversion, votre environnement de développement peut disposer d’une version plus récente de la préversion .NET que le service hébergé. Cela peut entraîner l’échec de votre application de fonction lors du déploiement. Pour résoudre ce problème, vous pouvez spécifier la version du kit SDK à utiliser dans global.json.

    1. Exécutez la commande dotnet --list-sdks et notez la préversion que vous utilisez actuellement pendant le développement local.
    2. Exécutez la commande dotnet new globaljson --sdk-version <SDK_VERSION> --force, où <SDK_VERSION> est la version que vous utilisez localement. Par exemple, dotnet new globaljson --sdk-version dotnet-sdk-10.0.100-preview.5.25277.114 --force oblige le système à utiliser le kit SDK .NET 10 préversion 5 lors de la génération de votre projet.

Remarque

En raison du chargement juste-à-temps des infrastructures en préversion, les temps de démarrage à froid des applications de fonctions s’exécutant sur Windows peuvent être plus élevés que ceux des versions en disponibilité générale antérieures.

Étapes suivantes

En savoir plus sur les meilleures pratiques pour Azure Functions

Effectuer une migration des applications .NET vers le modèle Worker isolé

Intégrer à Aspire

  • Last updated on