Värda ASP.NET Core i en Windows-tjänst

En ASP.NET Core-app kan hanteras i Windows som en Windows Service- utan att använda IIS. När appen körs som en Windows-tjänst startar den automatiskt efter att servern har startats om.

Förutsättningar

• ASP.NET Core SDK 7.0 eller senare
• PowerShell 6.2 eller senare

Arbetstjänstmall

Mallen ASP.NET Core Worker Service är en startpunkt för att skriva tidskrävande tjänstappar. Så här använder du mallen som grund för en Windows Service-app:

1. Skapa en Worker Service-app från .NET Core-mallen.
2. Installera NuGet-paketet Microsoft.Extensions.Hosting.WindowsServices.
3. Följ anvisningarna i avsnittet Appkonfiguration för att uppdatera Worker Service-appen så att den kan köras som en Windows-tjänst.

Visual Studio

1. Skapa ett nytt projekt.
2. Välj Worker Service. Välj Nästa.
3. Ange ett projektnamn i fältet Projektnamn eller godkänn standardprojektets namn. Välj Skapa.
4. I dialogrutan Skapa en ny Arbetstjänst väljer du Skapa.

Visual Studio för Mac

1. Skapa ett nytt projekt.
2. Välj App under .NET Core i sidofältet.
3. Välj Worker under ASP.NET Core. Välj Nästa.
4. Välj .NET Core 3.0 eller senare för Target Framework-. Välj Nästa.
5. Ange ett namn i fältet Projektnamn. Välj Skapa.

.NET CLI

Använd mallen Worker Service (worker) med kommandot dotnet new från ett kommandogränssnitt. I följande exempel skapas en Worker Service-app med namnet ContosoWorker. En mapp för ContosoWorker-appen skapas automatiskt när kommandot körs.

dotnet new worker -o ContosoWorker

Appkonfiguration

Uppdatera Program.cs för att anropa AddWindowsService. När appen körs som en Windows-tjänst AddWindowsService:

• Anger värdlivslängden till WindowsServiceLifetime.
• Ställer in innehållsroten till AppContext.BaseDirectory. Mer information finns i avsnittet Aktuell katalog och innehållsrot.
• Aktiverar loggning till händelseloggen:
  • Programnamnet används som standardkällnamn.
  • Standardloggnivån är Varning eller högre för en app som baseras på en ASP.NET Core-mall som anropar CreateDefaultBuilder för att skapa värdservern.
  • Åsidosätt standardloggnivån med Logging:EventLog:LogLevel:Default-nyckeln i appsettings.json/appsettings.{Environment}.json eller annan konfigurationsprovider.
  • Endast administratörer kan skapa nya händelsekällor. När en händelsekälla inte kan skapas med programnamnet, loggas en varning till Program och käll- och händelseloggar inaktiveras.

Överväg följande ServiceA-klass:

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

Följande Program.cs anropar AddHostedService för att registrera 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();

Följande exempelappar medföljer det här avsnittet:

• Exempel på Background Worker Service: Ett exempel på en icke-webbapp som baseras på mallen Worker Service som använder värdbaserade tjänster för bakgrundsaktiviteter.
• Exempel på Web App Service: Ett Razor Pages-webbappexempel som körs som en Windows-tjänst med värdbaserade tjänster för bakgrundsaktiviteter.

MVC-vägledning finns i artiklarna i Översikt över ASP.NET Core MVC och Migrera från ASP.NET Core 2.2 till 3.0.

Distributionstyp

Information och råd om distributionsscenarier finns i .NET Core-programdistribution.

SDK

För en webbappbaserad tjänst som använder ramverken Razor Pages eller MVC anger du webb-SDK:t i projektfilen:

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

Om tjänsten bara kör bakgrundsaktiviteter (till exempel värdbaserade tjänster) anger du Worker SDK i projektfilen:

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

Ramverksberoende distribution (FDD)

Ramverksberoende distribution (FDD) förlitar sig på förekomsten av en delad systemomfattande version av .NET Core i målsystemet. När FDD-scenariot antas enligt vägledningen i den här artikeln skapar SDK:n en körbar (.exe), som kallas en ramverksberoende körbar.

Om du använder Web SDKär en web.config-fil, som normalt skapas när du publicerar en ASP.NET Core-app, onödig för en Windows Services-app. Om du vill inaktivera skapandet av web.config-filen lägger du till egenskapen <IsTransformWebConfigDisabled> i true.

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

Fristående distribution (SCD)

Fristående distribution (SCD) förlitar sig inte på förekomsten av ett delat ramverk i värdsystemet. Körtiden och appens beroenden distribueras med appen.

En Windows Runtime Identifier (RID) ingår i <PropertyGroup> som innehåller målramverket:

<RuntimeIdentifier>win-x64</RuntimeIdentifier>

Så här publicerar du för flera RID:ar:

• Ange RID:erna i en semikolonavgränsad lista.
• Använd egenskapsnamnet <RuntimeIdentifiers> (plural).

Mer information finns i .NET Core RID Catalog.

Tjänstanvändarkonto

Om du vill skapa ett användarkonto för en tjänst använder du cmdleten New-LocalUser från ett administrativt PowerShell 6-kommandogränssnitt.

I Windows 10 Oktober 2018 Update (version 1809/build 10.0.17763) eller senare:

New-LocalUser -Name {SERVICE NAME}

I Windows OS tidigare än Windows 10 Oktober 2018 Update (version 1809/build 10.0.17763):

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

Ange ett starkt lösenord när du uppmanas att göra det.

Om inte parametern -AccountExpires anges till cmdleten New-LocalUser med en förfallotid DateTimeupphör kontot inte att gälla.

Mer information finns i Microsoft.PowerShell.LocalAccounts och tjänstanvändarkonton.

En alternativ metod för att hantera användare när du använder Active Directory är att använda hanterade tjänstkonton. För mer information, se översikt över grupphanterade tjänstkonton.

Rättigheter för inloggning som tjänst

Så här upprättar du Logga in som en tjänst rättigheter för ett tjänstanvändarkonto:

1. Öppna redigeraren för lokal säkerhetspolicy genom att köra secpol.msc.
2. Expandera noden lokala principer och välj Tilldelning av användarrättigheter.
3. Öppna Logga in som en tjänst princip.
4. Välj Lägg till användare eller grupp.
5. Ange objektnamnet (användarkontot) med någon av följande metoder:
   1. Skriv användarkontot ({DOMAIN OR COMPUTER NAME\USER}) i namnfältet för objekt och välj OK för att lägga till användaren i policyn.
   2. Välj Avancerat. Välj Hitta nu. Välj användarkontot i listan. Välj OK. Välj OK igen för att lägga till användaren i policyn.
6. Välj OK eller Använd för att godkänna ändringarna.

Skapa och hantera Windows-tjänsten

Skapa en tjänst

Använd PowerShell-kommandon för att registrera en tjänst. Kör följande kommandon från ett administrativt PowerShell 6-kommandogränssnitt:

$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}: Sökvägen till appens exekverbara fil på värden (till exempel d:\myservice). Inkludera inte appens körbara filnamn i sökvägen. Ett avslutande snedstreck krävs inte.
• {DOMAIN OR COMPUTER NAME\USER}: Tjänstanvändarkonto (till exempel Contoso\ServiceUser).
• {SERVICE NAME}: Tjänstnamn (till exempel MyService).
• {EXE FILE PATH}: Applikationens fullständiga körbara sökväg (till exempel d:\myservice\myservice.exe). Inkludera filnamnet för den körbara filen med filändelsen.
• {EXE FOLDER PATH}: Appens fullständiga körbara mappsökväg (till exempel d:\myservice).
• {DESCRIPTION}: Tjänstbeskrivning (till exempel My sample service).
• {DISPLAY NAME}: Tjänstvisningsnamn (till exempel My Service).

Starta en tjänst

Starta en tjänst med följande PowerShell 6-kommando:

Start-Service -Name {SERVICE NAME}

Kommandot tar några sekunder att starta tjänsten.

Fastställa status för en tjänst

Om du vill kontrollera status för en tjänst använder du följande PowerShell 6-kommando:

Get-Service -Name {SERVICE NAME}

Statusen rapporteras som ett av följande värden:

• Starting
• Running
• Stopping
• Stopped

Stoppa en tjänst

Stoppa en tjänst med följande PowerShell 6-kommando:

Stop-Service -Name {SERVICE NAME}

Ta bort en tjänst

Efter en kort fördröjning för att stoppa en tjänst tar du bort en tjänst med följande PowerShell 6-kommando:

Remove-Service -Name {SERVICE NAME}

Scenarier för proxyserver och lastbalanserare

Tjänster som interagerar med begäranden från Internet eller ett företagsnätverk och som finns bakom en proxy eller lastbalanserare kan kräva ytterligare konfiguration. Mer information finns i Konfigurera ASP.NET Core att fungera med proxyservrar och lastbalanserare.

Konfigurera slutpunkter

Som standard binder ASP.NET Core till http://localhost:5000. Konfigurera URL:en och porten genom att ange miljövariabeln ASPNETCORE_URLS.

Ytterligare metoder för URL- och portkonfiguration finns i relevant serverartikel:

• Konfigurera slutpunkter för webbservern ASP.NET Core Kestrel
• HTTP.sys webbserverimplementering i ASP.NET Core

Föregående vägledning omfattar stöd för HTTPS-slutpunkter. Konfigurera till exempel appen för HTTPS när autentisering används med en Windows-tjänst.

Not

Användning av ASP.NET Core HTTPS-utvecklingscertifikat för att skydda en tjänstslutpunkt stöds inte.

Aktuell katalog och innehållsrot

Den aktuella arbetskatalogen som returneras genom att anropa GetCurrentDirectory för en Windows-tjänst är mappen C:\WINDOWS\system32. Mappen system32 är inte en lämplig plats för att lagra en tjänsts filer (till exempel inställningsfiler). Använd någon av följande metoder för att underhålla och komma åt en tjänsts tillgångar och inställningsfiler.

Använda ContentRootPath eller ContentRootFileProvider

Använd IHostEnvironment.ContentRootPath eller ContentRootFileProvider för att hitta en apps resurser.

När appen körs som en tjänst anger UseWindowsServiceContentRootPath till AppContext.BaseDirectory.

Appens standardinställningsfiler, appsettings.json och appsettings.{Environment}.json, läses in från appens innehållsrot genom att anropa CreateDefaultBuilder under värdkonstruktionen.

För andra inställningar som läses in av utvecklarkod i ConfigureAppConfigurationbehöver du inte anropa SetBasePath. I följande exempel finns den custom_settings.json filen i appens innehållsrot och läses in utan att uttryckligen ange en bassökväg:

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

Försök inte använda GetCurrentDirectory för att hämta en resurssökväg eftersom en Windows Service-app returnerar mappen C:\WINDOWS\system32 som dess aktuella katalog.

Lagra en tjänsts filer på en lämplig plats på disken

Ange en absolut sökväg med SetBasePath när du använder en IConfigurationBuilder till mappen som innehåller filerna.

Felsöka

Information om hur du felsöker en Windows Service-app finns i Felsöka och debugga ASP.NET Core-projekt.

Vanliga fel

• En gammal eller förhandsversion av PowerShell används.
• Den registrerade tjänsten använder inte appens publicerade utdata från kommandot dotnet publish. Utdata från kommandot dotnet build stöds inte för appdistribution. Publicerade tillgångar finns i någon av följande mappar beroende på distributionstyp:
  • bin/Release/{TARGET FRAMEWORK}/publish (FDD)
  • bin/Release/{TARGET FRAMEWORK}/{RUNTIME IDENTIFIER}/publicera (SCD)
• Tjänsten är inte i körläge.
• Sökvägarna till resurser som appen använder (till exempel certifikat) är felaktiga. Bassökvägen för en Windows-tjänst är c:\Windows\System32.
• Användaren har inte logga in som tjänst rättigheter.
• Användarens lösenord har upphört att gälla eller skickas felaktigt när du kör kommandot New-Service PowerShell.
• Appen kräver ASP.NET Core-autentisering men är inte konfigurerad för säkra anslutningar (HTTPS).
• Url-porten för begäran är felaktig eller inte korrekt konfigurerad i appen.

System- och programhändelseloggar

Få åtkomst till system- och programhändelseloggarna:

1. Öppna Start-menyn, sök efter Händelseloggoch välj appen Händelselogg.
2. I Loggbokenöppnar du noden Windows-loggar.
3. Välj System för att öppna systemhändelseloggen. Välj program för att öppna programhändelseloggen.
4. Sök efter fel som är associerade med den misslyckade appen.

Kör appen i en kommandotolk

Många startfel ger inte användbar information i händelseloggarna. Du kan hitta orsaken till vissa fel genom att köra appen i en kommandotolk på värdsystemet. Om du vill logga ytterligare information från appen sänker du loggnivå eller kör appen i Utvecklingsmiljö.

Rensa paketcache

En fungerande app kan misslyckas omedelbart efter att ha uppgraderat .NET Core SDK på utvecklingsdatorn eller ändrat paketversioner i appen. I vissa fall kan inkonsekventa paket förstöra en app vid större uppgraderingar. De flesta av dessa problem kan åtgärdas genom att följa dessa instruktioner:

1. Ta bort bin och obj mappar.

2. Rensa paketcacheminnena genom att köra dotnet nuget locals all --clear från ett kommandogränssnitt.

   Du kan också rensa paketcacheminnen med verktyget nuget.exe och köra kommandot nuget locals all -clear. nuget.exe är inte en paketerad installation med Windows-skrivbordsoperativsystemet och måste hämtas separat från NuGet-webbplatsen.

3. Återställa och återskapa projektet.

4. Ta bort alla filer i distributionsmappen på servern innan du distribuerar om appen.

Långsam eller icke-svarande applikation

En kraschdump är en ögonblicksbild av systemets minne och kan hjälpa dig att fastställa orsaken till en appkrasch, ett startfel eller en långsam app.

Appen kraschar eller stöter på ett undantag

Hämta och analysera en dump från Windows Error Reporting (WER):

1. Skapa en mapp för att lagra kraschdumpfiler på c:\dumps.

2. Kör EnableDumps PowerShell-skriptet med programmets körbara namn:

   .\EnableDumps {APPLICATION EXE} c:\dumps
   

3. Kör appen under de förhållanden som orsakar kraschen.

4. När kraschen har inträffat kör du DisableDumps PowerShell-skriptet:

   .\DisableDumps {APPLICATION EXE}
   

När en app kraschar och dumpsamlingen har slutförts kan appen avslutas normalt. PowerShell-skriptet konfigurerar WER för att samla in upp till fem dumpar per app.

Varning

Kraschdumpar kan ta upp en stor mängd diskutrymme (upp till flera gigabyte vardera).

Appen svarar inte, misslyckas vid start eller körs normalt

När en app slutar svara men inte kraschar, misslyckas vid start eller körs normalt kan du läsa User-Mode Dump Files: Välja det bästa verktyget för att välja ett lämpligt verktyg för att skapa dumpen.

Analysera datadumpen

En dump kan analyseras med flera metoder. Mer information finns i Analysera en User-Mode dumpfil.

Ytterligare resurser

• Visa eller ladda ned exempelkod (hur du laddar ned)
• Kestrel slutpunktskonfiguration (inkluderar HTTPS-konfiguration och SNI-stöd)
• .NET Generic Host i ASP.NET Core
• Felsöka och avlusa ASP.NET Core-projekt