Host ASP.NET Core w usłudze systemu Windows

Aplikacja ASP.NET Core może być hostowana w systemie Windows jako usługa systemu Windows bez używania usług IIS. Gdy jest hostowana jako usługa systemu Windows, aplikacja jest uruchamiana automatycznie po ponownym uruchomieniu serwera.

Wymagania wstępne

• zestaw ASP.NET Core SDK 7.0 lub nowszy
• Program PowerShell 6.2 lub nowszy

Szablon usługi procesu roboczego

Szablon usługi ASP.NET Core Worker Service stanowi punkt wyjścia do pisania długotrwałych aplikacji usługi. Aby użyć szablonu jako podstawy dla aplikacji usługi systemu Windows:

1. Utwórz aplikację usługi Worker Service na podstawie szablonu platformy .NET Core.
2. Zainstaluj pakiet NuGet Microsoft.Extensions.Hosting.WindowsServices.
3. Postępuj zgodnie ze wskazówkami w sekcji Konfiguracja aplikacji, aby zaktualizować aplikację Usługi procesu roboczego, aby mogła działać jako usługa systemu Windows.

Program Visual Studio

1. Tworzenie nowego projektu.
2. Wybierz pozycję Usługa procesu roboczego. Wybierz pozycję Dalej.
3. Podaj nazwę projektu w polu Nazwa projektu lub zaakceptuj domyślną nazwę projektu. Wybierz pozycję Utwórz.
4. W oknie dialogowym Tworzenie nowej usługi Procesu roboczego wybierz pozycję Utwórz.

Visual Studio dla komputerów Mac

1. Tworzenie nowego projektu.
2. Na pasku bocznym wybierz pozycję Aplikacja w obszarze .NET Core.
3. Wybierz pozycję Proces roboczy w obszarze ASP.NET Core. Wybierz pozycję Dalej.
4. Wybierz platformę .NET Core 3.0 lub nowszą dla platformy docelowej. Wybierz pozycję Dalej.
5. Podaj nazwę w polu Nazwa projektu. Wybierz pozycję Utwórz.

.NET Core CLI

Użyj szablonu Usługi roboczej (worker) z nowym poleceniem dotnet w powłoce poleceń. W poniższym przykładzie aplikacja usługi Worker Service jest tworzona o nazwie ContosoWorker. Folder aplikacji ContosoWorker jest tworzony automatycznie po wykonaniu polecenia.

dotnet new worker -o ContosoWorker

Konfiguracja aplikacji

Zaktualizuj plik Program.cs, aby wywołać metodę AddWindowsService. Gdy aplikacja jest uruchomiona jako usługa systemu Windows, AddWindowsService:

• Ustawia okres istnienia hosta na WindowsServiceLifetimewartość .
• Ustawia katalog główny zawartości na AppContext.BaseDirectory. Aby uzyskać więcej informacji, zobacz sekcję Bieżący katalog i katalog główny zawartości.
• Włącza rejestrowanie w dzienniku zdarzeń:
  • Nazwa aplikacji jest używana jako domyślna nazwa źródła.
  • Domyślny poziom dziennika to Ostrzeżenie lub wyższe dla aplikacji na podstawie szablonu ASP.NET Core, który wywołuje CreateDefaultBuilder metodę kompilowania hosta.
  • Zastąpij domyślny poziom dziennika za pomocą Logging:EventLog:LogLevel:Default klucza w appsettings.json/appsettings.{Environment}.json lub innego dostawcy konfiguracji.
  • Tylko administratorzy mogą tworzyć nowe źródła zdarzeń. Jeśli nie można utworzyć źródła zdarzeń przy użyciu nazwy aplikacji, ostrzeżenie jest rejestrowane w źródle aplikacji , a dzienniki zdarzeń są wyłączone.

Rozważmy następującą ServiceA klasę:

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

Następujące Program.cs wywołania AddHostedService rejestrowania: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();

Następujące przykładowe aplikacje towarzyszą temu tematowi:

• Przykładowa usługa procesu roboczego w tle: przykład aplikacji innej niż internetowa oparty na szablonie usługi procesu roboczego, który używa hostowanych usług do wykonywania zadań w tle.
• Przykład usługi Web App Service: Razor przykład aplikacji internetowej Stron, który działa jako usługa systemu Windows z hostowanymi usługami na potrzeby zadań w tle.

Aby uzyskać wskazówki dotyczące wzorca MVC, zobacz artykuły w sekcji Przegląd ASP.NET Core MVC i Migrowanie z ASP.NET Core 2.2 do 3.0.

Typ wdrożenia

Aby uzyskać informacje i porady dotyczące scenariuszy wdrażania, zobacz Wdrażanie aplikacji platformy .NET Core.

SDK

W przypadku usługi opartej na aplikacji internetowej korzystającej ze Razor struktur Pages lub MVC określ zestaw SDK sieci Web w pliku projektu:

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

Jeśli usługa wykonuje tylko zadania w tle (na przykład hostowane usługi), określ zestaw SDK procesu roboczego w pliku projektu:

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

Wdrażanie zależne od struktury (FDD)

Wdrożenie zależne od struktury (FDD) opiera się na obecności udostępnionej wersji platformy .NET Core w całym systemie w systemie docelowym. Gdy scenariusz FDD zostanie przyjęty zgodnie ze wskazówkami w tym artykule, zestaw SDK tworzy plik wykonywalny (.exe), nazywany plikiem wykonywalnym zależnym od struktury.

W przypadku korzystania z zestawu Web SDK plik web.config, który jest zwykle generowany podczas publikowania aplikacji ASP.NET Core, jest niepotrzebny dla aplikacji usług systemu Windows. Aby wyłączyć tworzenie pliku web.config , dodaj właściwość ustawioną <IsTransformWebConfigDisabled> na true.

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

Wdrażanie samodzielne (SCD)

Wdrożenie samodzielne (SCD) nie polega na obecności struktury udostępnionej w systemie hosta. Środowisko uruchomieniowe i zależności aplikacji są wdrażane z aplikacją.

Identyfikator środowiska uruchomieniowego systemu Windows (RID) znajduje się w pliku <PropertyGroup> zawierającym platformę docelową:

<RuntimeIdentifier>win7-x64</RuntimeIdentifier>

Aby opublikować dla wielu identyfikatorów RID:

• Podaj identyfikatory RID na liście rozdzielanej średnikami.
• Użyj nazwy <właściwości RuntimeIdentifiers> (liczba mnoga).

Aby uzyskać więcej informacji, zobacz Katalog identyfikatorów RID platformy .NET Core.

Konto użytkownika usługi

Aby utworzyć konto użytkownika dla usługi, użyj polecenia cmdlet New-LocalUser z administracyjnej powłoki poleceń programu PowerShell 6.

W Aktualizacja systemu Windows 10 z października 2018 (wersja 1809/kompilacja 10.0.17763) lub nowsza:

New-LocalUser -Name {SERVICE NAME}

W systemie operacyjnym Windows starszym niż Aktualizacja systemu Windows 10 z października 2018 (wersja 1809/kompilacja 10.0.17763):

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

Po wyświetleniu monitu podaj silne hasło .

-AccountExpires Jeśli parametr nie zostanie dostarczony do polecenia cmdlet New-LocalUser z wygaśnięciemDateTime, konto nie wygaśnie.

Aby uzyskać więcej informacji, zobacz Microsoft.PowerShell.LocalAccounts i Konta użytkowników usługi.

Alternatywną metodą zarządzania użytkownikami w przypadku korzystania z usługi Active Directory jest użycie zarządzanych kont usług. Aby uzyskać więcej informacji, zobacz Omówienie kont usług zarządzanych przez grupę.

Logowanie się jako prawa usługi

Aby ustanowić uprawnienia logowania jako usługi dla konta użytkownika usługi:

1. Otwórz edytor lokalnych zasad zabezpieczeń, uruchamiając polecenie secpol.msc.
2. Rozwiń węzeł Zasady lokalne i wybierz pozycję Przypisanie praw użytkownika.
3. Otwórz zasady Logowanie jako usługa.
4. Wybierz pozycję Dodaj użytkownika lub grupę.
5. Podaj nazwę obiektu (konto użytkownika) przy użyciu jednej z następujących metod:
   1. Wpisz konto użytkownika ({DOMAIN OR COMPUTER NAME\USER}) w polu nazwa obiektu i wybierz przycisk OK , aby dodać użytkownika do zasad.
   2. Wybierz opcję Zaawansowane. Wybierz pozycję Znajdź teraz. Wybierz konto użytkownika z listy. Wybierz przycisk OK. Ponownie wybierz przycisk OK , aby dodać użytkownika do zasad.
6. Wybierz przycisk OK lub Zastosuj , aby zaakceptować zmiany.

Tworzenie usługi systemu Windows i zarządzanie nią

Tworzenie usługi

Użyj poleceń programu PowerShell, aby zarejestrować usługę. W administracyjnej powłoce poleceń programu PowerShell 6 wykonaj następujące polecenia:

$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}: ścieżka pliku wykonywalnego aplikacji na hoście (na przykład d:\myservice). Nie dołączaj nazwy pliku wykonywalnego aplikacji do ścieżki. Końcowy ukośnik nie jest wymagany.
• {DOMAIN OR COMPUTER NAME\USER}: Konto użytkownika usługi (na przykład Contoso\ServiceUser).
• {SERVICE NAME}: Nazwa usługi (na przykład MyService).
• {EXE FILE PATH}: pełna ścieżka wykonywalna aplikacji (na przykład d:\myservice\myservice.exe). Dołącz nazwę pliku wykonywalnego z rozszerzeniem .
• {EXE FOLDER PATH}: pełna ścieżka folderu wykonywalnego aplikacji (na przykład d:\myservice).
• {DESCRIPTION}: Opis usługi (na przykład My sample service).
• {DISPLAY NAME}: Nazwa wyświetlana usługi (na przykład My Service).

Uruchamianie usługi

Uruchom usługę za pomocą następującego polecenia programu PowerShell 6:

Start-Service -Name {SERVICE NAME}

Uruchomienie usługi trwa kilka sekund.

Określanie stanu usługi

Aby sprawdzić stan usługi, użyj następującego polecenia programu PowerShell 6:

Get-Service -Name {SERVICE NAME}

Stan jest zgłaszany jako jedna z następujących wartości:

• Starting
• Running
• Stopping
• Stopped

Zatrzymywanie usługi

Zatrzymaj usługę za pomocą następującego polecenia programu PowerShell 6:

Stop-Service -Name {SERVICE NAME}

Usuwanie usługi

Po krótkim opóźnieniu zatrzymania usługi usuń usługę za pomocą następującego polecenia programu PowerShell 6:

Remove-Service -Name {SERVICE NAME}

Scenariusze dotyczące serwera proxy i modułu równoważenia obciążenia

Usługi, które wchodzą w interakcje z żądaniami z Internetu lub sieci firmowej i znajdują się za serwerem proxy lub modułem równoważenia obciążenia, mogą wymagać dodatkowej konfiguracji. Aby uzyskać więcej informacji, zobacz Konfigurowanie platformy ASP.NET Core pod kątem pracy z serwerami proxy i modułami równoważenia obciążenia.

Konfigurowanie punktów końcowych

Domyślnie ASP.NET Core wiąże się z .http://localhost:5000 Skonfiguruj adres URL i port, ustawiając zmienną środowiskową ASPNETCORE_URLS .

Aby uzyskać dodatkowe podejścia do konfiguracji adresów URL i portów, zobacz odpowiedni artykuł serwera:

• Konfigurowanie punktów końcowych dla serwera internetowego ASP.NET Core Kestrel
• Implementacja serwera internetowego HTTP.sys w środowisku ASP.NET Core

Powyższe wskazówki obejmują obsługę punktów końcowych HTTPS. Na przykład skonfiguruj aplikację dla protokołu HTTPS, gdy uwierzytelnianie jest używane z usługą systemu Windows.

Uwaga

Użycie certyfikatu programistycznego ASP.NET Core HTTPS w celu zabezpieczenia punktu końcowego usługi nie jest obsługiwane.

Bieżący katalog i katalog główny zawartości

Bieżący katalog roboczy zwracany przez wywołanie GetCurrentDirectory usługi systemu Windows to folder C:\WINDOWS\system32 . Folder system32 nie jest odpowiednią lokalizacją do przechowywania plików usługi (na przykład plików ustawień). Użyj jednej z poniższych metod, aby zachować zasoby i pliki ustawień usługi i uzyskiwać do nich dostęp.

Używanie elementu ContentRootPath lub ContentRootFileProvider

Użyj elementu IHostEnvironment.ContentRootPath lub ContentRootFileProvider znajdź zasoby aplikacji.

Gdy aplikacja działa jako usługa, UseWindowsService ustawia wartość ContentRootPathAppContext.BaseDirectory.

Domyślne pliki appsettings.json ustawień aplikacji i appsettings.{Environment}.json, są ładowane z katalogu głównego zawartości aplikacji przez wywołanie metody CreateDefaultBuilder podczas budowy hosta.

W przypadku innych plików ustawień załadowanych przez kod dewelopera w programie ConfigureAppConfigurationnie ma potrzeby wywoływania metody SetBasePath. W poniższym przykładzie custom_settings.json plik istnieje w katalogu głównym zawartości aplikacji i jest ładowany bez jawnego ustawiania ścieżki podstawowej:

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

Nie próbuj użyć GetCurrentDirectory metody w celu uzyskania ścieżki zasobu, ponieważ aplikacja usługi systemu Windows zwraca folder C:\WINDOWS\system32 jako bieżący katalog.

Przechowywanie plików usługi w odpowiedniej lokalizacji na dysku

Określ ścieżkę bezwzględną w SetBasePath przypadku używania IConfigurationBuilder elementu do folderu zawierającego pliki.

Rozwiązywanie problemów

Aby rozwiązać problemy z aplikacją usługi systemu Windows, zobacz Rozwiązywanie problemów i debugowanie projektów ASP.NET Core.

Typowe błędy

• Używana jest stara lub wstępna wersja programu PowerShell.
• Zarejestrowana usługa nie używa opublikowanych danych wyjściowych aplikacji z polecenia dotnet publish. Dane wyjściowe polecenia dotnet build nie są obsługiwane w przypadku wdrażania aplikacji. Opublikowane zasoby znajdują się w jednym z następujących folderów w zależności od typu wdrożenia:
  • bin/Release/{TARGET FRAMEWORK}/publish (FDD)
  • bin/Release/{TARGET FRAMEWORK}/{RUNTIME IDENTIFIER}/publish (SCD)
• Usługa nie jest w stanie URUCHOMIONYm.
• Ścieżki do zasobów używanych przez aplikację (na przykład certyfikaty) są nieprawidłowe. Ścieżka podstawowa usługi systemu Windows to c:\Windows\System32.
• Użytkownik nie ma praw logowania jako usługi .
• Hasło użytkownika wygasło lub niepoprawnie zostało przekazane podczas wykonywania New-Service polecenia programu PowerShell.
• Aplikacja wymaga uwierzytelniania ASP.NET Core, ale nie jest skonfigurowana na potrzeby bezpiecznych połączeń (HTTPS).
• Port adresu URL żądania jest niepoprawny lub nie został poprawnie skonfigurowany w aplikacji.

Dzienniki zdarzeń systemu i aplikacji

Uzyskaj dostęp do dzienników zdarzeń systemu i aplikacji:

1. Otwórz menu Start, wyszukaj Podgląd zdarzeń i wybierz aplikację Podgląd zdarzeń.
2. W Podgląd zdarzeń otwórz węzeł Dzienniki systemu Windows.
3. Wybierz pozycję System, aby otworzyć dziennik zdarzeń systemu. Wybierz pozycję Aplikacja , aby otworzyć dziennik zdarzeń aplikacji.
4. Wyszukaj błędy skojarzone z aplikacją, która kończy się niepowodzeniem.

Uruchamianie aplikacji w wierszu polecenia

Wiele błędów uruchamiania nie generuje przydatnych informacji w dziennikach zdarzeń. Przyczyną niektórych błędów jest uruchomienie aplikacji w wierszu polecenia w systemie hostingu. Aby zarejestrować dodatkowe szczegóły z aplikacji, obniż poziom dziennika lub uruchom aplikację w środowisku deweloperów.

Wyczyść pamięci podręczne pakietów

Działająca aplikacja może zakończyć się niepowodzeniem natychmiast po uaktualnieniu zestawu .NET Core SDK na komputerze deweloperskim lub zmianie wersji pakietów w aplikacji. W niektórych przypadkach niespójne pakiety mogą spowodować przerwanie aplikacji podczas przeprowadzania głównych uaktualnień. Większość z tych problemów można rozwiązać, wykonując następujące instrukcje:

1. Usuń pojemnik i foldery obj.

2. Wyczyść pamięć podręczną pakietu, wykonując polecenie dotnet nuget locals all --clear z powłoki poleceń.

   Wyczyszczenie pamięci podręcznych pakietów można również wykonać za pomocą narzędzia nuget.exe i wykonać polecenie nuget locals all -clear. Nuget.exe nie jest instalacją pakietową z systemem operacyjnym Windows desktop i należy uzyskać ją oddzielnie od witryny internetowej NuGet.

3. Przywracanie i ponowne kompilowanie projektu.

4. Usuń wszystkie pliki w folderze wdrażania na serwerze przed ponownym wdrożeniem aplikacji.

Niska lub nieodpowiadjąca aplikacja

Zrzut awaryjny to migawka pamięci systemu i może pomóc w ustaleniu przyczyny awarii aplikacji, awarii uruchamiania lub powolnej aplikacji.

Aplikacja ulega awarii lub napotyka wyjątek

Uzyskiwanie i analizowanie zrzutu z Raportowanie błędów systemu Windows (WER):

1. Utwórz folder do przechowywania plików zrzutu awaryjnego pod adresem c:\dumps.

2. Uruchom skrypt EnableDumps programu PowerShell z nazwą pliku wykonywalnego aplikacji:

   .\EnableDumps {APPLICATION EXE} c:\dumps
   

3. Uruchom aplikację w warunkach, które powodują wystąpienie awarii.

4. Po wystąpieniu awarii uruchom skrypt DisableDumps programu PowerShell:

   .\DisableDumps {APPLICATION EXE}
   

Po awarii aplikacji i zakończeniu zbierania zrzutów aplikacja może zakończyć działanie normalnie. Skrypt programu PowerShell konfiguruje usługę WER do zbierania maksymalnie pięciu zrzutów na aplikację.

Ostrzeżenie

Zrzuty awaryjne mogą zająć dużą ilość miejsca na dysku (do kilku gigabajtów każdy).

Aplikacja nie odpowiada, kończy się niepowodzeniem podczas uruchamiania lub działa normalnie

Gdy aplikacja zawiesza się (przestaje odpowiadać, ale nie ulega awarii), kończy się niepowodzeniem podczas uruchamiania lub działa normalnie, zobacz Pliki zrzutu w trybie użytkownika: Wybieranie najlepszego narzędzia , aby wybrać odpowiednie narzędzie do utworzenia zrzutu.

Analizowanie zrzutu

Zrzut można analizować przy użyciu kilku metod. Aby uzyskać więcej informacji, zobacz Analizowanie pliku zrzutu trybu użytkownika.

Dodatkowe zasoby

• Wyświetl lub pobierz przykładowy kod (jak pobrać)
• Kestrel konfiguracja punktu końcowego (obejmuje konfigurację protokołu HTTPS i obsługę SNI)
• Host ogólny platformy .NET w programie ASP.NET Core
• Rozwiązywanie problemów i debugowanie projektów ASP.NET Core