Ospitare ASP.NET Core in un servizio Windows

È possibile ospitare un'app ASP.NET Core in Windows come servizio Windows senza usare IIS. Quando è ospitata come servizio di Windows, l'app viene avviata automaticamente dopo il riavvio del server.

Prerequisiti

• ASP.NET Core SDK 7.0 o versione successiva
• PowerShell 6.2 o versione successiva

Modello di servizio di ruolo di lavoro

Il modello di servizio di ruolo di lavoro di ASP.NET Core rappresenta un punto di partenza per la scrittura di app di servizi a esecuzione prolungata. Per usare il modello come base per un'app di servizio Windows:

1. Creare un'app di servizio di ruolo di lavoro dal modello .NET Core.
2. Installare il pacchetto NuGet Microsoft.Extensions.Hosting.WindowsServices.
3. Seguire le indicazioni nella sezione Configurazione dell'app per aggiornare l'app di servizio di ruolo di lavoro affinché venga eseguita come servizio Windows.

Visual Studio

1. Creare un nuovo progetto.
2. Selezionare Servizio di lavoro. Selezionare Avanti.
3. Specificare il nome di un progetto nel campo Nome progetto oppure accettare il nome predefinito. Seleziona Crea.
4. Nella finestra di dialogo Crea un nuovo servizio di lavoro selezionare Crea.

Visual Studio per Mac

1. Creare un nuovo progetto.
2. Selezionare App in .NET Core nella barra laterale.
3. Selezionare Ruolo di lavoro in ASP.NET Core. Selezionare Avanti.
4. Selezionare .NET Core 3.0 o versione successiva per Framework di destinazione. Selezionare Avanti.
5. Specificare un nome nel campo Nome progetto. Seleziona Crea.

CLI .NET

Usare il servizio di ruolo di lavoro (worker) con il comandodotnet new da una shell dei comandi. Nell'esempio seguente viene creata un'app del servizio di ruolo di lavoro denominata ContosoWorker. Una cartella per l'app ContosoWorker viene creata automaticamente quando viene eseguito il comando.

dotnet new worker -o ContosoWorker

Configurazione dell'app

Aggiornare Program.cs per chiamare AddWindowsService. Quando l'app è in esecuzione come servizio Windows, AddWindowsService:

• Imposta la durata dell'host su WindowsServiceLifetime.
• Imposta la radice del contenuto su AppContext.BaseDirectory. Per altre informazioni, vedere la sezione Directory corrente e radice del contenuto.
• Abilita la registrazione nel registro eventi:
  • Il nome dell'applicazione viene usato come nome di origine predefinito.
  • Il livello di log predefinito è Avviso o superiore per un'app basata su un modello ASP.NET Core che chiama CreateDefaultBuilder per compilare l'host.
  • Eseguire l'override del livello di log predefinito con la Logging:EventLog:LogLevel:Default chiave in appsettings.json/appsettings.{Environment}.json o un altro provider di configurazione.
  • Solo gli amministratori possono creare nuove origini eventi. Quando non è possibile creare un'origine evento usando il nome dell'applicazione, viene registrato un avviso nell'origine Applicazione e i log eventi vengono disabilitati.

Si consideri la classe ServiceA seguente:

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

Le chiamate AddHostedService seguenti Program.cs per registrare 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();

Le app di esempio seguenti accompagnano questo argomento:

• Esempio di servizio di lavoro in background: esempio di app non Web basato sul modello del servizio di lavoro che usa servizi ospitati per le attività in background.
• Esempio di web servizio app: un'app Razor Web Pages che viene eseguita come servizio Windows con servizi ospitati per le attività in background.

Per indicazioni su MVC, vedere gli articoli in Panoramica di ASP.NET Core MVC e Migrazione da ASP.NET Core 2.2 a 3.0.

Tipo di distribuzione

Per informazioni e consigli sugli scenari di distribuzione, vedere Distribuzione di applicazioni .NET Core.

SDK

Per un servizio basato su app Web che usa i Razor framework Pages o MVC, specificare Web SDK nel file di progetto:

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

Se il servizio esegue solo attività in background ,ad esempio servizi ospitati, specificare Worker SDK nel file di progetto:

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

Distribuzione dipendente dal framework

La distribuzione dipendente dal framework si basa sulla presenza di una versione condivisa a livello di sistema di .NET Core nel sistema di destinazione. Quando lo scenario di distribuzione dipendente dal framework viene implementato in base alle indicazioni di questo articolo, l'SDK genera un file eseguibile (con estensione exe) detto eseguibile dipendente dal framework.

Se si usa Web SDK, un file web.config , normalmente generato durante la pubblicazione di un'app ASP.NET Core, non è necessario per un'app di Servizi Windows. Per disabilitare la creazione del file web.config, aggiungere la proprietà <IsTransformWebConfigDisabled> impostata su true.

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

Distribuzione autonoma

Una distribuzione autonoma non si basa sulla presenza di un framework condiviso nel sistema host. Il runtime e le dipendenze dell'app vengono distribuiti con l'app.

Un identificatore di runtime (RID) di Windows viene incluso nel <PropertyGroup> che contiene il framework di destinazione:

<RuntimeIdentifier>win-x64</RuntimeIdentifier>

Per eseguire la pubblicazione per più identificatori di runtime:

• Specificare gli identificatori di runtime in un elenco delimitato da punto e virgola.
• Usare il nome <della proprietà RuntimeIdentifiers> (plurale).

Per altre informazioni, vedere il Catalogo RID di .NET Core.

Account utente del servizio

Per creare un account utente per un servizio, usare il cmdlet New-LocalUser da una shell dei comandi di PowerShell 6 amministrativa.

In Aggiornamento di Windows 10 (ottobre 2018) (versione 1809/build 10.0.17763) o versioni successive:

New-LocalUser -Name {SERVICE NAME}

In un sistema operativo Windows precedente ad Aggiornamento di Windows 10 (ottobre 2018) (versione 1809/build 10.0.17763):

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

Fornire una password complessa quando richiesto.

Se non viene specificato il parametro -AccountExpires per il cmdlet New-LocalUser con un valore DateTime di scadenza, l'account non scade.

Per altre informazioni, vedere Microsoft.PowerShell.LocalAccounts e Service User Accounts (Account utente di servizio).

Un approccio alternativo per la gestione degli utenti quando si usa Active Directory consiste nell'usare account del servizio gestito. Per altre informazioni, vedere Panoramica degli account del servizio gestito del gruppo.

Diritti Accesso come servizio

Per stabilire i diritti Accesso come servizio per un account utente di servizio:

1. Aprire l'editor Criteri di sicurezza locali eseguendo secpol.msc.
2. Espandere il nodo Criteri locali e selezionare Assegnazione diritti utente.
3. Aprire il criterio Accesso come servizio.
4. Selezionare Aggiungi utente o gruppo.
5. Specificare il nome dell'oggetto (account utente) usando uno degli approcci seguenti:
   1. Digitare l'account utente ({DOMAIN OR COMPUTER NAME\USER}) nel campo del nome oggetto e scegliere OK per aggiungere l'utente al criterio.
   2. Seleziona Avanzate. Selezionare Trova. Selezionare l'account utente dall'elenco. Seleziona OK. Scegliere di nuovo OK per aggiungere l'utente al criterio.
6. Scegliere OK o Applica per accettare le modifiche.

Creare e gestire il servizio di Windows

Creare un servizio

Usare i comandi di PowerShell per registrare un servizio. Da una shell dei comandi di PowerShell 6 amministrativa eseguire i comandi seguenti:

$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}: percorso dell'eseguibile dell'app nell'host (ad esempio, d:\myservice). Non includere il nome del file eseguibile dell'app nel percorso. Non è necessario aggiungere una barra finale.
• {DOMAIN OR COMPUTER NAME\USER}: account utente del servizio (ad esempio, Contoso\ServiceUser).
• {SERVICE NAME}: nome del servizio (ad esempio, MyService).
• {EXE FILE PATH}: percorso eseguibile completo dell'app (ad esempio, d:\myservice\myservice.exe). Includere il nome del file eseguibile con l'estensione.
• {EXE FOLDER PATH}: percorso completo della cartella eseguibile dell'app , ad esempio d:\myservice.
• {DESCRIPTION}: descrizione del servizio (ad esempio, My sample service).
• {DISPLAY NAME}: nome visualizzato del servizio (ad esempio, My Service).

Avviare un servizio

Per avviare un servizio, usare il comando di PowerShell 6 seguente:

Start-Service -Name {SERVICE NAME}

L'avvio del servizio richiede alcuni secondi.

Determinare lo stato di un servizio

Per verificare lo stato di un servizio, usare il comando di PowerShell 6 seguente:

Get-Service -Name {SERVICE NAME}

Lo stato viene indicato con uno dei valori seguenti:

• Starting
• Running
• Stopping
• Stopped

Arrestare un servizio

Arrestare un servizio con il comando di PowerShell 6 seguente:

Stop-Service -Name {SERVICE NAME}

Rimuovere un servizio

Dopo un breve ritardo per arrestare un servizio, rimuovere un servizio con il comando di PowerShell 6 seguente:

Remove-Service -Name {SERVICE NAME}

Scenari con server proxy e servizi di bilanciamento del carico

I servizi che interagiscono con le richieste da Internet o da una rete aziendale e si trovano dietro un proxy o un servizio di bilanciamento del carico potrebbero richiedere una configurazione aggiuntiva. Per altre informazioni, vedere Configurare ASP.NET Core per l'utilizzo di server proxy e servizi di bilanciamento del carico.

Configurare gli endpoint

Per impostazione predefinita, ASP.NET Core è associato a http://localhost:5000. Configurare l'URL e la porta impostando la ASPNETCORE_URLS variabile di ambiente.

Per altri approcci alla configurazione di URL e porte, vedere l'articolo relativo al server:

• Configurare gli endpoint per il server Web ASP.NET Core Kestrel
• HTTP.sys'implementazione del server Web in ASP.NET Core

Le indicazioni precedenti illustrano il supporto per gli endpoint HTTPS. Ad esempio, configurare l'app per HTTPS quando viene usata l'autenticazione con un servizio Windows.

Nota

L'uso del certificato di sviluppo ASP.NET Core HTTPS per proteggere un endpoint del servizio non è supportato.

Directory corrente e radice del contenuto

La directory di lavoro corrente restituita dalla chiamata di GetCurrentDirectory per un servizio Windows è la cartella C:\WINDOWS\system32. La cartella system32 non è un percorso appropriato per archiviare i file di un servizio, ad esempio i file di impostazioni. Usare uno degli approcci seguenti per gestire e accedere agli asset e ai file di impostazioni di un servizio.

Usare ContentRootPath o ContentRootFileProvider

Usare IHostEnvironment.ContentRootPath o ContentRootFileProvider per individuare le risorse di un'app.

Quando l'app viene eseguita come servizio, UseWindowsService imposta su ContentRootPath AppContext.BaseDirectory.

I file appsettings.json di impostazioni predefiniti dell'app e appsettings.{Environment}.json, vengono caricati dalla radice del contenuto dell'app chiamando CreateDefaultBuilder durante la costruzione dell'host.

Per altri file di impostazioni caricati dal codice dello sviluppatore in ConfigureAppConfiguration, non è necessario chiamare SetBasePath. Nell'esempio seguente il custom_settings.json file esiste nella radice del contenuto dell'app e viene caricato senza impostare in modo esplicito un percorso di 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>();
            });
}

Non tentare di usare GetCurrentDirectory per ottenere un percorso di risorsa perché un'app del servizio Windows restituisce la cartella C:\WINDOWS\system32 come directory corrente.

Archiviare i file di un servizio in un percorso appropriato nel disco

Specificare un percorso assoluto con SetBasePath quando si usa un IConfigurationBuilder per la cartella contenente i file.

Risoluzione dei problemi

Per risolvere i problemi relativi a un'app del servizio Windows, vedere Risolvere i problemi ed eseguire il debug di progetti di base ASP.NET.

Errori comuni

• È in uso una versione precedente o non definitiva di PowerShell.
• Il servizio registrato non usa l'output pubblicato dell'app dal comando dotnet publish. L'output del comando dotnet build non è supportato per la distribuzione di app. Gli asset pubblicati si trovano in una delle cartelle seguenti a seconda del tipo di distribuzione:
  • bin/Release/{TARGET FRAMEWORK}/publish (FDD)
  • bin/Release/{TARGET FRAMEWORK}/{RUNTIME IDENTIFIER}/publish (SCD)
• Il servizio non è nello stato RUNNING.
• I percorsi delle risorse usate dall'app ,ad esempio certificati, non sono corretti. Il percorso di base di un servizio Windows è c:\Windows\System32.
• L'utente non dispone dei diritti di accesso come servizio .
• La password dell'utente è scaduta o non è stata passata correttamente durante l'esecuzione del New-Service comando di PowerShell.
• L'app richiede ASP.NET'autenticazione core, ma non è configurata per le connessioni sicure (HTTPS).
• La porta dell'URL della richiesta non è corretta o non è configurata correttamente nell'app.

Registri eventi di sistema e applicazioni

Accedere ai registri eventi di sistema e applicazione:

1. Aprire il menu Start, cercare Visualizzatore eventi e selezionare l'app Visualizzatore eventi.
2. In Visualizzatore eventi aprire il nodo Registri di Windows.
3. Selezionare Sistema per aprire il registro eventi di sistema. Selezionare Applicazione per aprire il log eventi dell'applicazione.
4. Cercare gli errori associati all'app in cui si è verificato il problema.

Eseguire l'app da un prompt dei comandi

Molti errori di avvio non producono informazioni utili nei registri eventi. È possibile individuare la causa di alcuni errori eseguendo l'app da un prompt dei comandi nel sistema host. Per registrare dettagli aggiuntivi dall'app, abbassare il livello di log o eseguire l'app nell'ambiente di sviluppo.

Cancellare le cache dei pacchetti

Un'app funzionante potrebbe non riuscire immediatamente dopo l'aggiornamento di .NET Core SDK nel computer di sviluppo o la modifica delle versioni dei pacchetti all'interno dell'app. In alcuni casi i pacchetti incoerenti possono interrompere un'app quando si eseguono aggiornamenti principali. La maggior parte di questi problemi può essere risolta attenendosi alle istruzioni seguenti:

1. Eliminare le cartelle bin e obj.

2. Cancellare le cache dei pacchetti eseguendo dotnet nuget locals all --clear da una shell dei comandi.

   La cancellazione delle cache dei pacchetti può essere eseguita anche con lo strumento nuget.exe ed eseguendo il comando nuget locals all -clear. nuget.exe non è un'installazione inclusa con il sistema operativo desktop Windows e deve essere ottenuta separatamente dal sito Web NuGet.

3. Ripristinare e ricompilare il progetto.

4. Eliminare tutti i file nella cartella di distribuzione nel server prima di ridistribuire l'app.

App lenta o non risponde

Un dump di arresto anomalo del sistema è uno snapshot della memoria del sistema e può aiutare a determinare la causa di un arresto anomalo dell'app, un errore di avvio o un'app lenta.

Arresto anomalo o eccezione di un'app

Ottenere e analizzare un dump da Segnalazione errori Windows:

1. Creare una cartella per i file dump di arresto anomalo del sistema in c:\dumps.

2. Eseguire lo script di PowerShell EnableDumps con il nome eseguibile dell'applicazione:

   .\EnableDumps {APPLICATION EXE} c:\dumps
   

3. Eseguire l'app nelle condizioni che causano l'arresto anomalo.

4. Dopo che si è verificato l'arresto anomalo, eseguire lo script di PowerShell DisableDumps:

   .\DisableDumps {APPLICATION EXE}
   

Dopo l'arresto anomalo di un'app e la raccolta dei dump, l'app può terminare normalmente. Lo script di PowerShell configura Segnalazione errori Windows per raccogliere fino a cinque dump per ogni app.

Avviso

I dump di arresto anomalo del sistema potrebbero richiedere una grande quantità di spazio su disco (fino a diversi gigabyte ognuno).

L'app non risponde, non riesce durante l'avvio o viene eseguita normalmente

Quando un'app smette di rispondere ma non si arresta in modo anomalo, non riesce durante l'avvio o viene eseguita normalmente, vedi File di dump in modalità utente: scelta dello strumento migliore per selezionare uno strumento appropriato per produrre il dump.

Analizzare il dump

È possibile analizzare un dump usando diversi approcci. Per altre informazioni, vedere Analyzing a User-Mode Dump File (Analisi di un file dump in modalità utente).

Risorse aggiuntive

• Visualizzare o scaricare il codice di esempio (procedura per il download)
• Kestrel configurazione dell'endpoint (include la configurazione HTTPS e il supporto SNI)
• Host generico .NET in ASP.NET Core
• Risolvere i problemi ed eseguire il debug di progetti ASP.NET Core