Host ASP.NET Core in een Windows-service

Een ASP.NET Core-app kan worden gehost in Windows als een Windows-service zonder IIS te gebruiken. Wanneer de app wordt gehost als een Windows-service, wordt de app automatisch gestart nadat de server opnieuw is opgestart.

Voorwaarden

• ASP.NET Core SDK 7.0 of hoger
• PowerShell 6.2 of hoger

Worker Service-sjabloon

De ASP.NET Core Worker Service-sjabloon biedt een startpunt voor het schrijven van langlopende service-apps. De sjabloon gebruiken als basis voor een Windows Service-app:

1. Maak een Worker Service-app op basis van de .NET Core-sjabloon.
2. Installeer het NuGet-pakket Microsoft.Extensions.Hosting.WindowsServices.
3. Volg de richtlijnen in de sectie App-configuratie om de Worker Service-app bij te werken, zodat deze kan worden uitgevoerd als een Windows-service.

Visual Studio

1. Maak een nieuw project.
2. Selecteer Worker Service. Kies Volgende.
3. Geef een projectnaam op in het veld Projectnaam of accepteer de standaardprojectnaam. Selecteer Maakaan.
4. Selecteer in het dialoogvenster Een nieuwe werkservice makenmaken.

Visual Studio voor Mac-

1. Maak een nieuw project.
2. Selecteer App- onder .NET Core- in de zijbalk.
3. Selecteer Worker onder ASP.NET Core. Kies Volgende.
4. Selecteer .NET Core 3.0 of hoger voor de Target Framework-. Selecteer Volgende.
5. Geef een naam op in het veld Projectnaam. Selecteer Maak.

.NET CLI

Gebruik de sjabloon Worker Service (worker) met de opdracht dotnet new vanuit een opdrachtprompt. In het volgende voorbeeld wordt een Worker Service-app gemaakt met de naam ContosoWorker. Er wordt automatisch een map voor de ContosoWorker-app gemaakt wanneer de opdracht wordt uitgevoerd.

dotnet new worker -o ContosoWorker

App-configuratie

Werk Program.cs bij om AddWindowsServiceaan te roepen. Wanneer de app wordt uitgevoerd als een Windows-service, AddWindowsService:

• Hiermee stelt u de levensduur van de host in op WindowsServiceLifetime.
• Hiermee stelt u de inhoudshoofdmap in op AppContext.BaseDirectory. Zie de sectie Huidige map en inhoudshoofdmap voor meer informatie.
• Schakelt logboekregistratie in het gebeurtenislogboek in.
  • De naam van de toepassing wordt gebruikt als de standaardbronnaam.
  • Het standaardlogboekniveau is Waarschuwing of hoger voor een app op basis van een ASP.NET Core-sjabloon die CreateDefaultBuilder aanroept om de host te bouwen.
  • Overschrijf het standaardlogboekniveau met de Logging:EventLog:LogLevel:Default-sleutel in appsettings.json/appsettings.{Environment}.json of een andere configuratieprovider.
  • Alleen beheerders kunnen nieuwe gebeurtenisbronnen maken. Wanneer een gebeurtenisbron niet kan worden gecreëerd met behulp van de naam van de toepassing, wordt er een waarschuwing geregistreerd bij de Application-bron en worden de gebeurtenislogboeken uitgeschakeld.

Houd rekening met de volgende ServiceA klasse:

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

De volgende Program.cs roept AddHostedService aan om ServiceAte registreren:

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

De volgende voorbeeld-apps begeleiden bij dit onderwerp:

• Voorbeeld van een Background Worker Service: een niet-webapplicatievoorbeeld gebaseerd op de Worker Service-sjabloon, dat gebruik maakt van gehoste services voor achtergrondtaken.
• Web App Service-voorbeeld: een voorbeeld van een webapp die als een Windows-service draait met Razor pagina's en gehoste services voor achtergrondtaken.

Zie de artikelen onder Overzicht van ASP.NET Core MVC- en Migreren van ASP.NET Core 2.2 naar 3.0voor MVC-richtlijnen.

Implementatietype

Zie .NET Core-toepassingsimplementatievoor informatie en advies over implementatiescenario's.

SDK

Voor een web-app-service die gebruikmaakt van de Razor Pages- of MVC-frameworks, geeft u de Web SDK op in het projectbestand:

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

Als de service alleen achtergrondtaken uitvoert (bijvoorbeeld gehoste services), geeft u de Worker SDK op in het projectbestand:

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

Frameworkafhankelijke implementatie (FDD)

Frameworkafhankelijke implementatie (FDD) is afhankelijk van de aanwezigheid van een gedeelde systeembrede versie van .NET Core op het doelsysteem. Wanneer het FDD-scenario wordt aangenomen volgens de richtlijnen in dit artikel, produceert de SDK een uitvoerbaar bestand (.exe), een frameworkafhankelijk uitvoerbaregenoemd.

Als u de Web SDK-gebruikt, is een web.config-bestand, dat normaal gesproken wordt geproduceerd bij het publiceren van een ASP.NET Core-app, niet nodig voor een Windows Services-app. Als u het maken van het web.config-bestand wilt uitschakelen, voegt u de eigenschap <IsTransformWebConfigDisabled> toe die is ingesteld op true.

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

Zelf-ingesloten implementatie (SCD)

Zelfstandige implementatie (SCD) is niet afhankelijk van de aanwezigheid van een gedeeld framework op het hostsysteem. De runtime en de afhankelijkheden van de app worden geïmplementeerd met de app.

Een RID- (Windows Runtime Identifier) is opgenomen in de die het doelframework bevat:

<RuntimeIdentifier>win-x64</RuntimeIdentifier>

Publiceren voor meerdere RIDs:

• Geef de RID's op in een door puntkomma's gescheiden lijst.
• Gebruik de naam van de eigenschap <RuntimeIdentifiers> (meervoud).

Zie .NET Core RID Catalogvoor meer informatie.

Service-gebruikersaccount

Als u een gebruikersaccount voor een service wilt maken, gebruikt u de cmdlet New-LocalUser vanuit een powerShell 6-opdrachtshell met beheerdersrechten.

Op windows 10 oktober 2018 update (versie 1809/build 10.0.17763) of hoger:

New-LocalUser -Name {SERVICE NAME}

Op het Windows-besturingssysteem ouder dan de Update van Windows 10 oktober 2018 (versie 1809/build 10.0.17763):

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

Geef een sterk wachtwoord op wanneer hierom wordt gevraagd.

Tenzij de parameter -AccountExpires wordt opgegeven bij de cmdlet New-LocalUser met een vervaldatum DateTime, verloopt het account niet.

Zie Microsoft.PowerShell.LocalAccounts en Service User Accountsvoor meer informatie.

Een alternatieve benadering voor het beheren van gebruikers bij het gebruik van Active Directory is het gebruik van beheerde serviceaccounts. Zie Overzicht van beheerde serviceaccounts voor groepenvoor meer informatie.

Inloggen met service rechten

Als u aanmelden als een service wilt instellen rechten voor een servicegebruikersaccount:

1. Open de editor voor lokaal beveiligingsbeleid door secpol.mscuit te voeren.
2. Vouw het knooppunt Lokaal Beleid uit en selecteer Toewijzing van Gebruikersrechten.
3. Open het beleid Aanmelden als een service.
4. Selecteer gebruiker of groep toevoegen.
5. Geef de objectnaam (gebruikersaccount) op met een van de volgende methoden:
   1. Typ het gebruikersaccount ({DOMAIN OR COMPUTER NAME\USER}) in het objectnaamveld en selecteer OK- om de gebruiker toe te voegen aan het beleid.
   2. Selecteer Geavanceerde. Selecteer Nu zoeken. Selecteer het gebruikersaccount in de lijst. Selecteer OK-. Selecteer opnieuw OK om de gebruiker aan het beleid toe te voegen.
6. Selecteer OK- of Pas toe om de wijzigingen te accepteren.

De Windows-service maken en beheren

Een service maken

Gebruik PowerShell-opdrachten om een service te registreren. Voer vanuit een PowerShell 6-opdrachtshell met beheerdersrechten de volgende opdrachten uit:

$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}: Pad van het uitvoerbare bestand van de app op de host (bijvoorbeeld d:\myservice). Neem de naam van het uitvoerbare bestand van de app niet op in het pad. Een afsluitende slash is niet vereist.
• {DOMAIN OR COMPUTER NAME\USER}: Servicegebruikeraccount (bijvoorbeeld Contoso\ServiceUser).
• {SERVICE NAME}: Servicenaam (bijvoorbeeld MyService).
• {EXE FILE PATH}: het volledige uitvoerbare pad van de app (bijvoorbeeld d:\myservice\myservice.exe). Neem de bestandsnaam van het uitvoerbare bestand op met de extensie.
• {EXE FOLDER PATH}: het volledige uitvoerbare mappad van de app (bijvoorbeeld d:\myservice).
• {DESCRIPTION}: servicebeschrijving (bijvoorbeeld My sample service).
• {DISPLAY NAME}: weergavenaam van de service (bijvoorbeeld My Service).

Een service starten

Start een service met de volgende PowerShell 6-opdracht:

Start-Service -Name {SERVICE NAME}

Het duurt enkele seconden voordat de opdracht de service start.

De status van een service bepalen

Gebruik de volgende PowerShell 6-opdracht om de status van een service te controleren:

Get-Service -Name {SERVICE NAME}

De status wordt gerapporteerd als een van de volgende waarden:

• Starting
• Running
• Stopping
• Stopped

Een service stoppen

Stop een service met de volgende PowerShell 6-opdracht:

Stop-Service -Name {SERVICE NAME}

Een service verwijderen

Na een korte vertraging om een service te stoppen, verwijdert u een service met de volgende PowerShell 6-opdracht:

Remove-Service -Name {SERVICE NAME}

Scenario's voor proxyserver en load balancer

Services die communiceren met aanvragen van internet of een bedrijfsnetwerk en zich achter een proxy of load balancer bevinden, vereisen mogelijk extra configuratie. Zie ASP.NET Core configureren voor gebruik met proxyservers en load balancersvoor meer informatie.

Eindpunten configureren

Standaard wordt ASP.NET Core gebonden aan http://localhost:5000. Configureer de URL en poort door de ASPNETCORE_URLS omgevingsvariabele in te stellen.

Zie het relevante serverartikel voor aanvullende URL- en poortconfiguratiemethoden:

• Eindpunten configureren voor de ASP.NET Core Kestrel webserver
• HTTP.sys webserver-implementatie in ASP.NET Core

De voorgaande richtlijnen hebben betrekking op ondersteuning voor HTTPS-eindpunten. Configureer bijvoorbeeld de app voor HTTPS wanneer verificatie wordt gebruikt met een Windows-service.

Notitie

Het gebruik van het ASP.NET Core HTTPS-ontwikkelingscertificaat voor het beveiligen van een service-eindpunt wordt niet ondersteund.

Huidige map en inhoudsroot

De huidige werkmap die wordt geretourneerd door GetCurrentDirectory aan te roepen voor een Windows-service, is de map C:\WINDOWS\system32. De map system32 is geen geschikte locatie voor het opslaan van de bestanden van een service (bijvoorbeeld instellingenbestanden). Gebruik een van de volgende methoden om de assets en instellingenbestanden van een service te onderhouden en te openen.

ContentRootPath of ContentRootFileProvider gebruiken

Gebruik IHostEnvironment.ContentRootPath of ContentRootFileProvider om de resources van een app te vinden.

Wanneer de app wordt uitgevoerd als een service, stelt UseWindowsService de ContentRootPath in op AppContext.BaseDirectory-.

De standaardinstellingenbestanden van de app, appsettings.json en appsettings.{Environment}.json, worden geladen vanuit de inhoudsroot van de app door de functie CreateDefaultBuilder aan te roepen tijdens de constructie van de host.

Voor andere instellingenbestanden die door ontwikkelaarscode in ConfigureAppConfigurationzijn geladen, hoeft u SetBasePathniet aan te roepen. In het volgende voorbeeld bestaat het custom_settings.json bestand in de hoofdmap van de app en wordt geladen zonder expliciet een basispad in te stellen:

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

Probeer geen GetCurrentDirectory te gebruiken om een resourcepad te verkrijgen omdat een Windows Service-app de map C:\WINDOWS\system32 als huidige map retourneert.

Bestanden van een service opslaan op een geschikte locatie op schijf

Geef een absoluut pad op met SetBasePath wanneer u een IConfigurationBuilder gebruikt voor de map met de bestanden.

Problemen oplossen

Zie Problemen met ASP.NET Core-projecten oplossen en fouten opsporenom problemen met een Windows Service-app op te lossen.

Veelvoorkomende fouten

• Een oude of voorlopige versie van PowerShell wordt gebruikt.
• De geregistreerde service maakt geen gebruik van de gepubliceerde uitvoer van de dotnet-publicatie opdracht. Uitvoer van de dotnet-build opdracht wordt niet ondersteund voor app-implementatie. Gepubliceerde assets vindt u in een van de volgende mappen, afhankelijk van het implementatietype:
  • bin/release/{TARGET FRAMEWORK}/publish (FDD)
  • bin/release/{TARGET FRAMEWORK}/{RUNTIME IDENTIFIER}/publish (SCD)
• De dienst bevindt zich niet in de status RUNNING.
• De paden naar resources die door de app worden gebruikt (bijvoorbeeld certificaten) zijn onjuist. Het basispad van een Windows-service is c:\Windows\System32.
• De gebruiker heeft geen aanmeldrechten als een service.
• Het wachtwoord van de gebruiker is verlopen of onjuist doorgegeven bij het uitvoeren van de New-Service PowerShell-opdracht.
• De app vereist ASP.NET Core-verificatie, maar is niet geconfigureerd voor beveiligde verbindingen (HTTPS).
• De aanvraag-URL-poort is onjuist of niet juist geconfigureerd in de app.

Gebeurtenislogboeken van systeem en toepassing

Toegang tot de gebeurtenislogboeken van het systeem en de toepassing:

1. Open het menu Start, zoek Logboekvieweren selecteer de Logboekviewer app.
2. Open in Logboekenhet knooppunt Windows-logboeken.
3. Selecteer System om het systeemlogboek te openen. Selecteer Toepassing om het gebeurtenislogboek van de toepassing te openen.
4. Zoek naar fouten die zijn gekoppeld aan de mislukte app.

De app uitvoeren bij een opdrachtprompt

Veel opstartfouten produceren geen nuttige informatie in de gebeurtenislogboeken. U kunt de oorzaak van sommige fouten vinden door de app uit te voeren via een opdrachtprompt op het hostingsysteem. Als u aanvullende details van de app wilt vastleggen, verlaagt u het logboekniveau of voert u de app uit in de Ontwikkelomgeving.

Caches van pakketten wissen

Een werkende app kan onmiddellijk mislukken na het upgraden van de .NET Core SDK op de ontwikkelcomputer of het wijzigen van pakketversies in de app. In sommige gevallen kunnen incoherent pakketten een app breken bij het uitvoeren van belangrijke upgrades. De meeste van deze problemen kunnen worden opgelost door de volgende instructies te volgen:

1. Verwijder de bin en obj-mappen.

2. Wis de pakketcaches door dotnet nuget locals all --clear vanuit een opdrachtprompt uit te voeren.

   Het wissen van pakketcaches kan ook worden uitgevoerd met het hulpprogramma nuget.exe en het uitvoeren van de opdracht nuget locals all -clear. nuget.exe is geen gebundelde installatie met het Windows-bureaubladbesturingssysteem en moet afzonderlijk worden verkregen van de NuGet-website.

3. Herstel het project en bouw het opnieuw.

4. Verwijder alle bestanden in de implementatiemap op de server voordat u de app opnieuw implementeert.

Trage of niet-reagerende app

Een crashdump is een momentopname van het geheugen van het systeem en kan helpen bij het bepalen van de oorzaak van een app-crash, opstartfout of trage app.

App loopt vast of ondervindt een uitzondering

Een dump verkrijgen en analyseren van Wer (Windows Error Reporting):

1. Maak een map voor het opslaan van crashdumpbestanden op c:\dumps.

2. Voer het EnableDumps PowerShell-script uit met de naam van het uitvoerbare toepassingsbestand:

   .\EnableDumps {APPLICATION EXE} c:\dumps
   

3. Voer de app uit onder de omstandigheden die ervoor zorgen dat de crash optreedt.

4. Nadat de crash is opgetreden, voert u het DisableDumps PowerShell-script uit:

   .\DisableDumps {APPLICATION EXE}
   

Nadat een app vastloopt en het verzamelen van dumps is voltooid, mag de app normaal worden beëindigd. Met het PowerShell-script wordt WER geconfigureerd voor het verzamelen van maximaal vijf dumps per app.

Waarschuwing

Crashdumps kunnen een grote hoeveelheid schijfruimte in beslag nemen (tot een aantal gigabytes per stuk).

App reageert niet, mislukt tijdens het opstarten of wordt normaal uitgevoerd

Wanneer een app niet meer reageert, maar niet crasht, mislukt tijdens het opstarten of normaal wordt uitgevoerd, raadpleegt u User-Mode dumpbestanden: het kiezen van het beste hulpprogramma om een geschikt hulpprogramma te selecteren om de dump te produceren.

De dump analyseren

Een dump kan op verschillende manieren worden geanalyseerd. Zie Een User-Mode dumpbestand analyserenvoor meer informatie.

Aanvullende informatiebronnen

• voorbeeldcode bekijken of downloaden (hoe te downloaden)
• Kestrel eindpuntconfiguratie (inclusief HTTPS-configuratie en SNI-ondersteuning)
• .NET Generic Host in ASP.NET Core
• Problemen met ASP.NET Core-projecten oplossen en fouten opsporen