Hosten von ASP.NET Core in einem Windows-Dienst

Eine ASP.NET Core-App kann unter Windows als Windows-Dienst ohne die Verwendung von IIS gehostet werden. Wenn die App als Windows-Dienst gehostet und der Server neu gestartet wird, startet diese automatisch.

Voraussetzungen

• ASP.NET Core SDK 7.0 oder höher
• PowerShell 6.2 oder höher

Workerdienstvorlage

Die ASP.NET Core-Workerdienstvorlage dient als Ausgangspunkt für das Programmieren von zeitintensiven Dienstanwendungen. So können Sie diese Vorlage als Grundlage für eine Windows-Dienstanwendung verwenden:

1. Erstellen Sie eine Workerdienstanwendung über die .NET Core-Vorlage.
2. Installieren Sie das NuGet-Paket Microsoft.Extensions.Hosting.WindowsServices.
3. Befolgen Sie die Anweisungen im Abschnitt App-Konfiguration, um die Workerdienstanwendung so zu aktualisieren, dass sie als Windows-Dienst ausgeführt werden kann.

Visual Studio

1. Erstellen Sie ein neues Projekt.
2. Wählen Sie Workerdienst aus. Klicken Sie auf Weiter.
3. Geben Sie im Feld Projektname einen Projektnamen ein, oder übernehmen Sie den Standardnamen. Klicken Sie auf Erstellen.
4. Wählen Sie im Dialogfeld Neuen Workerdienst erstellenErstellen aus.

Visual Studio für Mac

1. Erstellen Sie ein neues Projekt.
2. Wählen Sie in der Randleiste unter .NET Core den Eintrag App aus.
3. Wählen Sie unter ASP.NET Core den Eintrag Worker aus. Wählen Sie Weiter aus.
4. Wählen Sie .NET Core 3.0 oder höher als Zielframework aus. Wählen Sie Weiter aus.
5. Geben Sie im Feld Projektname einen Namen an. Klicken Sie auf Erstellen.

.NET Core-CLI

Rufen Sie die Vorlage „Workerdienst“ (worker) über eine Befehlsshell mit dem Befehl dotnet new auf. Im folgenden Beispiel wird eine Workerdienstanwendung namens ContosoWorker erstellt. Der Ordner für die App ContosoWorker wird automatisch erstellt, wenn der Befehl ausgeführt wird.

dotnet new worker -o ContosoWorker

App-Konfiguration

Aktualisieren Sie „Program.cs“ so, dass AddWindowsService aufgerufen wird. Wenn die App als Windows-Dienst ausgeführt wird, bewirkt AddWindowsService Folgendes:

• Sie legt die Lebensdauer des Hosts auf WindowsServiceLifetime fest.
• AppContext.BaseDirectory wird als Inhaltsstammverzeichnis festgelegt. Weitere Informationen finden Sie im Abschnitt Aktuelles Verzeichnis und Inhaltsstammverzeichnis.
• Ermöglicht die Protokollierung zum Ereignisprotokoll:
  • Der Anwendungsname wird als Standardname für die Quelle verwendet.
  • Für eine App basierend auf einer ASP.NET Core-Vorlage, die CreateDefaultBuilder zur Erstellung des Hosts aufruft, lautet die Standardprotokollebene Warnung oder höher.
  • Überschreiben Sie die Standardprotokollebene mit dem Logging:EventLog:LogLevel:Default-Schlüssel in appsettings.json/appsettings.{Environment}.json oder einem anderen Konfigurationsanbieter.
  • Nur Administratoren können neue Ereignisquellen erstellen. Wenn keine Ereignisquellen mithilfe des Anwendungsnamens erstellt werden können, wird in der Anwendungsquelle eine Warnung protokolliert, und die Ereignisprotokolle werden deaktiviert.

Betrachten wir einmal die folgende 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.");
    }
}

Die folgende Program.cs ruft AddHostedService zum Registrieren von ServiceA auf:

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

In diesem Thema werden die folgenden Beispiel-Apps behandelt:

• Beispiel für einen Hintergrundworkerdienst: Dabei handelt es sich um ein Beispiel einer nicht webbasierten App, die auf der Workerdienstvorlage basiert und gehostete Dienste für Hintergrundaufgaben verwendet.
• Beispiel für einen Web-App-Dienst: Dabei handelt es sich um ein Razor Pages-Web-App-Beispiel, das als Windows-Dienst mit gehosteten Diensten für Hintergrundaufgaben ausgeführt wird.

Eine MVC-Anleitung finden Sie in den Artikeln Übersicht über ASP.NET Core MVC und Migrieren von ASP.NET Core 2.2 zu 3.0.

Bereitstellungstyp

Weitere Informationen und Tipps zu Bereitstellungsszenarien finden Sie unter .NET Core-Anwendungsbereitstellung.

SDK

Geben Sie für einen Web-App-basierten Dienst, der die Razor Pages- oder MVC-Frameworks verwendet, das Web-SDK in der Projektdatei an:

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

Geben Sie das Worker-SDK in der Projektdatei an, wenn der Dienst nur Hintergrundaufgaben ausführt (z. B. gehostete Dienste):

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

Frameworkabhängige Bereitstellung (Framework-dependent deployment, FDD)

Eine Framework-abhängige Bereitstellung (Framework-Dependent Deployment, FDD) benötigt eine gemeinsame systemweite Version von .NET Core auf dem Zielsystem. Wenn das FDD-Szenario gemäß der Anleitung in diesem Artikel übernommen wird, erzeugt das SDK eine ausführbare Datei ( .exe). Diese wird als frameworkabhängige ausführbare Datei bezeichnet.

Bei Verwendung des Web-SDK ist eine web.config-Datei, die normalerweise erstellt wird, wenn Sie eine ASP.NET Core-App veröffentlichen, für eine Windows Services-App nicht erforderlich. Um die Erstellung der web.config-Datei zu deaktivieren, fügen Sie die auf true festgelegte <IsTransformWebConfigDisabled>-Eigenschaft hinzu.

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

Eigenständige Bereitstellung

Eigenständige Bereitstellungen (Self-Contained Deployment, SCD) benötigen kein gemeinsames Framework auf dem Hostsystem. Die Runtime und die App-Abhängigkeiten werden mit der App bereitgestellt.

Ein Runtimebezeichner (Runtime Identifier, RID) für Windows ist im <PropertyGroup>-Objekt enthalten, das wiederum das Zielframework enthält:

<RuntimeIdentifier>win7-x64</RuntimeIdentifier>

So führen Sie die Veröffentlichung für mehrere RIDs aus:

• Geben Sie die RIDs in einer durch Semikolons getrennten Liste an.
• Verwenden Sie den Eigenschaftenname <RuntimeIdentifiers> (Plural).

Weitere Informationen finden Sie im .NET Core RID-Katalog.

Benutzerkonten für Dienste

Wenn Sie ein Benutzerkonto für einen Dienst erstellen möchten, verwenden Sie das Cmdlet New-LocalUser in einer PowerShell 6-Befehlsshell.

Unter Windows 10 mit dem Update von Oktober 2018 (Version 1809/Build 10.0.17763) oder höher:

New-LocalUser -Name {SERVICE NAME}

Unter Windows mit einer früheren Betriebssystemversion als Windows 10 mit dem Update von Oktober 2018 (Version 1809/Build 10.0.17763):

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

Geben Sie bei Aufforderung ein sicheres Kennwort ein.

Solange der Parameter -AccountExpires dem Cmdlet New-LocalUser nicht mit einem Ablaufdatum DateTime angegeben wird, läuft das Konto nicht ab.

Weitere Informationen finden Sie unter Microsoft.PowerShell.LocalAccounts und Dienstbenutzerkonten.

Eine alternative Methode zum Verwalten von Benutzern bei Verwendung von Active Directory ist die Verwendung von verwalteten Dienstkonten. Weitere Informationen finden Sie unter Gruppenverwaltete Dienstkonten: Übersicht.

Rechte zum Anmelden als Dienst

Gehen Sie wie folgt vor, um Rechte zum Anmelden als Dienst für das Benutzerkonto eines Diensts einzurichten:

1. Öffnen Sie den Editor für lokale Sicherheitsrichtlinien, indem Sie die Datei secpol.msc ausführen.
2. Erweitern Sie den Knoten Lokale Richtlinien, und klicken Sie auf Zuweisen von Benutzerrechten.
3. Öffnen Sie die Richtlinie Anmelden als Dienst.
4. Wählen Sie Benutzer oder Gruppe hinzufügen aus.
5. Geben Sie den Objektnamen (das Benutzerkonto) an. Dafür gibt es zwei Möglichkeiten:
   1. Geben Sie die Bezeichnung des Benutzerkontos ({DOMAIN OR COMPUTER NAME\USER}) in das Feld für den Objektnamen ein, und klicken Sie auf OK, um den Benutzer der Richtlinie hinzuzufügen.
   2. Wählen Sie Erweitert aus. Klicken Sie auf Find Now (Suche starten). Wählen Sie das betreffende Benutzerkonto aus der Liste aus. Klicken Sie auf OK. Klicken Sie erneut auf OK, um den Benutzer zur Richtlinie hinzuzufügen.
6. Klicken Sie auf OK oder auf Anwenden, um die Änderungen zu übernehmen.

Erstellen und Verwalten des Windows-Diensts

Erstellen eines Diensts

Verwenden Sie PowerShell-Befehle, um einen Dienst zu registrieren. Führen Sie über eine administrative PowerShell 6-Befehlsshell die folgenden Befehle aus:

$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}: Pfad der ausführbaren Datei der App auf dem Host (z. B. d:\myservice). Fügen Sie den Namen der ausführbare Datei der App nicht in den Pfad ein. Außerdem benötigen Sie keinen nachstehenden Schrägstrich.
• {DOMAIN OR COMPUTER NAME\USER}: entspricht dem Benutzerkonto für den Dienst (z. B. Contoso\ServiceUser).
• {SERVICE NAME}: entspricht dem Dienstnamen (z. B. MyService).
• {EXE FILE PATH}: Der vollständige Pfad der ausführbaren Datei der App (z. B d:\myservice\myservice.exe). Fügen Sie den Namen der ausführbaren Datei einschließlich ihrer Erweiterung hinzu.
• {EXE FOLDER PATH}: Der vollständige Ordnerpfad der ausführbaren Datei der App (z. B. d:\myservice).
• {DESCRIPTION}: ist eine Beschreibung des Diensts (z. B. My sample service).
• {DISPLAY NAME}: entspricht dem Anzeigenamen des Diensts (z. B. My Service).

Starten eines Diensts

Sie können Dienste mithilfe des folgenden PowerShell 6-Befehls starten:

Start-Service -Name {SERVICE NAME}

Das Starten des Diensts dauert ein paar Sekunden.

Ermitteln des Status eines Diensts

Sie können den Status von Diensten mithilfe des folgenden PowerShell 6-Befehls überprüfen:

Get-Service -Name {SERVICE NAME}

Der Status wird als einer der folgenden Werte gemeldet:

• Starting
• Running
• Stopping
• Stopped

Beenden eines Diensts

Sie können Dienste mithilfe des folgenden PowerShell 6-Befehls beenden:

Stop-Service -Name {SERVICE NAME}

Entfernen eines Diensts

Nach einer kurzen Verzögerung durch das Beenden des Diensts können Sie diesen mithilfe des folgenden PowerShell 6-Befehls entfernen:

Remove-Service -Name {SERVICE NAME}

Proxyserver und Lastenausgleichsszenarien

Dienste, die mit Anforderungen aus dem Internet oder einem Unternehmensnetzwerk interagieren und hinter einem Proxy oder Lastenausgleich ausgeführt werden, erfordern möglicherweise zusätzliche Konfigurationen. Weitere Informationen finden Sie unter Konfigurieren von ASP.NET Core für die Arbeit mit Proxyservern und Lastenausgleichen.

Konfigurieren von Endpunkten

Standardmäßig ist ASP.NET Core an http://localhost:5000 gebunden. Konfigurieren Sie URL und Port, indem Sie die ASPNETCORE_URLS-Umgebungsvariable festlegen.

Weitere Informationen zu den Konfigurationsansätzen für URLs und Ports finden Sie im relevanten Serverartikel:

• Konfigurieren von Endpunkten für den Kestrel-Webserver in ASP.NET Core
• Implementierung des Http.sys-Webservers in ASP.NET Core

Die vorangehende Anleitung behandelt die Unterstützung für HTTPS-Endpunkte. Konfigurieren Sie z. B. die APP für HTTPS, wenn die Authentifizierung mit einem Windows-Dienst verwendet wird.

Hinweis

Die Verwendung des ASP.NET Core-HTTPS-Entwicklerzertifikats zum Schützen eines Dienstendpunkts wird nicht unterstützt.

Aktuelles Verzeichnis und Inhaltsstammverzeichnis

Das aktuelle Arbeitsverzeichnis, das durch Aufrufen von GetCurrentDirectory für einen Windows-Dienst zurückgegeben wird, ist der Ordner C:\WINDOWS\system32. Der Ordner system32 ist kein geeigneter Speicherort für die Dateien eines Diensts (z.B. Einstellungsdateien). Verwenden Sie einen der folgenden Ansätze, um die Objekt- und Einstellungsdateien eines Dienstes beizubehalten und darauf zuzugreifen.

Verwenden von ContentRootPath oder ContentRootFileProvider

Verwenden Sie IHostEnvironment.ContentRootPath oder ContentRootFileProvider, um die Ressourcen einer App zu finden.

Wenn die App als Dienst ausgeführt wird, AppContext.BaseDirectory durch UseWindowsService für ContentRootPath festgelegt.

Die Dateien mit den Standardeinstellungen (appsettings.json und appsettings.{Environment}.json) der App werden über das Inhaltsstammverzeichnis der App geladen, indem CreateDefaultBuilder während der Hosterstellung aufgerufen wird.

Für andere Einstellungsdateien, die in ConfigureAppConfiguration durch Entwicklercode geladen werden, muss SetBasePath nicht aufgerufen werden. Im folgenden Beispiel ist die Datei custom_settings.json im Inhaltsstammverzeichnis der App enthalten und wird geladen, ohne das ein Basispfad explizit festgelegt wird:

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

Versuchen Sie nicht, GetCurrentDirectory zum Abrufen eines Ressourcenpfads zu verwenden, da eine Windows-Dienstanwendung den Ordner C:\WINDOWS\system32 als aktuelles Verzeichnis zurückgibt.

Speichern der Dateien eines Diensts an einem geeigneten Ort auf dem Datenträger

Geben Sie mit SetBasePath beim Verwenden von IConfigurationBuilder einen absoluten Pfad zu dem Ordner an, der die Dateien enthält.

Problembehandlung

Informationen zur Problembehandlung für Windows Service-App finden Sie unter Problembehandlung und Debuggen von ASP.NET Core-Projekten.

Häufige Fehler

• Eine alte oder eine Vorabversion von PowerShell wird verwendet.
• Der registrierte Dienst verwendet nicht die veröffentlichte Ausgabe des Befehls dotnet publish der Anwendung. Die Ausgabe des Befehls dotnet build wird nicht für die Anwendungsbereitstellung unterstützt. Veröffentlichte Ressourcen sind je nach Bereitstellungstyp in einem der folgenden Ordner vorzufinden:
  • bin/Release/{ZIELFRAMEWORK}/publish (FDD)
  • bin/Release/{ZIELFRAMEWORK}/{RUNTIME-ID}/publish (SCD)
• Der Dienst weist nicht den Status „WIRD AUSGEFÜHRT“ auf.
• Die App enthält falsche Pfade zu Ressourcen (z. B. Zertifikate). Der Basispfad eines Windows-Diensts lautet c:\Windows\System32.
• Der Benutzer verfügt nicht über die Berechtigung Als Dienst anmelden.
• Das Kennwort des Benutzers ist abgelaufen oder wird nicht ordnungsgemäß übermittelt, wenn der PowerShell-Befehl New-Service ausgeführt wird.
• Die App erfordert ASP.NET Core-Authentifizierung, aber sie wurde nicht für sichere (HTTPS-)Verbindungen konfiguriert.
• Der Port für die Anforderungs-URL in der App ist fehlerhaft oder nicht ordnungsgemäß konfiguriert.

System- und Anwendungsereignisprotokolle

So greifen Sie auf die System- und Anwendungsereignisprotokolle zu:

1. Öffnen Sie das Startmenü, suchen Sie nach der Ereignisanzeige, und wählen Sie dann die App Ereignisanzeige aus.
2. Öffnen Sie unter Ereignisanzeige den Knoten Windows-Protokolle.
3. Klicken Sie auf System, um das Systemereignisprotokoll zu öffnen. Wählen Sie Anwendung aus, um das Anwendungsereignisprotokoll zu öffnen.
4. Suchen Sie nach Fehlern, die mit der fehlerhaften App im Zusammenhang stehen.

Ausführen der App in einer Eingabeaufforderung

Viele Startfehler erzeugen keine nützlichen Informationen in den Ereignisprotokollen. Sie können die Ursache für einige Fehler ermitteln, indem Sie die App in einer Eingabeaufforderung auf dem Hostsystem ausführen. Senken Sie den Protokolliergrad, oder führen Sie die App in der Entwicklungsumgebung aus, um zusätzliche Informationen von der App zu protokollieren.

Bereinigen der Paketcaches

Eine funktionsfähige App kann direkt nach der Durchführung eines Upgrades für das .NET Core SDK auf dem Entwicklungscomputer oder einer Änderung der Paketversionen in der App fehlschlagen. In einigen Fällen können inkohärente Pakete eine App beschädigen, wenn größere Upgrades durchgeführt werden. Die meisten dieser Probleme können durch Befolgung der folgenden Anweisungen behoben werden:

1. Löschen Sie die Ordner bin und obj.

2. Bereinigen Sie die Paketcaches, indem Sie dotnet nuget locals all --clear über eine Befehlsshell ausführen.

   Sie können die Paketcaches auch mit dem Tool nuget.exe und dem Befehl nuget locals all -clear bereinigen. nuget.exe ist wird unter dem Windows Desktop-Betriebssystem nicht gebündelt installiert und muss separat von der NuGet-Website abgerufen werden.

3. Stellen Sie das Projekt wieder her und erstellen Sie es neu.

4. Löschen Sie alle Dateien im Bereitstellungsordner auf dem Server, bevor Sie die App noch mal bereitstellen.

Langsame oder nicht reagierende App

Ein Absturzabbild ist eine Momentaufnahme des Systemarbeitsspeichers, die Ihnen dabei behilflich sein kann, die Ursache eines App-Absturzes, eines Startfehlers oder einer langsamen App zu ermitteln.

App stürzt ab, oder es tritt eine Ausnahme auf

Abrufen und Analysieren eines Speicherabbilds aus der Windows-Fehlerberichterstattung (WER):

1. Erstellen Sie einen Ordner zum Speichern von Absturzabbilddateien unter c:\dumps.

2. Führen Sie das PowerShell-Skript EnableDumps mit dem Namen des ausführbaren Anwendung aus:

   .\EnableDumps {APPLICATION EXE} c:\dumps
   

3. Führen Sie die App unter den Bedingungen aus, die dazu führen, dass der Absturz auftritt.

4. Nachdem der Absturz stattgefunden hat, führen Sie das PowerShell-Skript „DisableDumps“ aus:

   .\DisableDumps {APPLICATION EXE}
   

Nachdem eine Anwendung abgestürzt ist und die Absturzabbildsammlung abgeschlossen ist, kann die App ordnungsgemäß beendet werden. Das PowerShell-Skript konfiguriert WER für die Erfassung von bis zu fünf Absturzabbildern pro App.

Warnung

Absturzabbilder können eine große Menge Speicherplatz in Anspruch nehmen (jeweils bis zu mehreren GB).

Die App reagiert nicht, es tritt ein Fehler während des Starts auf, oder sie wird normal ausgeführt.

Wenn sich eine App aufgehängt hat (nicht mehr reagiert, aber nicht abstürzt), ein Fehler während des Starts auftritt bzw. die App normal ausgeführt wird, finden Sie weitere Informationen unter Benutzermodus-Absturzabbilddateien: Auswählen des besten Tools, um ein geeignetes Tool zum Generieren des Speicherabbilds auszuwählen.

Analysieren des Speicherabbilds

Ein Speicherabbild kann mithilfe mehrerer Ansätze analysiert werden. Weitere Informationen finden Sie unter Analysieren einer Benutzermodus-Speicherabbilddatei.

Zusätzliche Ressourcen

• Anzeigen oder Herunterladen von Beispielcode (Vorgehensweise zum Herunterladen)
• Kestrel-Endpunktkonfiguration (einschließlich HTTPS-Konfiguration und Unterstützung für SNI)
• Generischer .NET-Host in ASP.NET Core
• Problembehandlung und Debuggen von ASP.NET Core-Projekten