Héberger ASP.NET Core dans un service Windows

Une application ASP.NET Core peut être hébergée sur Windows en tant que service Windows sans utiliser IIS. Lorsqu’elle est hébergée en tant que service Windows, l’application se lance automatiquement après le redémarrage du serveur.

Prérequis

• Kit SDK ASP.NET Core 7.0 ou plus
• PowerShell version 6.2 ou ultérieure

Modèle Service Worker

Le modèle Service Worker ASP.NET Core fournit un point de départ pour l’écriture d’applications de service durables. Pour utiliser le modèle en tant que base d’une application de service Windows :

1. Créez une application Service Worker à partir du modèle .NET Core.
2. Installez le package NuGet Microsoft.Extensions.Hosting.WindowsServices.
3. Suivez l’aide fournie dans la section Configuration d’application pour mettre à jour l’application Service Worker afin qu’elle puisse s’exécuter en tant que service Windows.

Visual Studio

1. Créer un nouveau projet.
2. Sélectionnez Service Worker. Cliquez sur Suivant.
3. Indiquez un nom de projet dans le champ Nom du projet, ou acceptez le nom de projet par défaut. Cliquez sur Créer.
4. Dans la boîte de dialogue Créer un service Worker, sélectionnez Créer.

Visual Studio pour Mac

1. Créer un nouveau projet.
2. Sélectionnez Application sous .NET Core dans la barre latérale.
3. Sélectionnez Worker sous ASP.NET Core. Cliquez sur Suivant.
4. Sélectionnez .NET Core 3.0 ou version ultérieure pour la version cible de .Net Framework. Sélectionnez Suivant.
5. Indiquez un nom dans le champ Nom du projet. Cliquez sur Créer.

CLI .NET

Utilisez le modèle Service Worker (worker) avec la commande dotnet new à partir d’un interpréteur de commandes. Dans l’exemple suivant, une application Service Worker est créée et se nomme ContosoWorker. Un dossier pour l’application ContosoWorker est créé automatiquement durant l’exécution de la commande.

dotnet new worker -o ContosoWorker

la configuration d’une application ;

Mettez à jour Program.cs pour appeler AddWindowsService. Quand l’application s’exécute comme un service Windows, AddWindowsService :

• définit la durée de vie de l’hôte sur WindowsServiceLifetime ;
• Définit la racine de contenu sur AppContext.BaseDirectory. Pour plus d’informations, consultez la section Répertoire actif et racine du contenu.
• Active la journalisation dans le journal des événements :
  • Le nom de l’application est utilisé comme nom source par défaut.
  • Le niveau de journal par défaut est Avertissement ou supérieur pour une application basée sur un modèle ASP.NET Core qui appelle CreateDefaultBuilder pour générer l’hôte.
  • Remplacez le niveau de journal par défaut par la clé Logging:EventLog:LogLevel:Default dans appsettings.json/appsettings.{Environment}.json ou un autre fournisseur de configuration.
  • Seuls les administrateurs peuvent créer des sources d’événement. Si une source d’événement ne peut pas être créée en utilisant le nom de l’application, un avertissement est consigné dans la source Application source et les journaux d’événements sont désactivés.

Considérez la classe ServiceA suivante :

namespace SampleApp.Services;

public class ServiceA : BackgroundService
{
    public ServiceA(ILoggerFactory loggerFactory)
    {
        Logger = loggerFactory.CreateLogger<ServiceA>();
    }

    public ILogger Logger { get; }

    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        Logger.LogInformation("ServiceA is starting.");

        stoppingToken.Register(() => Logger.LogInformation("ServiceA is stopping."));

        while (!stoppingToken.IsCancellationRequested)
        {
            Logger.LogInformation("ServiceA is doing background work.");

            await Task.Delay(TimeSpan.FromSeconds(5), stoppingToken);
        }

        Logger.LogInformation("ServiceA has stopped.");
    }
}

Les appels Program.cs suivants AddHostedService pour inscrire ServiceA :

using SampleApp.Services;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorPages();

builder.Services.AddWindowsService();
builder.Services.AddHostedService<ServiceA>();

var app = builder.Build();

app.MapRazorPages();

app.Run();

Les échantillons d’applications suivants accompagnent cette rubrique :

• Exemple de service Worker en arrière-plan : échantillon d’application non web basé sur le modèle Worker Service qui utilise des services hébergés pour les tâches en arrière-plan.
• Exemple de App Service web : échantillon d’application web Pages Razor qui s’exécute en tant que service Windows avec des services hébergés pour les tâches en arrière-plan.

Pour obtenir des conseils sur MVC, consultez les articles sous Vue d’ensemble de ASP.NET Core MVC et Migrer de ASP.NET Core 2.2 à 3.0.

Type de déploiement

Pour des informations et des conseils sur les scénarios de déploiement, consultez Déploiement d’applications .NET Core.

Kit SDK

Pour un service basé sur une application web qui utilise les infrastructures Pages Razor ou MVC, spécifiez le SDK web dans le fichier projet :

<Project Sdk="Microsoft.NET.Sdk.Web">

Si le service exécute uniquement des tâches en arrière-plan (par exemple, des services hébergés), spécifiez le SDK Worker dans le fichier projet :

<Project Sdk="Microsoft.NET.Sdk.Worker">

Déploiement dépendant du framework

Un déploiement dépendant du framework s’appuie sur la présence d’une version partagée à l’échelle du système de .NET Core sur le système cible. Lorsque vous effectuez le scénario de déploiement dépendant du framework en suivant les conseils du présent article, le Kit de développement logiciel (SDK) produit un fichier exécutable (.exe), appelé fichier exécutable dépendant du framework.

Quand vous utilisez le SDK web, un fichier web.config, qui est normalement produit lors de la publication d’une application ASP.NET Core, n’est pas nécessaire pour une application de Windows Services. Pour désactiver la création d’un fichier web.config, ajoutez la propriété <IsTransformWebConfigDisabled> définie sur true.

<PropertyGroup>
  <TargetFramework>net7.0</TargetFramework>
  <IsTransformWebConfigDisabled>true</IsTransformWebConfigDisabled>
</PropertyGroup>

Déploiement autonome

Un déploiement autonome ne s’appuie sur la présence d’aucune infrastructure partagée sur le système hôte. Le runtime et les dépendances de l’application sont déployés avec l’application.

Un identificateur de runtime (RID) Windows est inclus dans l’élément <PropertyGroup> qui contient la version cible de .NET Framework :

<RuntimeIdentifier>win-x64</RuntimeIdentifier>

Pour publier pour plusieurs RID :

• Fournissez les RID dans une liste séparée par des points-virgules.
• Utilisez le nom de propriété <RuntimeIdentifiers > (au pluriel).

Pour plus d’informations, consultez le Catalogue RID .NET Core.

Compte d’utilisateur du service

Pour créer un compte d’utilisateur du service, utilisez la cmdlet New-LocalUser depuis un interpréteur de commandes d’administration PowerShell 6.

Dans la Mise à jour de Windows 10 d’octobre 2018 (version 1809/build 10.0.17763) ou plus :

New-LocalUser -Name {SERVICE NAME}

Dans un système d’exploitation Windows antérieur à la Mise à jour de Windows 10 d’octobre 2018 (version 1809/build 10.0.17763) :

powershell -Command "New-LocalUser -Name {SERVICE NAME}"

Fournissez un mot de passe fort à l’invite.

Le compte n’expire pas, sauf si le paramètre -AccountExpires est fourni à la cmdlet New-LocalUser avec un DateTime d’expiration.

Pour plus d’informations, voir Microsoft.PowerShell.LocalAccounts et Comptes d’utilisateurs de service.

Une approche alternative à la gestion des utilisateurs lors de l’utilisation d’Active Directory consiste à utiliser des Comptes de service administrés. Pour plus d’informations, consultez Vue d’ensemble des comptes de service administrés de groupe.

Droits d’ouverture de session en tant que service

Pour établir des droits d’ouverture de session en tant que service pour un compte d’utilisateur de service, procédez comme suit :

1. Ouvrez l’éditeur de stratégie de sécurité locale en exécutant le fichier secpool.msc.
2. Développez le nœud Stratégies locales et sélectionnez Attribution des droits utilisateur.
3. Ouvrez la stratégie Ouvrir une session en tant que service.
4. Sélectionnez Ajouter un utilisateur ou un groupe.
5. Fournissez le nom d’objet (compte d’utilisateur) avec l’une des approches suivantes :
   1. Tapez le compte d’utilisateur ({DOMAIN OR COMPUTER NAME\USER}) dans le champ du nom d’objet et sélectionnez OK pour ajouter l’utilisateur à la stratégie.
   2. Sélectionnez Avancé. Sélectionnez Rechercher maintenant. Sélectionnez le compte d’utilisateur dans la liste. Cliquez sur OK. Cliquez à nouveau sur OK pour ajouter l’utilisateur à la stratégie.
6. Sélectionnez OK ou Appliquer pour accepter les modifications.

Créer et gérer le service Windows

Créer un service

Utilisez les commandes PowerShell pour enregistrer un service. À partir d’un interpréteur de commandes d’administration PowerShell 6, exécutez les commandes suivantes :

$acl = Get-Acl "{EXE PATH}"
$aclRuleArgs = "{DOMAIN OR COMPUTER NAME\USER}", "Read,Write,ReadAndExecute", "ContainerInherit,ObjectInherit", "None", "Allow"
$accessRule = New-Object System.Security.AccessControl.FileSystemAccessRule($aclRuleArgs)
$acl.SetAccessRule($accessRule)
$acl | Set-Acl "{EXE PATH}"

New-Service -Name {SERVICE NAME} -BinaryPathName "{EXE FILE PATH} --contentRoot {EXE FOLDER PATH}" -Credential "{DOMAIN OR COMPUTER NAME\USER}" -Description "{DESCRIPTION}" -DisplayName "{DISPLAY NAME}" -StartupType Automatic

• {EXE PATH} : Chemin d’accès de l’exécutable de l’application sur l’hôte (par exemple, d:\myservice). N’incluez pas le nom du fichier exécutable de l’application dans le chemin. Aucune barre oblique de fin n’est nécessaire.
• {DOMAIN OR COMPUTER NAME\USER} : Compte d’utilisateur du service (par exemple, Contoso\ServiceUser).
• {SERVICE NAME} : Nom du service (par exemple, MyService).
• {EXE FILE PATH} : Chemin d’accès complet du fichier exécutable de l’application (par exemple, d:\myservice\myservice.exe). Incluez le nom de fichier de l’exécutable avec l’extension.
• {EXE FOLDER PATH}: Chemin d’accès complet du dossier exécutable de l’application (par exemple d:\myservice).
• {DESCRIPTION} : Description du service (par exemple, My sample service).
• {DISPLAY NAME} : Nom d’affichage du service (par exemple, My Service).

Démarrer un service

Démarrez un service avec la commande PowerShell 6 suivante :

Start-Service -Name {SERVICE NAME}

La commande prend quelques secondes pour démarrer le service.

Déterminer l’état d’un service

Pour vérifier l’état d’un service, utilisez la commande PowerShell 6 suivante :

Get-Service -Name {SERVICE NAME}

L’état est signalé comme étant l’une des valeurs suivantes :

• Starting
• Running
• Stopping
• Stopped

Arrêter un service

Arrêtez un service avec la commande PowerShell 6 suivante :

Stop-Service -Name {SERVICE NAME}

Supprimer un service

Après un court délai pour arrêter un service, supprimez-le avec la commande PowerShell 6 suivante :

Remove-Service -Name {SERVICE NAME}

Scénarios avec un serveur proxy et un équilibreur de charge

Les services qui interagissent avec les requêtes provenant d’Internet ou d’un réseau d’entreprise et qui se trouvent derrière un proxy ou équilibreur de charge peuvent nécessiter une configuration supplémentaire. Pour plus d’informations, consultez l’article Configurer ASP.NET Core pour l’utilisation de serveurs proxy et d’équilibreurs de charge.

Configuration des points de terminaison

Par défaut, ASP.NET Core est lié à http://localhost:5000. Configurez l’URL et le port en définissant la variable d’environnement ASPNETCORE_URLS.

Pour obtenir d’autres approches de configuration d’URL et de port, consultez l’article serveur approprié :

• Configurer des points de terminaison pour le serveur web ASP.NET Core Kestrel
• Implémentation de serveur web HTTP.sys dans ASP.NET Core

Les conseils précédents couvrent la prise en charge des points de terminaison HTTPS. Par exemple, configurez l’application pour HTTPS lorsque l’authentification est utilisée avec un service Windows.

Remarque

L’utilisation du certificat de développement HTTPS ASP.NET Core pour sécuriser un point de terminaison de service n’est pas prise en charge.

Répertoire actif et racine du contenu

Le répertoire de travail actif retourné par l’appel à GetCurrentDirectory pour un service Windows est le dossier C:\WINDOWS\system32. Le dossier system32 n’est pas un emplacement approprié pour stocker les fichiers d’un service (tels que les fichiers de paramètres). Utilisez une des approches suivantes pour gérer les ressources ainsi que les fichiers de paramètres d’un service, et y accéder.

Utiliser ContentRootPath ou ContentRootFileProvider

Utilisez les éléments IHostEnvironment.ContentRootPath ou ContentRootFileProvider pour localiser les ressources d’une application.

Lorsque l’application s’exécute en tant que service, UseWindowsService définit ContentRootPath sur AppContext.BaseDirectory.

Les fichiers de paramètres par défaut de l’application, appsettings.json et appsettings.{Environment}.json, sont chargés à partir de la racine de contenu de l’application en appelant CreateDefaultBuilder pendant la construction de l’hôte.

Pour les autres fichiers de paramètres chargés par le code du développeur dans ConfigureAppConfiguration, il n’est pas nécessaire d’appeler SetBasePath. Dans l’exemple suivant, le fichiercustom_settings.json existe à la racine de contenu de l’application et est chargé sans définir explicitement de chemin d’accès de base :

public class Program
{
    public static void Main(string[] args)
    {
        CreateHostBuilder(args).Build().Run();
    }

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .UseWindowsService()
            .ConfigureAppConfiguration((hostingContext, config) =>
            {
                config.AddJsonFile("custom_settings.json");
            })
            .ConfigureServices((hostContext, services) =>
            {
                services.AddHostedService<Worker>();
            });
}

N’essayez pas d’utiliser GetCurrentDirectory pour obtenir un chemin d’accès aux ressources, car une application de service Windows retourne le dossier C:\WINDOWS\system32 comme répertoire actif.

Stocker les fichiers d’un service dans un emplacement approprié sur le disque

Spécifiez un chemin absolu avec SetBasePath, si vous utilisez IConfigurationBuilder, vers le dossier contenant les fichiers.

Résoudre les problèmes

Pour résoudre les problèmes d’une application de service Windows, consultez Résoudre les problèmes et déboguer les projets ASP.NET Core.

Erreurs courantes

• Une version antérieure ou préversion de PowerShell est en cours d’utilisation.
• Le service inscrit n’utilise pas la sortie publiée de l’application à partir de la commande dotnet publish. La sortie de la commande dotnet build n’est pas prise en charge pour le déploiement d’applications. Les ressources publiées se trouvent dans l’un des dossiers suivants en fonction du type de déploiement :
  • bin/Release/{TARGET FRAMEWORK}/publish (FDD)
  • bin/Release/{TARGET FRAMEWORK}/{RUNTIME IDENTIFIER}/publish (SCD)
• Le service n’est pas à l’état EN COURS D’EXÉCUTION.
• Les chemins d’accès aux ressources que l’application utilise (par exemple, les certificats) sont incorrects. Le chemin d’accès de base d’un service Windows est c:\Windows\System32.
• L’utilisateur ne dispose pas des droits d’ouverture de session en tant que service.
• Le mot de passe de l’utilisateur a expiré ou est passé de manière incorrecte lors de l’exécution de la commande PowerShell New-Service.
• L’application nécessite ASP.NET Core authentification, mais n’est pas configurée pour les connexions sécurisées (HTTPS).
• Le port d’URL de requête est incorrect ou n’est pas configuré correctement dans l’application.

Journaux des événements système et d’application

Accédez aux journaux des événements système et application :

1. Ouvrez le menu Démarrer, recherchez Observateur d’événements, puis sélectionnez l’application Observateur d’événements.
2. Dans Observateur d’événements, ouvrez le nœud Journaux Windows.
3. Sélectionnez Système pour ouvrir le journal des événements système. Sélectionnez Application pour ouvrir le Journal des événements de l’application.
4. Recherchez les erreurs liées à l’application défectueuse.

Exécuter l’application depuis une invite de commandes

De nombreuses erreurs de démarrage ne produisent pas d’informations utiles dans les journaux des événements. Vous pouvez trouver la cause de certaines erreurs en exécutant l’application depuis une invite de commandes sur le système hôte. Pour enregistrer des détails supplémentaires à partir de l’application, réduisez le niveau du journal ou exécutez l’application dans l’environnement de développement.

Effacer les caches de package

Une application fonctionnelle peut échouer immédiatement après la mise à niveau du kit SDK .NET Core sur l’ordinateur de développement ou la modification des versions de package au sein de l’application. Dans certains cas, les packages incohérents peuvent bloquer une application quand vous effectuez des mises à niveau majeures. Vous pouvez résoudre la plupart de ces problèmes en suivant les instructions suivantes :

1. Supprimez les dossiers bin et obj.

2. Effacez les caches de package en exécutant dotnet nuget locals all --clear à partir d’un interpréteur de commandes.

   Vous pouvez également effacer les caches de package en utilisant l’outil nuget.exe et en exécutant la commande nuget locals all -clear. NuGet.exe n’étant pas une installation fournie avec le système d’exploitation de bureau Windows, il doit être obtenu séparément à partir du site web de NuGet.

3. Restaurez et regénérez le projet.

4. Supprimez tous les fichiers du dossier de déploiement sur le serveur avant de redéployer l’application.

Application lente ou qui ne répond pas

Un fichier image mémoire après incident est un instantané de la mémoire système et peut aider à déterminer la cause de l’arrêt d’une application, d’un échec de démarrage ou de la lenteur d’une application.

L’application cesse de fonctionner ou rencontre une exception

Obtenez un fichier dump et analysez-le depuis le Rapport d'erreurs Windows :

1. Créez un dossier pour accueillir les fichiers d’image mémoire dans c:\dumps.

2. Exécutez le script PowerShell EnableDumps avec le nom de l’exécutable de l’application :

   .\EnableDumps {APPLICATION EXE} c:\dumps
   

3. Exécutez l’application en reproduisant les conditions ayant entraîné l’incident.

4. Une fois l’incident survenu, exécutez le script PowerShell DisableDumps :

   .\DisableDumps {APPLICATION EXE}
   

Après l’arrêt de l’application et après avoir terminé la collection dump, l’application peut être fermée normalement. Le script PowerShell configure le rapport d’erreurs Windows pour collecter jusqu'à cinq fichiers dump par application.

Avertissement

Les fichiers dump d’incident peuvent occuper plus d’espace disque (jusqu’à plusieurs gigaoctets par fichier).

L’application ne répond pas, ne démarre pas ou s’exécute normalement

Lorsqu’une application cesse de répondre sans s’interrompre, plante au démarrage ou s’exécute normalement, consultez Fichiers d’image mémoire en mode utilisateur : choisir le meilleur outil afin de sélectionner un outil approprié pour produire l’image mémoire.

Analyser le fichier dump

Un fichier dump peut être analysé à l’aide de plusieurs approches. Pour plus d’informations, consultez Analyzing a User-Mode Dump File (Analyser un fichier dump en mode utilisateur).

Ressources supplémentaires

• Affichez ou téléchargez l’exemple de code (procédure de téléchargement)
• Configuration de point de terminaison Kestrel (inclut la configuration de HTTPS et la prise en charge de SNI)
• Hôte générique .NET dans ASP.NET Core
• Résoudre les problèmes et effectuer le débogage des projets ASP.NET Core