Udostępnij za pośrednictwem

Moduł ASP.NET Core Module (ANCM) dla usług IIS

  • Artykuł

Uwaga

Nie jest to najnowsza wersja tego artykułu. Aby zapoznać się z bieżącą wersją, zobacz wersję tego artykułu platformy .NET 9.

Ostrzeżenie

Ta wersja ASP.NET Core nie jest już obsługiwana. Aby uzyskać więcej informacji, zobacz zasady pomocy technicznej platformy .NET i platformy .NET Core. Aby zapoznać się z bieżącą wersją, zobacz wersję tego artykułu platformy .NET 9.

Ważne

Te informacje odnoszą się do produktu w wersji wstępnej, który może zostać znacząco zmodyfikowany, zanim zostanie wydany komercyjnie. Firma Microsoft nie udziela żadnych gwarancji, jawnych lub domniemanych, w odniesieniu do informacji podanych w tym miejscu.

Aby zapoznać się z bieżącą wersją, zobacz wersję tego artykułu platformy .NET 9.

Moduł ASP.NET Core Module (ANCM) to natywny moduł usług IIS, który podłącza się do potoku usług IIS, umożliwiając ASP.NET Core aplikacji do pracy z usługami IIS. Uruchom aplikacje ASP.NET Core za pomocą usług IIS, wykonując jedną z następujących czynności:

  • Hostowanie aplikacji ASP.NET Core wewnątrz procesu roboczego usług IIS (w3wp.exe) nazywanego modelem hostingu w procesie przetwarzania.
  • Przekazywanie żądań internetowych do zaplecza ASP.NET aplikacji Core z uruchomionym Kestrel serwerem , nazywanym modelem hostingu poza procesem.

Istnieją kompromisy między poszczególnymi modelami hostingu. Domyślnie model hostingu w procesie jest używany ze względu na lepszą wydajność i diagnostykę.

Aby uzyskać więcej informacji i wskazówek dotyczących konfiguracji, zobacz następujące tematy:

Instalowanie ASP.NET Core Module (ANCM)

Moduł ASP.NET Core Module (ANCM) jest instalowany przy użyciu środowiska uruchomieniowego platformy .NET Core z pakietu hostingu platformy .NET Core. Moduł ASP.NET Core jest do przodu i do tyłu zgodny z wersjami pomocy technicznej platformy .NET.

Zmiany powodujące niezgodność i biuletyny zabezpieczeń są zgłaszane w repozytorium Anonsy. Anonsy mogą być ograniczone do określonej wersji, wybierając filtr Etykieta.

Pobierz instalatora za pomocą następującego linku:

Bieżący instalator pakietu hostingowego platformy .NET Core (pobieranie bezpośrednie)

Aby uzyskać więcej informacji, w tym zainstalowanie starszej wersji modułu, zobacz Hosting Bundle (Pakiet hostingu).

Aby zapoznać się z samouczkiem dotyczącym publikowania aplikacji ASP.NET Core na serwerze usług IIS, zobacz Publikowanie aplikacji ASP.NET Core w usługach IIS.

Moduł ASP.NET Core Module (ANCM) to natywny moduł usług IIS, który podłącza potok usług IIS do jednego z następujących elementów:

Obsługiwane wersje systemu Windows:

  • Windows 7 lub nowszy
  • Windows Server 2012 R2 lub nowszy

Podczas hostowania procesu moduł używa implementacji serwera przetwarzania dla usług IIS o nazwie SERWER HTTP usług IIS (IISHttpServer).

W przypadku hostowania poza procesem moduł działa tylko z Kestrelprogramem . Moduł nie działa z HTTP.sys.

Modele hostingu

Model hostingu wewnątrz procesu

ASP.NET Aplikacje podstawowe są domyślne dla modelu hostingu w procesie.

Podczas hostowania w procesie obowiązują następujące cechy:

  • Serwer HTTP usług IIS (IISHttpServer) jest używany zamiast Kestrel serwera. W przypadku procesu wywołania UseIIS metody CreateDefaultBuilder do:

    • Zarejestruj plik IISHttpServer.
    • Skonfiguruj port i ścieżkę podstawową, na którym serwer powinien nasłuchiwać podczas uruchamiania za modułem ASP.NET Core.
    • Skonfiguruj hosta do przechwytywania błędów uruchamiania.

  • Atrybut requestTimeout nie ma zastosowania do hostingu w procesie.

  • Udostępnianie puli aplikacji między aplikacjami nie jest obsługiwane. Użyj jednej puli aplikacji na aplikację.

  • W przypadku korzystania z narzędzia Web Deploy lub ręcznego umieszczaniaapp_offline.htm pliku we wdrożeniu aplikacja może nie zostać natychmiast zamknięta, jeśli istnieje otwarte połączenie. Na przykład połączenie protokołu WebSocket może opóźnić zamknięcie aplikacji.

  • Architektura (bitowość) aplikacji i zainstalowane środowisko uruchomieniowe (x64 lub x86) musi być zgodne z architekturą puli aplikacji.

  • Wykryto rozłączenia klienta. Token HttpContext.RequestAborted anulowania jest anulowany po rozłączeniu klienta.

  • W programie ASP.NET Core 2.2.1 lub starszym GetCurrentDirectory zwraca katalog roboczy procesu uruchomionego przez usługi IIS, a nie katalog aplikacji (na przykład C:\Windows\System32\inetsrv ).w3wp.exe

    Aby uzyskać przykładowy kod, który ustawia bieżący katalog aplikacji, zobacz klasęCurrentDirectoryHelpers. Wywołaj metodę SetCurrentDirectory . Kolejne wywołania w celu GetCurrentDirectory udostępnienia katalogu aplikacji.

  • W przypadku hostowania procesu nie jest wywoływana wewnętrznie, AuthenticateAsync aby zainicjować użytkownika. W związku z tym implementacja IClaimsTransformation używana do przekształcania oświadczeń po każdym uwierzytelnieniu nie jest domyślnie aktywowana. Podczas przekształcania oświadczeń przy użyciu implementacji wywołaj metodę IClaimsTransformation AddAuthentication , aby dodać usługi uwierzytelniania:

    public void ConfigureServices(IServiceCollection services)
{
    services.AddTransient<IClaimsTransformation, ClaimsTransformer>();
    services.AddAuthentication(IISServerDefaults.AuthenticationScheme);
}

public void Configure(IApplicationBuilder app)
{
    app.UseAuthentication();
}
    • Wdrożenia pakietu internetowego (pojedynczego pliku) nie są obsługiwane.

Model hostingu poza procesem

Aby skonfigurować aplikację na potrzeby hostingu poza procesem, ustaw wartość <AspNetCoreHostingModel> właściwości na OutOfProcess w pliku projektu (.csproj):

<PropertyGroup>
  <AspNetCoreHostingModel>OutOfProcess</AspNetCoreHostingModel>
</PropertyGroup>

Hostowanie procesów jest ustawiane na InProcesswartość , która jest wartością domyślną.

Wartość <AspNetCoreHostingModel> jest niewrażliwa na wielkość liter, więc inprocess i outofprocess są prawidłowymi wartościami.

Kestrel Serwer jest używany zamiast serwera HTTP usług IIS (IISHttpServer).

W przypadku braku procesu CreateDefaultBuilder wywołania UseIISIntegration :

  • Skonfiguruj port i ścieżkę podstawową, na którym serwer powinien nasłuchiwać podczas uruchamiania za modułem ASP.NET Core.
  • Skonfiguruj hosta do przechwytywania błędów uruchamiania.

Zmiany modelu hostingu

hostingModel Jeśli ustawienie zostanie zmienione w web.config pliku (wyjaśnione w sekcji Konfiguracja za pomocąweb.config), moduł przetwarza proces roboczy dla usług IIS.

W przypadku usług IIS Express moduł nie przetwarza procesu roboczego, ale zamiast tego wyzwala bezproblemowe zamknięcie bieżącego procesu IIS Express. Następne żądanie do aplikacji zduplikuje nowy proces usług IIS Express.

Nazwa procesu

Process.GetCurrentProcess().ProcessName raporty w3wp/iisexpress (proces) lub dotnet (poza procesem).

Wiele modułów natywnych, takich jak uwierzytelnianie systemu Windows, pozostaje aktywnych. Aby dowiedzieć się więcej o modułach usług IIS aktywnych przy użyciu modułu podstawowego ASP.NET, zobacz Moduły usług IIS z ASP.NET Core.

Moduł ASP.NET Core może również wykonywać następujące czynności:

  • Ustaw zmienne środowiskowe dla procesu roboczego.
  • Rejestrowanie danych wyjściowych stdout w magazynie plików w celu rozwiązywania problemów z uruchamianiem.
  • Przekazywanie tokenów uwierzytelniania systemu Windows.

Jak zainstalować moduł ASP.NET Core Module (ANCM) i korzystać z niego

Aby uzyskać instrukcje dotyczące sposobu instalowania modułu ASP.NET Core, zobacz Instalowanie pakietu hostingu platformy .NET Core. Moduł ASP.NET Core jest do przodu i do tyłu zgodny z wersjami pomocy technicznej platformy .NET.

Zmiany powodujące niezgodność i biuletyny zabezpieczeń są zgłaszane w repozytorium Anonsy. Anonsy mogą być ograniczone do określonej wersji, wybierając filtr Etykieta.

Konfiguracja za pomocą pliku web.config

Moduł ASP.NET Core jest skonfigurowany z sekcją aspNetCore system.webServer węzła w pliku web.config witryny.

Następujący web.config plik jest publikowany na potrzeby wdrożenia zależnego od platformy i konfiguruje moduł ASP.NET Core do obsługi żądań lokacji:

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <location path="." inheritInChildApplications="false">
    <system.webServer>
      <handlers>
        <add name="aspNetCore" path="*" verb="*" modules="AspNetCoreModuleV2" resourceType="Unspecified" />
      </handlers>
      <aspNetCore processPath="dotnet"
                  arguments=".\MyApp.dll"
                  stdoutLogEnabled="false"
                  stdoutLogFile=".\logs\stdout"
                  hostingModel="inprocess" />
    </system.webServer>
  </location>
</configuration>

Następująca konfiguracja web.config jest opublikowana dla samodzielnego wdrożenia:

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <location path="." inheritInChildApplications="false">
    <system.webServer>
      <handlers>
        <add name="aspNetCore" path="*" verb="*" modules="AspNetCoreModuleV2" resourceType="Unspecified" />
      </handlers>
      <aspNetCore processPath=".\MyApp.exe"
                  stdoutLogEnabled="false"
                  stdoutLogFile=".\logs\stdout"
                  hostingModel="inprocess" />
    </system.webServer>
  </location>
</configuration>

Właściwość jest ustawiona InheritInChildApplications na wartość , aby wskazać false , że ustawienia określone w elemecie <location> nie są dziedziczone przez aplikacje znajdujące się w podkatalogu aplikacji.

Po wdrożeniu aplikacji w usłudze aplikacja systemu Azure ścieżka jest ustawiona stdoutLogFile na \\?\%home%\LogFiles\stdout. Ścieżka zapisuje dzienniki stdout w LogFiles folderze, który jest lokalizacją automatycznie utworzoną przez usługę.

Aby uzyskać informacje na temat konfiguracji podrzędnej aplikacji usług IIS, zobacz Host ASP.NET Core w systemie Windows z usługami IIS.

Atrybuty elementu aspNetCore

Atrybut opis Wartość domyślna
arguments

Opcjonalny atrybut ciągu.

Argumenty pliku wykonywalnego określonego w processPath.
disableStartUpErrorPage

Opcjonalny atrybut logiczny.

Jeśli wartość true, strona 502.5 — Niepowodzenie procesu jest pomijana, a strona kodowa stanu 502 skonfigurowana w pliku web.config ma pierwszeństwo.

 false
forwardWindowsAuthToken

Opcjonalny atrybut logiczny.

Jeśli wartość true, token jest przekazywany do procesu podrzędnego nasłuchiwania %ASPNETCORE_PORT% jako nagłówka 'MS-ASPNETCORE-WINAUTHTOKEN' na żądanie. Jest to odpowiedzialność za wywołanie metody CloseHandle na tym tokenie na żądanie.

 true
hostingModel

Opcjonalny atrybut ciągu.

Określa model hostingu jako proces (InProcess/inprocess) lub poza procesem ().OutOfProcess/outofprocess

 InProcess
inprocess
processesPerApplication

Opcjonalny atrybut liczby całkowitej.

Określa liczbę wystąpień procesu określonego w ustawieniu processPath , które można połączyć na aplikację.

†Do hostingu w procesie wartość jest ograniczona do 1.

Ustawienie processesPerApplication jest odradzane. Ten atrybut zostanie usunięty w przyszłej wersji.

 Domyślnie: 1
Min: 1
Maksymalna: 100†
processPath

Wymagany atrybut ciągu.

Ścieżka do pliku wykonywalnego, który uruchamia proces nasłuchiwania żądań HTTP. Ścieżki względne są obsługiwane. Jeśli ścieżka zaczyna się od ., ścieżka jest uważana za względną względem katalogu głównego witryny.
rapidFailsPerMinute

Opcjonalny atrybut liczby całkowitej.

Określa liczbę przypadków awarii procesu określonego w programie processPath na minutę. Jeśli ten limit zostanie przekroczony, moduł przestanie uruchamiać proces w pozostałej części minuty.

Nieobsługiwane w przypadku hostingu w procesie.

 Domyślnie: 10
Min: 0
Max: 100
requestTimeout

Opcjonalny atrybut przedziału czasu.

Określa czas trwania, przez który moduł ASP.NET Core czeka na odpowiedź z procesu nasłuchiwania na %ASPNETCORE_PORT%.

W wersjach modułu ASP.NET Core dostarczanego z wydaniem ASP.NET Core 2.1 lub nowszym requestTimeout parametr jest określony w godzinach, minutach i sekundach.

Nie ma zastosowania do hostingu w procesie. W przypadku hostingu w procesie moduł czeka na przetworzenie żądania przez aplikację.

Prawidłowe wartości dla segmentów ciągu w minutach i sekundach znajdują się w zakresie od 0 do 59. Użycie wartości 60 w ciągu minut lub sekund powoduje wystąpienie błędu 500 — wewnętrzny serwer.

 Domyślnie: 00:02:00
Min: 00:00:00
Max: 360:00:00
shutdownTimeLimit

Opcjonalny atrybut liczby całkowitej.

Czas trwania w sekundach oczekiwania modułu na bezproblemowe zamknięcie pliku wykonywalnego po app_offline.htm wykryciu pliku.

 Domyślnie: 10
Min: 0
Max: 600
startupTimeLimit

Opcjonalny atrybut liczby całkowitej.

Czas trwania w sekundach oczekiwania modułu na uruchomienie procesu nasłuchiwania na porcie. Jeśli ten limit czasu zostanie przekroczony, moduł zabije ten proces.

W przypadku hostowania procesu: proces nie jest uruchamiany ponownie i nie używa ustawienia rapidFailsPerMinute.

Podczas hostowania procesu poza procesem: moduł próbuje ponownie uruchomić proces po odebraniu nowego żądania i nadal próbuje ponownie uruchomić proces na kolejnych żądaniach przychodzących, chyba że aplikacja nie może uruchomić funkcji rapidFailsPerMinute kilka razy w ostatniej minucie stopniowej.

Wartość 0 (zero) nie jest uważana za nieskończony limit czasu.

 Domyślnie: 120
Min: 0
Max: 3600
stdoutLogEnabled

Opcjonalny atrybut logiczny.

Jeśli wartość true, stdout i stderr dla procesu określonego w processPath są przekierowywane do pliku określonego w pliku stdoutLogFile.

false
stdoutLogFile

Opcjonalny atrybut ciągu.

Określa względną lub bezwzględną ścieżkę pliku, dla której są rejestrowane ścieżki stdout i stderr z procesu określonego w processPath . Ścieżki względne są względne względem katalogu głównego witryny. Każda ścieżka rozpoczynająca się od . elementu jest względna względem katalogu głównego witryny, a wszystkie inne ścieżki są traktowane jako ścieżki bezwzględne. Wszystkie foldery podane w ścieżce są tworzone przez moduł podczas tworzenia pliku dziennika. Przy użyciu ograniczników podkreślenia znacznik czasu, identyfikator procesu i rozszerzenie pliku (.log) są dodawane do ostatniego segmentu ścieżki stdoutLogFile . Jeśli .\logs\stdout zostanie podana jako wartość, przykładowy dziennik stdout zostanie zapisany jako stdout_20180205194132_1934.log w logs folderze zapisanym w dniu 2/5/2018 o 19:41:32 z identyfikatorem procesu 1934.

 aspnetcore-stdout

Ustawianie zmiennych środowiskowych

Zmienne środowiskowe można określić dla procesu w atrybucie processPath . Określ zmienną środowiskową z <environmentVariable> elementem podrzędnym <environmentVariables> elementu kolekcji. Zmienne środowiskowe ustawione w tej sekcji mają pierwszeństwo przed zmiennymi środowiskowymi systemu.

W poniższym przykładzie ustawiono dwie zmienne środowiskowe w pliku web.config. ASPNETCORE_ENVIRONMENT Konfiguruje środowisko aplikacji na Development. Deweloper może tymczasowo ustawić tę wartość w pliku, web.config aby wymusić załadowanie strony wyjątku dewelopera podczas debugowania wyjątku aplikacji. CONFIG_DIR to przykład zmiennej środowiskowej zdefiniowanej przez użytkownika, w której deweloper napisał kod, który odczytuje wartość podczas uruchamiania, aby utworzyć ścieżkę ładowania pliku konfiguracji aplikacji.

<aspNetCore processPath="dotnet"
      arguments=".\MyApp.dll"
      stdoutLogEnabled="false"
      stdoutLogFile=".\logs\stdout"
      hostingModel="inprocess">
  <environmentVariables>
    <environmentVariable name="ASPNETCORE_ENVIRONMENT" value="Development" />
    <environmentVariable name="CONFIG_DIR" value="f:\application_config" />
  </environmentVariables>
</aspNetCore>

Uwaga

Alternatywą dla ustawienia środowiska bezpośrednio w programie web.config jest dołączenie <EnvironmentName> właściwości do profilu publikowania (.pubxml) lub pliku projektu. To podejście ustawia środowisko w web.config momencie opublikowania projektu:

<PropertyGroup>
  <EnvironmentName>Development</EnvironmentName>
</PropertyGroup>

Ostrzeżenie

Ustaw zmienną ASPNETCORE_ENVIRONMENT środowiskową Development tylko na serwery przejściowe i testowe, które nie są dostępne dla niezaufanych sieci, takich jak Internet.

app_offline.htm

Jeśli plik o nazwie app_offline.htm zostanie wykryty w katalogu głównym aplikacji, moduł ASP.NET Core próbuje bezpiecznie zamknąć aplikację i zatrzymać przetwarzanie żądań przychodzących. Jeśli aplikacja jest nadal uruchomiona po liczbie sekund zdefiniowanych w programie shutdownTimeLimit, moduł ASP.NET Core zabija uruchomiony proces.

app_offline.htm Gdy plik jest obecny, moduł ASP.NET Core odpowiada na żądania, wysyłając z powrotem zawartość app_offline.htm pliku. Po usunięciu app_offline.htm pliku następne żądanie uruchamia aplikację.

W przypadku korzystania z modelu hostingu poza procesem aplikacja może nie zostać natychmiast zamknięta, jeśli istnieje otwarte połączenie. Na przykład połączenie protokołu WebSocket może opóźnić zamknięcie aplikacji.

Strona błędu uruchamiania

Zarówno w procesie, jak i poza procesem hostingu generują niestandardowe strony błędów, gdy nie można uruchomić aplikacji.

Jeśli moduł ASP.NET Core nie może odnaleźć procedury obsługi żądań w procesie lub poza procesem, zostanie wyświetlona strona kodowa stanu błędu ładowania 500.0 — In-Process/Out-Of-Process Handler.

W przypadku hostowania w procesie, jeśli nie można uruchomić aplikacji ASP.NET Core Module, zostanie wyświetlona strona kodowa stanu niepowodzenia 500.30.

W przypadku hostowania poza procesem, jeśli moduł ASP.NET Core nie może uruchomić procesu zaplecza lub proces zaplecza zostanie uruchomiony, ale nie można nasłuchiwać na skonfigurowanym porcie, zostanie wyświetlona strona kodowa stanu błędu procesu 502.5.

Aby pominąć tę stronę i przywrócić domyślną stronę kodu stanu usług IIS 5xx, użyj atrybutu disableStartUpErrorPage . Aby uzyskać więcej informacji na temat konfigurowania niestandardowych komunikatów o błędach, zobacz Błędy <httpErrors>HTTP .

Tworzenie i przekierowywanie dzienników

Moduł ASP.NET Core przekierowuje dane wyjściowe konsoli stdout i stderr do dysku, jeśli stdoutLogEnabled ustawiono atrybuty aspNetCore i stdoutLogFile elementu. Wszystkie foldery w ścieżce stdoutLogFile są tworzone przez moduł podczas tworzenia pliku dziennika. Pula aplikacji musi mieć dostęp do zapisu w lokalizacji, w której są zapisywane dzienniki (użyj IIS AppPool\<app_pool_name> polecenia w celu udzielenia uprawnień do zapisu).

Dzienniki nie są obracane, chyba że nastąpi ponowne odtwarzanie/ponowne uruchomienie procesu. Jest to odpowiedzialność hosta za ograniczenie miejsca na dysku używanego przez dzienniki.

Korzystanie z dziennika stdout jest zalecane tylko w przypadku rozwiązywania problemów z uruchamianiem aplikacji podczas hostowania w usługach IIS lub korzystania z obsługi czasu programowania dla usług IIS w programie Visual Studio, a nie podczas debugowania lokalnie i uruchamiania aplikacji za pomocą usług IIS Express.

Nie używaj dziennika stdout do ogólnych celów rejestrowania aplikacji. W przypadku rutynowego rejestrowania w aplikacji ASP.NET Core użyj biblioteki rejestrowania, która ogranicza rozmiar pliku dziennika i obraca dzienniki. Aby uzyskać więcej informacji, zobacz dostawcy rejestrowania innych firm.

Znacznik czasu i rozszerzenie pliku są dodawane automatycznie po utworzeniu pliku dziennika. Nazwa pliku dziennika składa się z dołączania znacznika czasu, identyfikatora procesu i rozszerzenia pliku (.log) do ostatniego segmentu stdoutLogFile ścieżki (zazwyczaj stdout) rozdzielanego znakami podkreślenia. stdoutLogFile Jeśli ścieżka kończy się ciągiem stdout, dziennik aplikacji z identyfikatorem PID z 1934 r. utworzonym w dniu 2.5.2018 o godzinie 19:42:32 ma nazwę stdout_20180205194132_1934.logpliku .

Jeśli stdoutLogEnabled jest to fałsz, błędy występujące podczas uruchamiania aplikacji są przechwytywane i emitowane do dziennika zdarzeń do 30 KB. Po uruchomieniu wszystkie dodatkowe dzienniki zostaną odrzucone.

Poniższy przykładowy aspNetCore element konfiguruje rejestrowanie stdout w ścieżce .\log\względnej . Upewnij się, że użytkownik identity puli aplikacji ma uprawnienia do zapisu w podanej ścieżce.

<aspNetCore processPath="dotnet"
    arguments=".\MyApp.dll"
    stdoutLogEnabled="true"
    stdoutLogFile=".\logs\stdout"
    hostingModel="inprocess">
</aspNetCore>

Podczas publikowania aplikacji na potrzeby wdrożenia usługi aplikacja systemu Azure zestaw SDK sieci Web ustawia stdoutLogFile wartość na \\?\%home%\LogFiles\stdout. Zmienna %home środowiskowa jest wstępnie zdefiniowana dla aplikacji hostowanych przez usługę aplikacja systemu Azure.

Aby utworzyć reguły filtru rejestrowania, zobacz sekcję Stosowanie reguł filtru dziennika w kodzie dokumentacji rejestrowania ASP.NET Core.

Aby uzyskać więcej informacji na temat formatów ścieżek, zobacz Formaty ścieżek plików w systemach Windows.

Rozszerzone dzienniki diagnostyczne

Moduł ASP.NET Core można skonfigurować w celu zapewnienia rozszerzonych dzienników diagnostycznych. <handlerSettings> Dodaj element do elementu w pliku <aspNetCore> web.config. Ustawienie elementu debugLevel w celu TRACE uwidocznienia wyższej wierności informacji diagnostycznych:

<aspNetCore processPath="dotnet"
    arguments=".\MyApp.dll"
    stdoutLogEnabled="false"
    stdoutLogFile="\\?\%home%\LogFiles\stdout"
    hostingModel="inprocess">
  <handlerSettings>
    <handlerSetting name="debugFile" value=".\logs\aspnetcore-debug.log" />
    <handlerSetting name="debugLevel" value="FILE,TRACE" />
  </handlerSettings>
</aspNetCore>

Wszystkie foldery w ścieżce (logs w poprzednim przykładzie) są tworzone przez moduł podczas tworzenia pliku dziennika. Pula aplikacji musi mieć dostęp do zapisu w lokalizacji, w której są zapisywane dzienniki (użyj IIS AppPool\{APP POOL NAME}symbolu zastępczego , gdzie symbol zastępczy {APP POOL NAME} to nazwa puli aplikacji, aby zapewnić uprawnienie do zapisu).

Wartości poziomu debugowania (debugLevel) mogą obejmować zarówno poziom, jak i lokalizację.

Poziomy (w kolejności od najmniejszej do najbardziej pełnej):

  • BŁĄD
  • OSTRZEŻENIE
  • INFO
  • TRACE

Lokalizacje (dozwolone są wiele lokalizacji):

  • CONSOLE
  • DZIENNIK ZDARZEŃ
  • PLIK

Ustawienia programu obsługi można również udostępnić za pomocą zmiennych środowiskowych:

  • ASPNETCORE_MODULE_DEBUG_FILE: ścieżka do pliku dziennika debugowania. (Ustawienie domyślne: aspnetcore-debug.log)
  • ASPNETCORE_MODULE_DEBUG: Ustawienie poziomu debugowania.

Ostrzeżenie

Nie należy pozostawiać rejestrowania debugowania włączonego we wdrożeniu dłużej niż jest to wymagane do rozwiązania problemu. Rozmiar dziennika nie jest ograniczony. Pozostawienie włączonego dziennika debugowania może wyczerpać dostępne miejsce na dysku i awarii serwera lub usługi app Service.

Zobacz Configuration with web.config (Konfiguracja za pomocą pliku web.config ), aby zapoznać się z przykładem aspNetCore elementu w web.config pliku.

Modyfikowanie rozmiaru stosu

Ma zastosowanie tylko w przypadku korzystania z modelu hostingu w procesie.

Skonfiguruj rozmiar zarządzanego stosu stackSize przy użyciu ustawienia w bajtach w pliku web.config. Domyślny rozmiar to 1 048 576 bajtów (1 MB).

<aspNetCore processPath="dotnet"
    arguments=".\MyApp.dll"
    stdoutLogEnabled="false"
    stdoutLogFile="\\?\%home%\LogFiles\stdout"
    hostingModel="inprocess">
  <handlerSettings>
    <handlerSetting name="stackSize" value="2097152" />
  </handlerSettings>
</aspNetCore>

Konfiguracja serwera proxy używa protokołu HTTP i tokenu parowania

Dotyczy tylko hostingu poza procesem.

Serwer proxy utworzony między modułem ASP.NET Core i Kestrel używa protokołu HTTP. Nie ma ryzyka podsłuchiwania ruchu między modułem a Kestrel lokalizacją poza serwerem.

Token parowania służy do zagwarantowania, że żądania odebrane przez Kestrel usługę IIS były proxied przez usługi IIS i nie pochodziły z innego źródła. Token parowania jest tworzony i ustawiany w zmiennej środowiskowej (ASPNETCORE_TOKEN) przez moduł. Token parowania jest również ustawiany na nagłówek (MS-ASPNETCORE-TOKEN) dla każdego żądania proxied. Oprogramowanie pośredniczące USŁUG IIS sprawdza każde odebrane żądanie, aby potwierdzić, że wartość nagłówka tokenu parowania jest zgodna z wartością zmiennej środowiskowej. Jeśli wartości tokenu są niezgodne, żądanie jest rejestrowane i odrzucane. Zmienna środowiskowa tokenu parowania i ruch między modułem i Kestrel nie są dostępne z lokalizacji poza serwerem. Bez znajomości wartości tokenu parowania cyberatak nie może przesyłać żądań, które pomijają ewidencjonowanie oprogramowania pośredniczącego usług IIS.

ASP.NET Core Module z konfiguracją udostępnioną usług IIS

Instalator modułu ASP.NET Core jest uruchamiany z uprawnieniami konta TrustedInstaller . Ponieważ lokalne konto systemowe nie ma uprawnień do modyfikowania ścieżki udziału używanej przez konfigurację udostępnioną usług IIS, instalator zgłasza błąd odmowy dostępu podczas próby skonfigurowania ustawień modułu w pliku w applicationHost.config udziale.

W przypadku korzystania z konfiguracji udostępnionej usług IIS na tej samej maszynie co instalacja usług IIS uruchom instalator pakietu hostingu podstawowego ASP.NET z parametrem ustawionym OPT_NO_SHARED_CONFIG_CHECK na 1:

dotnet-hosting-{VERSION}.exe OPT_NO_SHARED_CONFIG_CHECK=1

Jeśli ścieżka do konfiguracji udostępnionej nie znajduje się na tej samej maszynie co instalacja usług IIS, wykonaj następujące kroki:

  1. Wyłącz konfigurację udostępnioną usług IIS.
  2. Uruchom instalatora.
  3. Wyeksportuj zaktualizowany applicationHost.config plik do udziału.
  4. Ponownie włącz konfigurację udostępnioną usług IIS.

Dzienniki instalatora wersji modułu i pakietu hostingu

Aby określić wersję zainstalowanego modułu ASP.NET Core:

  1. W systemie hostingu przejdź do %windir%\System32\inetsrvadresu .
  2. aspnetcore.dll Znajdź plik.
  3. Kliknij plik prawym przyciskiem myszy i wybierz polecenie Właściwości z menu kontekstowego.
  4. Wybierz kartę Szczegóły. Wersja pliku i wersja produktu reprezentują zainstalowaną wersję modułu.

Dzienniki instalatora pakietu hostingu dla modułu znajdują się pod adresem C:\Users\%UserName%\AppData\Local\Temp. Plik ma nazwę dd_DotNetCoreWinSvrHosting__{TIMESTAMP}_000_AspNetCoreModule_x64.log.

Lokalizacje plików modułu, schematu i konfiguracji

Moduł

IIS (x86/amd64):

  • %windir%\System32\inetsrv\aspnetcore.dll

  • %windir%\SysWOW64\inetsrv\aspnetcore.dll

  • %ProgramFiles%\IIS\Asp.Net Core Module\V2\aspnetcorev2.dll

  • %ProgramFiles(x86)%\IIS\Asp.Net Core Module\V2\aspnetcorev2.dll

IIS Express (x86/amd64):

  • %ProgramFiles%\IIS Express\aspnetcore.dll

  • %ProgramFiles(x86)%\IIS Express\aspnetcore.dll

  • %ProgramFiles%\IIS Express\Asp.Net Core Module\V2\aspnetcorev2.dll

  • %ProgramFiles(x86)%\IIS Express\Asp.Net Core Module\V2\aspnetcorev2.dll

Schemat

IIS

  • %windir%\System32\inetsrv\config\schema\aspnetcore_schema.xml

  • %windir%\System32\inetsrv\config\schema\aspnetcore_schema_v2.xml

IIS Express

  • %ProgramFiles%\IIS Express\config\schema\aspnetcore_schema.xml

  • %ProgramFiles%\IIS Express\config\schema\aspnetcore_schema_v2.xml

Konfigurowanie

IIS

  • %windir%\System32\inetsrv\config\applicationHost.config

IIS Express

  • Visual Studio: {APPLICATION ROOT}\.vs\config\applicationHost.config

  • interfejs wiersza polecenia iisexpress.exe:%USERPROFILE%\Documents\IISExpress\config\applicationhost.config

Pliki można znaleźć, wyszukując aspnetcore applicationHost.config w pliku.

Moduł ASP.NET Core Module (ANCM) to natywny moduł usług IIS, który podłącza potok usług IIS do jednego z następujących elementów:

Obsługiwane wersje systemu Windows:

  • Windows 7 lub nowszy
  • Windows Server 2008 R2 lub nowszy

Podczas hostowania procesu moduł używa implementacji serwera przetwarzania dla usług IIS o nazwie SERWER HTTP usług IIS (IISHttpServer).

W przypadku hostowania poza procesem moduł działa tylko z Kestrelprogramem . Moduł nie działa z HTTP.sys.

Modele hostingu

Model hostingu wewnątrz procesu

Aby skonfigurować aplikację do hostowania procesów, dodaj <AspNetCoreHostingModel> właściwość do pliku projektu aplikacji z wartością InProcess (hosting poza procesem jest ustawiony za pomocą OutOfProcesspolecenia ):

<PropertyGroup>
  <AspNetCoreHostingModel>InProcess</AspNetCoreHostingModel>
</PropertyGroup>

Model hostingu w procesie nie jest obsługiwany w przypadku aplikacji ASP.NET Core przeznaczonych dla platformy .NET Framework.

Wartość <AspNetCoreHostingModel> jest niewrażliwa na wielkość liter, więc inprocess i outofprocess są prawidłowymi wartościami.

<AspNetCoreHostingModel> Jeśli właściwość nie istnieje w pliku, wartość domyślna to OutOfProcess.

Podczas hostowania w procesie obowiązują następujące cechy:

  • Serwer HTTP usług IIS (IISHttpServer) jest używany zamiast Kestrel serwera. W przypadku procesu wywołania UseIIS metody CreateDefaultBuilder do:

    • Zarejestruj plik IISHttpServer.
    • Skonfiguruj port i ścieżkę podstawową, na którym serwer powinien nasłuchiwać podczas uruchamiania za modułem ASP.NET Core.
    • Skonfiguruj hosta do przechwytywania błędów uruchamiania.

  • Atrybut requestTimeout nie ma zastosowania do hostingu w procesie.

  • Udostępnianie puli aplikacji między aplikacjami nie jest obsługiwane. Użyj jednej puli aplikacji na aplikację.

  • W przypadku korzystania z narzędzia Web Deploy lub ręcznego umieszczania pliku app_offline.htm we wdrożeniu aplikacja może nie zostać natychmiast zamknięta, jeśli istnieje otwarte połączenie. Na przykład połączenie protokołu websocket może opóźnić zamknięcie aplikacji.

  • Architektura (bitowość) aplikacji i zainstalowane środowisko uruchomieniowe (x64 lub x86) musi być zgodne z architekturą puli aplikacji.

  • Wykryto rozłączenia klienta. Token anulowania httpContext.RequestAborted jest anulowany po rozłączeniu klienta.

  • W programie ASP.NET Core 2.2.1 lub starszym GetCurrentDirectory zwraca katalog roboczy procesu uruchomionego przez usługi IIS, a nie katalog aplikacji (na przykład C:\Windows\System32\inetsrv dla w3wp.exe).

    Aby uzyskać przykładowy kod, który ustawia bieżący katalog aplikacji, zobacz klasę CurrentDirectoryHelpers. Wywołaj metodę SetCurrentDirectory . Kolejne wywołania w celu GetCurrentDirectory udostępnienia katalogu aplikacji.

  • W przypadku hostowania procesu nie jest wywoływana wewnętrznie, AuthenticateAsync aby zainicjować użytkownika. W związku z tym implementacja IClaimsTransformation używana do przekształcania oświadczeń po każdym uwierzytelnieniu nie jest domyślnie aktywowana. Podczas przekształcania oświadczeń przy użyciu implementacji wywołaj metodę IClaimsTransformation AddAuthentication , aby dodać usługi uwierzytelniania:

    public void ConfigureServices(IServiceCollection services)
{
    services.AddTransient<IClaimsTransformation, ClaimsTransformer>();
    services.AddAuthentication(IISServerDefaults.AuthenticationScheme);
}

public void Configure(IApplicationBuilder app)
{
    app.UseAuthentication();
}

Model hostingu poza procesem

Aby skonfigurować aplikację na potrzeby hostingu poza procesem, użyj jednej z następujących metod w pliku projektu:

  • Nie określaj <AspNetCoreHostingModel> właściwości. <AspNetCoreHostingModel> Jeśli właściwość nie istnieje w pliku, wartość domyślna to OutOfProcess.
  • Ustaw wartość <AspNetCoreHostingModel> właściwości na OutOfProcess (hosting w procesie jest ustawiony na InProcess):
<PropertyGroup>
  <AspNetCoreHostingModel>OutOfProcess</AspNetCoreHostingModel>
</PropertyGroup>

Wartość jest niewrażliwa na wielkość liter, więc inprocess i outofprocess są prawidłowymi wartościami.

Kestrel Serwer jest używany zamiast serwera HTTP usług IIS (IISHttpServer).

W przypadku braku procesu wywołania UseIISIntegration metody CreateDefaultBuilder do:

  • Skonfiguruj port i ścieżkę podstawową, na którym serwer powinien nasłuchiwać podczas uruchamiania za modułem ASP.NET Core.
  • Skonfiguruj hosta do przechwytywania błędów uruchamiania.

Zmiany modelu hostingu

hostingModel Jeśli ustawienie zostanie zmienione w pliku web.config (wyjaśnione w sekcji Konfiguracja za pomocą pliku web.config), moduł przetwarza proces roboczy dla usług IIS.

W przypadku usług IIS Express moduł nie przetwarza procesu roboczego, ale zamiast tego wyzwala bezproblemowe zamknięcie bieżącego procesu IIS Express. Następne żądanie do aplikacji zduplikuje nowy proces usług IIS Express.

Nazwa procesu

Process.GetCurrentProcess().ProcessName raporty w3wp/iisexpress (proces) lub dotnet (poza procesem).

Wiele modułów natywnych, takich jak uwierzytelnianie systemu Windows, pozostaje aktywnych. Aby dowiedzieć się więcej o modułach usług IIS aktywnych przy użyciu modułu podstawowego ASP.NET, zobacz Moduły usług IIS z ASP.NET Core.

Moduł ASP.NET Core może również wykonywać następujące czynności:

  • Ustaw zmienne środowiskowe dla procesu roboczego.
  • Rejestrowanie danych wyjściowych stdout w magazynie plików w celu rozwiązywania problemów z uruchamianiem.
  • Przekazywanie tokenów uwierzytelniania systemu Windows.

Jak zainstalować moduł ASP.NET Core Module (ANCM) i korzystać z niego

Aby uzyskać instrukcje dotyczące sposobu instalowania modułu ASP.NET Core, zobacz Instalowanie pakietu hostingu platformy .NET Core. Moduł ASP.NET Core jest do przodu i do tyłu zgodny z wersjami pomocy technicznej platformy .NET.

Zmiany powodujące niezgodność i biuletyny zabezpieczeń są zgłaszane w repozytorium Anonsy. Anonsy mogą być ograniczone do określonej wersji, wybierając filtr Etykieta.

Konfiguracja za pomocą pliku web.config

Moduł ASP.NET Core jest skonfigurowany z sekcją aspNetCore system.webServer węzła w pliku web.config witryny.

Następujący plik web.config jest publikowany na potrzeby wdrożenia zależnego od platformy i konfiguruje moduł ASP.NET Core do obsługi żądań lokacji:

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <location path="." inheritInChildApplications="false">
    <system.webServer>
      <handlers>
        <add name="aspNetCore" path="*" verb="*" modules="AspNetCoreModuleV2" resourceType="Unspecified" />
      </handlers>
      <aspNetCore processPath="dotnet"
                  arguments=".\MyApp.dll"
                  stdoutLogEnabled="false"
                  stdoutLogFile=".\logs\stdout"
                  hostingModel="inprocess" />
    </system.webServer>
  </location>
</configuration>

Następująca konfiguracja web.config jest opublikowana dla samodzielnego wdrożenia:

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <location path="." inheritInChildApplications="false">
    <system.webServer>
      <handlers>
        <add name="aspNetCore" path="*" verb="*" modules="AspNetCoreModuleV2" resourceType="Unspecified" />
      </handlers>
      <aspNetCore processPath=".\MyApp.exe"
                  stdoutLogEnabled="false"
                  stdoutLogFile=".\logs\stdout"
                  hostingModel="inprocess" />
    </system.webServer>
  </location>
</configuration>

Właściwość jest ustawiona InheritInChildApplications na wartość , aby wskazać false , że ustawienia określone w elemecie <location> nie są dziedziczone przez aplikacje znajdujące się w podkatalogu aplikacji.

Po wdrożeniu aplikacji w usłudze aplikacja systemu Azure ścieżka jest ustawiona stdoutLogFile na \\?\%home%\LogFiles\stdout. Ścieżka zapisuje dzienniki stdout w folderze LogFiles , który jest lokalizacją automatycznie utworzoną przez usługę.

Aby uzyskać informacje na temat konfiguracji podrzędnej aplikacji usług IIS, zobacz Host ASP.NET Core w systemie Windows z usługami IIS.

Atrybuty elementu aspNetCore

Atrybut opis Wartość domyślna
arguments

Opcjonalny atrybut ciągu.

Argumenty pliku wykonywalnego określonego w pliku processPath.
disableStartUpErrorPage

Opcjonalny atrybut logiczny.

Jeśli wartość true, strona 502.5 — Niepowodzenie procesu jest pomijana, a strona kodowa stanu 502 skonfigurowana w pliku web.config ma pierwszeństwo.

 false
forwardWindowsAuthToken

Opcjonalny atrybut logiczny.

Jeśli to prawda, token jest przekazywany do procesu podrzędnego nasłuchiwania w %ASPNETCORE_PORT% jako nagłówek "MS-ASPNETCORE-WINAUTHTOKEN" na żądanie. Jest to odpowiedzialność za wywołanie metody CloseHandle na tym tokenie na żądanie.

 true
hostingModel

Opcjonalny atrybut ciągu.

Określa model hostingu jako proces (InProcess/inprocess) lub poza procesem ().OutOfProcess/outofprocess

 OutOfProcess
outofprocess
processesPerApplication

Opcjonalny atrybut liczby całkowitej.

Określa liczbę wystąpień procesu określonego processPath w ustawieniu, które można połączyć na aplikację.

†Do hostingu w procesie wartość jest ograniczona do 1.

Ustawienie processesPerApplication jest odradzane. Ten atrybut zostanie usunięty w przyszłej wersji.

 Domyślnie: 1
Min: 1
Maksymalna: 100†
processPath

Wymagany atrybut ciągu.

Ścieżka do pliku wykonywalnego, który uruchamia proces nasłuchiwania żądań HTTP. Ścieżki względne są obsługiwane. Jeśli ścieżka zaczyna się od ., ścieżka jest uważana za względną względem katalogu głównego witryny.
rapidFailsPerMinute

Opcjonalny atrybut liczby całkowitej.

Określa liczbę przypadków, w których proces określony w processPath programie może ulec awarii na minutę. Jeśli ten limit zostanie przekroczony, moduł przestanie uruchamiać proces w pozostałej części minuty.

Nieobsługiwane w przypadku hostingu w procesie.

 Domyślnie: 10
Min: 0
Max: 100
requestTimeout

Opcjonalny atrybut przedziału czasu.

Określa czas trwania, przez który moduł ASP.NET Core czeka na odpowiedź z procesu nasłuchiwania na %ASPNETCORE_PORT%.

W wersjach modułu ASP.NET Core dostarczanego z wydaniem ASP.NET Core 2.1 lub nowszym requestTimeout parametr jest określony w godzinach, minutach i sekundach.

Nie ma zastosowania do hostingu w procesie. W przypadku hostingu w procesie moduł czeka na przetworzenie żądania przez aplikację.

Prawidłowe wartości dla segmentów ciągu w minutach i sekundach znajdują się w zakresie od 0 do 59. Użycie wartości 60 w ciągu minut lub sekund powoduje wystąpienie błędu 500 — wewnętrzny serwer.

 Domyślnie: 00:02:00
Min: 00:00:00
Max: 360:00:00
shutdownTimeLimit

Opcjonalny atrybut liczby całkowitej.

Czas trwania w sekundach oczekiwania modułu na bezproblemowe zamknięcie pliku wykonywalnego po app_offline.htm wykryciu pliku.

 Domyślnie: 10
Min: 0
Max: 600
startupTimeLimit

Opcjonalny atrybut liczby całkowitej.

Czas trwania w sekundach oczekiwania modułu na uruchomienie procesu nasłuchiwania na porcie. Jeśli ten limit czasu zostanie przekroczony, moduł zabije ten proces.

W przypadku hostowania procesu: proces nie jest uruchamiany ponownie i nie używa rapidFailsPerMinute tego ustawienia.

Podczas hostowania procesu poza procesem: moduł próbuje ponownie uruchomić proces po odebraniu nowego żądania i kontynuuje próbę ponownego uruchomienia procesu na kolejnych żądaniach przychodzących, chyba że aplikacja nie rozpocznie się rapidFailsPerMinute liczbą razy w ostatniej rolce.

Wartość 0 (zero) nie jest uważana za nieskończony limit czasu.

 Domyślnie: 120
Min: 0
Max: 3600
stdoutLogEnabled

Opcjonalny atrybut logiczny.

Jeśli wartość true, stdout i stderr dla procesu określonego w pliku processPath są przekierowywane do pliku określonego w pliku stdoutLogFile.

false
stdoutLogFile

Opcjonalny atrybut ciągu.

Określa względną lub bezwzględną ścieżkę pliku, dla której stdout i stderr z procesu określonego w pliku processPath są rejestrowane. Ścieżki względne są względne względem katalogu głównego witryny. Każda ścieżka rozpoczynająca się od . elementu jest względna względem katalogu głównego witryny, a wszystkie inne ścieżki są traktowane jako ścieżki bezwzględne. Wszystkie foldery podane w ścieżce są tworzone przez moduł podczas tworzenia pliku dziennika. Przy użyciu ograniczników podkreślenia znacznik czasu, identyfikator procesu i rozszerzenie pliku (.log) są dodawane do ostatniego segmentu stdoutLogFile ścieżki. Jeśli .\logs\stdout zostanie podana jako wartość, przykładowy dziennik stdout zostanie zapisany jako stdout_20180205194132_1934.log w logs folderze zapisanym w dniu 2/5/2018 o 19:41:32 z identyfikatorem procesu 1934.

 aspnetcore-stdout

Ustawianie zmiennych środowiskowych

Zmienne środowiskowe można określić dla procesu w atrybucie processPath . Określ zmienną środowiskową z <environmentVariable> elementem podrzędnym <environmentVariables> elementu kolekcji. Zmienne środowiskowe ustawione w tej sekcji mają pierwszeństwo przed zmiennymi środowiskowymi systemu.

W poniższym przykładzie ustawiono dwie zmienne środowiskowe. ASPNETCORE_ENVIRONMENT Konfiguruje środowisko aplikacji na Development. Deweloper może tymczasowo ustawić tę wartość w pliku, web.config aby wymusić załadowanie strony wyjątku dewelopera podczas debugowania wyjątku aplikacji. CONFIG_DIR to przykład zmiennej środowiskowej zdefiniowanej przez użytkownika, w której deweloper napisał kod, który odczytuje wartość podczas uruchamiania, aby utworzyć ścieżkę ładowania pliku konfiguracji aplikacji.

<aspNetCore processPath="dotnet"
      arguments=".\MyApp.dll"
      stdoutLogEnabled="false"
      stdoutLogFile=".\logs\stdout"
      hostingModel="inprocess">
  <environmentVariables>
    <environmentVariable name="ASPNETCORE_ENVIRONMENT" value="Development" />
    <environmentVariable name="CONFIG_DIR" value="f:\application_config" />
  </environmentVariables>
</aspNetCore>

Uwaga

Alternatywą dla ustawienia środowiska bezpośrednio w programie web.config jest uwzględnienie <EnvironmentName> właściwości w profilu publikowania (pubxml) lub pliku projektu. To podejście ustawia środowisko w web.config momencie opublikowania projektu:

<PropertyGroup>
  <EnvironmentName>Development</EnvironmentName>
</PropertyGroup>

Ostrzeżenie

Ustaw zmienną ASPNETCORE_ENVIRONMENT środowiskową Development tylko na serwery przejściowe i testowe, które nie są dostępne dla niezaufanych sieci, takich jak Internet.

app_offline.htm

Jeśli plik o nazwie app_offline.htm zostanie wykryty w katalogu głównym aplikacji, moduł ASP.NET Core próbuje bezpiecznie zamknąć aplikację i zatrzymać przetwarzanie żądań przychodzących. Jeśli aplikacja jest nadal uruchomiona po liczbie sekund zdefiniowanych w programie shutdownTimeLimit, moduł ASP.NET Core zabija uruchomiony proces.

app_offline.htm Gdy plik jest obecny, moduł ASP.NET Core odpowiada na żądania, wysyłając z powrotem zawartość app_offline.htm pliku. Po usunięciu app_offline.htm pliku następne żądanie uruchamia aplikację.

W przypadku korzystania z modelu hostingu poza procesem aplikacja może nie zostać natychmiast zamknięta, jeśli istnieje otwarte połączenie. Na przykład połączenie protokołu websocket może opóźnić zamknięcie aplikacji.

Strona błędu uruchamiania

Zarówno w procesie, jak i poza procesem hostingu generują niestandardowe strony błędów, gdy nie można uruchomić aplikacji.

Jeśli moduł ASP.NET Core nie może odnaleźć procedury obsługi żądań w procesie lub poza procesem, zostanie wyświetlona strona kodowa stanu błędu ładowania 500.0 — In-Process/Out-Of-Process Handler.

W przypadku hostowania w procesie, jeśli nie można uruchomić aplikacji ASP.NET Core Module, zostanie wyświetlona strona kodowa stanu niepowodzenia 500.30.

W przypadku hostowania poza procesem, jeśli moduł ASP.NET Core nie może uruchomić procesu zaplecza lub proces zaplecza zostanie uruchomiony, ale nie można nasłuchiwać na skonfigurowanym porcie, zostanie wyświetlona strona kodowa stanu błędu procesu 502.5.

Aby pominąć tę stronę i przywrócić domyślną stronę kodu stanu usług IIS 5xx, użyj atrybutu disableStartUpErrorPage . Aby uzyskać więcej informacji na temat konfigurowania niestandardowych komunikatów o błędach, zobacz Http Errors httpErrors (Błędy <>HTTP).

Tworzenie i przekierowywanie dzienników

Moduł ASP.NET Core przekierowuje dane wyjściowe konsoli stdout i stderr do dysku, jeśli stdoutLogEnabled ustawiono atrybuty aspNetCore i stdoutLogFile elementu. Wszystkie foldery w ścieżce stdoutLogFile są tworzone przez moduł podczas tworzenia pliku dziennika. Pula aplikacji musi mieć dostęp do zapisu w lokalizacji, w której są zapisywane dzienniki (służy IIS AppPool\{APP POOL NAME} do udzielania uprawnień do zapisu, gdzie symbol zastępczy {APP POOL NAME} to nazwa puli aplikacji).

Dzienniki nie są obracane, chyba że nastąpi ponowne odtwarzanie/ponowne uruchomienie procesu. Jest to odpowiedzialność hosta za ograniczenie miejsca na dysku używanego przez dzienniki.

Korzystanie z dziennika stdout jest zalecane tylko w przypadku rozwiązywania problemów z uruchamianiem aplikacji podczas hostowania w usługach IIS lub korzystania z obsługi czasu programowania dla usług IIS w programie Visual Studio, a nie podczas debugowania lokalnie i uruchamiania aplikacji za pomocą usług IIS Express.

Nie używaj dziennika stdout do ogólnych celów rejestrowania aplikacji. W przypadku rutynowego rejestrowania w aplikacji ASP.NET Core użyj biblioteki rejestrowania, która ogranicza rozmiar pliku dziennika i obraca dzienniki. Aby uzyskać więcej informacji, zobacz dostawcy rejestrowania innych firm.

Znacznik czasu i rozszerzenie pliku są dodawane automatycznie po utworzeniu pliku dziennika. Nazwa pliku dziennika składa się z dołączania znacznika czasu, identyfikatora procesu i rozszerzenia pliku (.log) do ostatniego segmentu stdoutLogFile ścieżki (zazwyczaj stdout) rozdzielanego znakami podkreślenia. stdoutLogFile Jeśli ścieżka kończy się ciągiem stdout, dziennik aplikacji z identyfikatorem PID z 1934 r. utworzonym w dniu 2.5.2018 o godzinie 19:42:32 ma nazwę stdout_20180205194132_1934.logpliku .

Jeśli stdoutLogEnabled jest to fałsz, błędy występujące podczas uruchamiania aplikacji są przechwytywane i emitowane do dziennika zdarzeń do 30 KB. Po uruchomieniu wszystkie dodatkowe dzienniki zostaną odrzucone.

Poniższy przykładowy aspNetCore element konfiguruje rejestrowanie stdout w ścieżce .\log\względnej . Upewnij się, że użytkownik identity puli aplikacji ma uprawnienia do zapisu w podanej ścieżce.

<aspNetCore processPath="dotnet"
    arguments=".\MyApp.dll"
    stdoutLogEnabled="true"
    stdoutLogFile=".\logs\stdout"
    hostingModel="inprocess">
</aspNetCore>

Podczas publikowania aplikacji na potrzeby wdrożenia usługi aplikacja systemu Azure zestaw SDK sieci Web ustawia stdoutLogFile wartość na \\?\%home%\LogFiles\stdout. Zmienna %home środowiskowa jest wstępnie zdefiniowana dla aplikacji hostowanych przez usługę aplikacja systemu Azure.

Aby uzyskać więcej informacji na temat formatów ścieżek, zobacz Formaty ścieżek plików w systemach Windows.

Rozszerzone dzienniki diagnostyczne

Moduł ASP.NET Core można skonfigurować w celu zapewnienia rozszerzonych dzienników diagnostycznych. <handlerSettings> Dodaj element do elementu w pliku <aspNetCore> web.config. Ustawienie elementu debugLevel w celu TRACE uwidocznienia wyższej wierności informacji diagnostycznych:

<aspNetCore processPath="dotnet"
    arguments=".\MyApp.dll"
    stdoutLogEnabled="false"
    stdoutLogFile="\\?\%home%\LogFiles\stdout"
    hostingModel="inprocess">
  <handlerSettings>
    <handlerSetting name="debugFile" value=".\logs\aspnetcore-debug.log" />
    <handlerSetting name="debugLevel" value="FILE,TRACE" />
  </handlerSettings>
</aspNetCore>

Foldery w ścieżce podanej <handlerSetting> do wartości (logs w poprzednim przykładzie) nie są tworzone automatycznie przez moduł i powinny istnieć wstępnie we wdrożeniu. Pula aplikacji musi mieć dostęp do zapisu w lokalizacji, w której są zapisywane dzienniki (służy IIS AppPool\{APP POOL NAME} do udzielania uprawnień do zapisu, gdzie symbol zastępczy {APP POOL NAME} to nazwa puli aplikacji).

Wartości poziomu debugowania (debugLevel) mogą obejmować zarówno poziom, jak i lokalizację.

Poziomy (w kolejności od najmniejszej do najbardziej pełnej):

  • BŁĄD
  • OSTRZEŻENIE
  • INFO
  • TRACE

Lokalizacje (dozwolone są wiele lokalizacji):

  • CONSOLE
  • DZIENNIK ZDARZEŃ
  • PLIK

Ustawienia programu obsługi można również udostępnić za pomocą zmiennych środowiskowych:

  • ASPNETCORE_MODULE_DEBUG_FILE: ścieżka do pliku dziennika debugowania. (Ustawienie domyślne: aspnetcore-debug.log)
  • ASPNETCORE_MODULE_DEBUG: Ustawienie poziomu debugowania.

Ostrzeżenie

Nie należy pozostawiać rejestrowania debugowania włączonego we wdrożeniu dłużej niż jest to wymagane do rozwiązania problemu. Rozmiar dziennika nie jest ograniczony. Pozostawienie włączonego dziennika debugowania może wyczerpać dostępne miejsce na dysku i awarii serwera lub usługi app Service.

Zobacz Configuration with web.config (Konfiguracja za pomocą pliku web.config ), aby zapoznać się z przykładem aspNetCore elementu w web.config pliku.

Konfiguracja serwera proxy używa protokołu HTTP i tokenu parowania

Dotyczy tylko hostingu poza procesem.

Serwer proxy utworzony między modułem ASP.NET Core i Kestrel używa protokołu HTTP. Nie ma ryzyka podsłuchiwania ruchu między modułem a Kestrel lokalizacją poza serwerem.

Token parowania służy do zagwarantowania, że żądania odebrane przez Kestrel usługę IIS były proxied przez usługi IIS i nie pochodziły z innego źródła. Token parowania jest tworzony i ustawiany w zmiennej środowiskowej (ASPNETCORE_TOKEN) przez moduł. Token parowania jest również ustawiany na nagłówek (MS-ASPNETCORE-TOKEN) dla każdego żądania proxied. Oprogramowanie pośredniczące USŁUG IIS sprawdza każde odebrane żądanie, aby potwierdzić, że wartość nagłówka tokenu parowania jest zgodna z wartością zmiennej środowiskowej. Jeśli wartości tokenu są niezgodne, żądanie jest rejestrowane i odrzucane. Zmienna środowiskowa tokenu parowania i ruch między modułem i Kestrel nie są dostępne z lokalizacji poza serwerem. Bez znajomości wartości tokenu parowania cyberatak nie może przesyłać żądań, które pomijają ewidencjonowanie oprogramowania pośredniczącego usług IIS.

ASP.NET Core Module z konfiguracją udostępnioną usług IIS

Instalator ASP.NET Core Module jest uruchamiany z uprawnieniami TrustedInstaller konta. Ponieważ lokalne konto systemowe nie ma uprawnień do modyfikowania ścieżki udziału używanej przez konfigurację udostępnioną usług IIS, instalator zgłasza błąd odmowy dostępu podczas próby skonfigurowania ustawień modułu w pliku w applicationHost.config udziale.

W przypadku korzystania z konfiguracji udostępnionej usług IIS na tej samej maszynie co instalacja usług IIS uruchom instalator pakietu hostingu podstawowego ASP.NET z parametrem ustawionym OPT_NO_SHARED_CONFIG_CHECK na 1:

dotnet-hosting-{VERSION}.exe OPT_NO_SHARED_CONFIG_CHECK=1

Jeśli ścieżka do konfiguracji udostępnionej nie znajduje się na tej samej maszynie co instalacja usług IIS, wykonaj następujące kroki:

  1. Wyłącz konfigurację udostępnioną usług IIS.
  2. Uruchom instalatora.
  3. Wyeksportuj zaktualizowany applicationHost.config plik do udziału.
  4. Ponownie włącz konfigurację udostępnioną usług IIS.

Dzienniki instalatora wersji modułu i pakietu hostingu

Aby określić wersję zainstalowanego modułu ASP.NET Core:

  1. W systemie hostingu przejdź do %windir%\System32\inetsrvadresu .
  2. aspnetcore.dll Znajdź plik.
  3. Kliknij plik prawym przyciskiem myszy i wybierz polecenie Właściwości z menu kontekstowego.
  4. Wybierz kartę Szczegóły. Wersja pliku i wersja produktu reprezentują zainstalowaną wersję modułu.

Dzienniki instalatora pakietu hostingu dla modułu znajdują się pod adresem C:\\Users\\%UserName%\\AppData\\Local\\Temp. Plik ma nazwę dd_DotNetCoreWinSvrHosting__\{TIMESTAMP}_000_AspNetCoreModule_x64.log, gdzie symbol zastępczy {TIMESTAMP} to sygnatura czasowa.

Lokalizacje plików modułu, schematu i konfiguracji

Moduł

IIS (x86/amd64):

  • %windir%\System32\inetsrv\aspnetcore.dll

  • %windir%\SysWOW64\inetsrv\aspnetcore.dll

  • %ProgramFiles%\IIS\Asp.Net Core Module\V2\aspnetcorev2.dll

  • %ProgramFiles(x86)%\IIS\Asp.Net Core Module\V2\aspnetcorev2.dll

IIS Express (x86/amd64):

  • %ProgramFiles%\IIS Express\aspnetcore.dll

  • %ProgramFiles(x86)%\IIS Express\aspnetcore.dll

  • %ProgramFiles%\IIS Express\Asp.Net Core Module\V2\aspnetcorev2.dll

  • %ProgramFiles(x86)%\IIS Express\Asp.Net Core Module\V2\aspnetcorev2.dll

Schemat

IIS

  • %windir%\System32\inetsrv\config\schema\aspnetcore_schema.xml

  • %windir%\System32\inetsrv\config\schema\aspnetcore_schema_v2.xml

IIS Express

  • %ProgramFiles%\IIS Express\config\schema\aspnetcore_schema.xml

  • %ProgramFiles%\IIS Express\config\schema\aspnetcore_schema_v2.xml

Konfigurowanie

IIS

  • %windir%\System32\inetsrv\config\applicationHost.config

IIS Express

  • Visual Studio: {APPLICATION ROOT}\.vs\config\applicationHost.config

  • interfejs wiersza polecenia iisexpress.exe:%USERPROFILE%\Documents\IISExpress\config\applicationhost.config

Pliki można znaleźć, wyszukując aspnetcore applicationHost.config w pliku.

Moduł ASP.NET Core Module (ANCM) to natywny moduł usług IIS, który podłącza potok usług IIS do przekazywania żądań internetowych do zaplecza ASP.NET Core aplikacji.

Obsługiwane wersje systemu Windows:

  • Windows 7 lub nowszy
  • Windows Server 2008 R2 lub nowszy

Moduł działa tylko z elementem Kestrel. Moduł jest niezgodny z HTTP.sys.

Ponieważ aplikacje ASP.NET Core działają w procesie oddzielnym od procesu roboczego usług IIS, moduł obsługuje również zarządzanie procesami. Moduł uruchamia proces aplikacji ASP.NET Core po odebraniu pierwszego żądania i ponownym uruchomieniu aplikacji w przypadku awarii. Jest to zasadniczo takie samo zachowanie jak w przypadku aplikacji ASP.NET 4.x uruchamianych w procesie w usługach IIS zarządzanych przez usługę aktywacji procesów systemu Windows (WAS).

Na poniższym diagramie przedstawiono relację między usługami IIS, modułem ASP.NET Core i aplikacją:

Moduł ASP.NET Core

Żądania z Internetu docierają do sterownika HTTP.sys trybu jądra. Sterownik kieruje te żądania do usług IIS na skonfigurowanym porcie witryny internetowej, zazwyczaj 80 (HTTP) lub 443 (HTTPS). Moduł przekazuje żądania do serwera Kestrel na losowym porcie dla aplikacji, który nie jest portem 80 ani 443.

Moduł określa port za pośrednictwem zmiennej środowiskowej podczas uruchamiania, a oprogramowanie pośredniczące integracji usług IIS konfiguruje serwer do nasłuchiwania na porcie http://localhost:{port}. Wykonywane są dodatkowe kontrole, a żądania, które nie pochodzą z modułu, są odrzucane. Moduł nie obsługuje przekazywania HTTPS, dlatego żądania są przekazywane za pośrednictwem protokołu HTTP, nawet jeśli zostały odebrane przez usługi IIS za pośrednictwem protokołu HTTPS.

Żądanie z modułu odebrane przez serwer Kestrel jest wypychane do potoku oprogramowania pośredniczącego ASP.NET Core. Potok oprogramowania pośredniczącego obsługuje żądanie i przekazuje je jako wystąpienie obiektu HttpContext do logiki aplikacji. Oprogramowanie pośredniczące dodane przez integrację z usługami IIS aktualizuje schemat, zdalny adres IP i bazę ścieżek, aby uwzględnić przekazanie żądania do serwera Kestrel. Odpowiedź aplikacji jest przekazywana z powrotem do usług IIS, które wypychają ją z powrotem do klienta HTTP, który zainicjował żądanie.

Wiele modułów natywnych, takich jak uwierzytelnianie systemu Windows, pozostaje aktywnych. Aby dowiedzieć się więcej o modułach usług IIS aktywnych przy użyciu modułu podstawowego ASP.NET, zobacz Moduły usług IIS z ASP.NET Core.

Moduł ASP.NET Core może również wykonywać następujące czynności:

  • Ustaw zmienne środowiskowe dla procesu roboczego.
  • Rejestrowanie danych wyjściowych stdout w magazynie plików w celu rozwiązywania problemów z uruchamianiem.
  • Przekazywanie tokenów uwierzytelniania systemu Windows.

Jak zainstalować moduł ASP.NET Core Module (ANCM) i korzystać z niego

Aby uzyskać instrukcje dotyczące sposobu instalowania modułu ASP.NET Core, zobacz Instalowanie pakietu hostingu platformy .NET Core.

Konfiguracja za pomocą pliku web.config

Moduł ASP.NET Core jest skonfigurowany z sekcją aspNetCore system.webServer węzła w pliku web.config witryny.

Następujący plik web.config jest publikowany na potrzeby wdrożenia zależnego od platformy i konfiguruje moduł ASP.NET Core do obsługi żądań lokacji:

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <system.webServer>
    <handlers>
      <add name="aspNetCore" path="*" verb="*" modules="AspNetCoreModule" resourceType="Unspecified" />
    </handlers>
    <aspNetCore processPath="dotnet"
                arguments=".\MyApp.dll"
                stdoutLogEnabled="false"
                stdoutLogFile=".\logs\stdout" />
  </system.webServer>
</configuration>

Następująca konfiguracja web.config jest opublikowana dla samodzielnego wdrożenia:

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <system.webServer>
    <handlers>
      <add name="aspNetCore" path="*" verb="*" modules="AspNetCoreModule" resourceType="Unspecified" />
    </handlers>
    <aspNetCore processPath=".\MyApp.exe"
                stdoutLogEnabled="false"
                stdoutLogFile=".\logs\stdout" />
  </system.webServer>
</configuration>

Po wdrożeniu aplikacji w usłudze aplikacja systemu Azure ścieżka jest ustawiona stdoutLogFile na \\?\%home%\LogFiles\stdout. Ścieżka zapisuje dzienniki stdout w folderze LogFiles , który jest lokalizacją automatycznie utworzoną przez usługę.

Aby uzyskać informacje na temat konfiguracji podrzędnej aplikacji usług IIS, zobacz Host ASP.NET Core w systemie Windows z usługami IIS.

Atrybuty elementu aspNetCore

Atrybut opis Wartość domyślna
arguments

Opcjonalny atrybut ciągu.

Argumenty pliku wykonywalnego określonego w processPath.
disableStartUpErrorPage

Opcjonalny atrybut logiczny.

Jeśli wartość true, strona 502.5 — Niepowodzenie procesu jest pomijana, a strona kodowa stanu 502 skonfigurowana w pliku web.config ma pierwszeństwo.

 false
forwardWindowsAuthToken

Opcjonalny atrybut logiczny.

Jeśli to prawda, token jest przekazywany do procesu podrzędnego nasłuchiwania w %ASPNETCORE_PORT% jako nagłówek "MS-ASPNETCORE-WINAUTHTOKEN" na żądanie. Jest to odpowiedzialność za wywołanie metody CloseHandle na tym tokenie na żądanie.

 true
processesPerApplication

Opcjonalny atrybut liczby całkowitej.

Określa liczbę wystąpień procesu określonego w ustawieniu processPath , które można połączyć na aplikację.

Ustawienie processesPerApplication jest odradzane. Ten atrybut zostanie usunięty w przyszłej wersji.

 Domyślnie: 1
Min: 1
Max: 100
processPath

Wymagany atrybut ciągu.

Ścieżka do pliku wykonywalnego, który uruchamia proces nasłuchiwania żądań HTTP. Ścieżki względne są obsługiwane. Jeśli ścieżka zaczyna się od ., ścieżka jest uważana za względną względem katalogu głównego witryny.
rapidFailsPerMinute

Opcjonalny atrybut liczby całkowitej.

Określa liczbę przypadków awarii procesu określonego w programie processPath na minutę. Jeśli ten limit zostanie przekroczony, moduł przestanie uruchamiać proces w pozostałej części minuty.

 Domyślnie: 10
Min: 0
Max: 100
requestTimeout

Opcjonalny atrybut przedziału czasu.

Określa czas trwania, przez który moduł ASP.NET Core czeka na odpowiedź z procesu nasłuchiwania na %ASPNETCORE_PORT%.

W wersjach modułu ASP.NET Core dostarczanego z wydaniem ASP.NET Core 2.1 lub nowszym requestTimeout parametr jest określony w godzinach, minutach i sekundach.

 Domyślnie: 00:02:00
Min: 00:00:00
Max: 360:00:00
shutdownTimeLimit

Opcjonalny atrybut liczby całkowitej.

Czas trwania w sekundach oczekiwania modułu na bezproblemowe zamknięcie pliku wykonywalnego po app_offline.htm wykryciu pliku.

 Domyślnie: 10
Min: 0
Max: 600
startupTimeLimit

Opcjonalny atrybut liczby całkowitej.

Czas trwania w sekundach oczekiwania modułu na uruchomienie procesu nasłuchiwania na porcie. Jeśli ten limit czasu zostanie przekroczony, moduł zabije ten proces. Moduł próbuje ponownie uruchomić proces po odebraniu nowego żądania i kontynuuje próbę ponownego uruchomienia procesu na kolejnych żądaniach przychodzących, chyba że aplikacja nie może uruchomić funkcji rapidFailsPerMinute w ostatniej chwili.

Wartość 0 (zero) nie jest uważana za nieskończony limit czasu.

 Domyślnie: 120
Min: 0
Max: 3600
stdoutLogEnabled

Opcjonalny atrybut logiczny.

Jeśli wartość true, stdout i stderr dla procesu określonego w processPath są przekierowywane do pliku określonego w pliku stdoutLogFile.

false
stdoutLogFile

Opcjonalny atrybut ciągu.

Określa względną lub bezwzględną ścieżkę pliku, dla której są rejestrowane ścieżki stdout i stderr z procesu określonego w processPath . Ścieżki względne są względne względem katalogu głównego witryny. Każda ścieżka rozpoczynająca się od . elementu jest względna względem katalogu głównego witryny, a wszystkie inne ścieżki są traktowane jako ścieżki bezwzględne. Wszystkie foldery podane w ścieżce muszą istnieć, aby moduł utworzył plik dziennika. Przy użyciu ograniczników podkreślenia znacznik czasu, identyfikator procesu i rozszerzenie pliku (.log) są dodawane do ostatniego segmentu ścieżki stdoutLogFile . Jeśli .\logs\stdout zostanie podana jako wartość, przykładowy dziennik stdout zostanie zapisany jako stdout_20180205194132_1934.log w folderze logs po zapisaniu w dniu 2/5/2018 o 19:41:32 z identyfikatorem procesu 1934.

 aspnetcore-stdout

Ustawianie zmiennych środowiskowych

Zmienne środowiskowe można określić dla procesu w atrybucie processPath . Określ zmienną środowiskową z <environmentVariable> elementem podrzędnym <environmentVariables> elementu kolekcji.

Ostrzeżenie

Zmienne środowiskowe ustawione w tej sekcji powodują konflikt ze zmiennymi środowiskowymi systemu ustawionymi o tej samej nazwie. Jeśli zmienna środowiskowa jest ustawiana zarówno w pliku web.config , jak i na poziomie systemu w systemie Windows, wartość z pliku web.config zostanie dołączona do wartości zmiennej środowiskowej systemu (na przykład ASPNETCORE_ENVIRONMENT: Development;Development), co uniemożliwia uruchamianie aplikacji.

W poniższym przykładzie ustawiono dwie zmienne środowiskowe. ASPNETCORE_ENVIRONMENT Konfiguruje środowisko aplikacji na Development. Deweloper może tymczasowo ustawić tę wartość w pliku web.config , aby wymusić załadowanie strony wyjątku dewelopera podczas debugowania wyjątku aplikacji. CONFIG_DIR to przykład zmiennej środowiskowej zdefiniowanej przez użytkownika, w której deweloper napisał kod, który odczytuje wartość podczas uruchamiania, aby utworzyć ścieżkę ładowania pliku konfiguracji aplikacji.

<aspNetCore processPath="dotnet"
      arguments=".\MyApp.dll"
      stdoutLogEnabled="false"
      stdoutLogFile="\\?\%home%\LogFiles\stdout">
  <environmentVariables>
    <environmentVariable name="ASPNETCORE_ENVIRONMENT" value="Development" />
    <environmentVariable name="CONFIG_DIR" value="f:\application_config" />
  </environmentVariables>
</aspNetCore>

Ostrzeżenie

Ustaw zmienną ASPNETCORE_ENVIRONMENT środowiskową Development tylko na serwery przejściowe i testowe, które nie są dostępne dla niezaufanych sieci, takich jak Internet.

app_offline.htm

Jeśli plik o nazwie app_offline.htm zostanie wykryty w katalogu głównym aplikacji, moduł ASP.NET Core próbuje bezpiecznie zamknąć aplikację i zatrzymać przetwarzanie żądań przychodzących. Jeśli aplikacja jest nadal uruchomiona po liczbie sekund zdefiniowanych w programie shutdownTimeLimit, moduł ASP.NET Core zabija uruchomiony proces.

app_offline.htm Gdy plik jest obecny, moduł ASP.NET Core odpowiada na żądania, wysyłając z powrotem zawartość app_offline.htm pliku. Po usunięciu app_offline.htm pliku następne żądanie uruchamia aplikację.

Strona błędu uruchamiania

Jeśli moduł ASP.NET Core nie może uruchomić procesu zaplecza lub proces zaplecza zostanie uruchomiony, ale nie nasłuchuje na skonfigurowanym porcie, zostanie wyświetlona strona kodowa stanu błędu procesu 502.5. Aby pominąć tę stronę i przywrócić domyślną stronę kodów stanu usług IIS 502, użyj atrybutu disableStartUpErrorPage . Aby uzyskać więcej informacji na temat konfigurowania niestandardowych komunikatów o błędach, zobacz Http Errors httpErrors (Błędy <>HTTP).

Tworzenie i przekierowywanie dzienników

Moduł ASP.NET Core przekierowuje dane wyjściowe konsoli stdout i stderr do dysku, jeśli stdoutLogEnabled ustawiono atrybuty aspNetCore i stdoutLogFile elementu. Wszystkie foldery w ścieżce stdoutLogFile są tworzone przez moduł podczas tworzenia pliku dziennika. Pula aplikacji musi mieć dostęp do zapisu w lokalizacji, w której są zapisywane dzienniki (użyj IIS AppPool\<app_pool_name> polecenia w celu udzielenia uprawnień do zapisu).

Dzienniki nie są obracane, chyba że nastąpi ponowne odtwarzanie/ponowne uruchomienie procesu. Jest to odpowiedzialność hosta za ograniczenie miejsca na dysku używanego przez dzienniki.

Korzystanie z dziennika stdout jest zalecane tylko w przypadku rozwiązywania problemów z uruchamianiem aplikacji podczas hostowania w usługach IIS lub korzystania z obsługi czasu programowania dla usług IIS w programie Visual Studio, a nie podczas debugowania lokalnie i uruchamiania aplikacji za pomocą usług IIS Express.

Nie używaj dziennika stdout do ogólnych celów rejestrowania aplikacji. W przypadku rutynowego rejestrowania w aplikacji ASP.NET Core użyj biblioteki rejestrowania, która ogranicza rozmiar pliku dziennika i obraca dzienniki. Aby uzyskać więcej informacji, zobacz dostawcy rejestrowania innych firm.

Znacznik czasu i rozszerzenie pliku są dodawane automatycznie po utworzeniu pliku dziennika. Nazwa pliku dziennika składa się z dołączania znacznika czasu, identyfikatora procesu i rozszerzenia pliku (.log) do ostatniego segmentu stdoutLogFile ścieżki (zazwyczaj stdout) rozdzielanej znakami podkreślenia. stdoutLogFile Jeśli ścieżka kończy się ciągiem stdout, dziennik aplikacji z identyfikatorem PID z 1934 r. utworzonym w dniu 2.5.2018 o godzinie 19:42:32 ma nazwę pliku stdout_20180205194132_1934.log.

Poniższy przykładowy aspNetCore element konfiguruje rejestrowanie stdout w ścieżce .\log\względnej . Upewnij się, że użytkownik identity puli aplikacji ma uprawnienia do zapisu w podanej ścieżce.

<aspNetCore processPath="dotnet"
    arguments=".\MyApp.dll"
    stdoutLogEnabled="true"
    stdoutLogFile=".\logs\stdout">
</aspNetCore>

Podczas publikowania aplikacji na potrzeby wdrożenia usługi aplikacja systemu Azure zestaw SDK sieci Web ustawia stdoutLogFile wartość na \\?\%home%\LogFiles\stdout. Zmienna %home środowiskowa jest wstępnie zdefiniowana dla aplikacji hostowanych przez usługę aplikacja systemu Azure.

Aby utworzyć reguły filtru rejestrowania, zobacz sekcję Stosowanie reguł filtru dziennika w kodzie dokumentacji rejestrowania ASP.NET Core.

Aby uzyskać więcej informacji na temat formatów ścieżek, zobacz Formaty ścieżek plików w systemach Windows.

Konfiguracja serwera proxy używa protokołu HTTP i tokenu parowania

Serwer proxy utworzony między modułem ASP.NET Core i Kestrel używa protokołu HTTP. Nie ma ryzyka podsłuchiwania ruchu między modułem a Kestrel lokalizacją poza serwerem.

Token parowania służy do zagwarantowania, że żądania odebrane przez Kestrel usługę IIS były proxied przez usługi IIS i nie pochodziły z innego źródła. Token parowania jest tworzony i ustawiany w zmiennej środowiskowej (ASPNETCORE_TOKEN) przez moduł. Token parowania jest również ustawiany na nagłówek (MS-ASPNETCORE-TOKEN) dla każdego żądania proxied. Oprogramowanie pośredniczące USŁUG IIS sprawdza każde odebrane żądanie, aby potwierdzić, że wartość nagłówka tokenu parowania jest zgodna z wartością zmiennej środowiskowej. Jeśli wartości tokenu są niezgodne, żądanie jest rejestrowane i odrzucane. Zmienna środowiskowa tokenu parowania i ruch między modułem i Kestrel nie są dostępne z lokalizacji poza serwerem. Bez znajomości wartości tokenu parowania cyberatak nie może przesyłać żądań, które pomijają ewidencjonowanie oprogramowania pośredniczącego usług IIS.

ASP.NET Core Module z konfiguracją udostępnioną usług IIS

Instalator modułu ASP.NET Core jest uruchamiany z uprawnieniami konta TrustedInstaller . Ponieważ lokalne konto systemowe nie ma uprawnień do modyfikowania ścieżki udziału używanej przez konfigurację udostępnioną usług IIS, instalator zgłasza błąd odmowy dostępu podczas próby skonfigurowania ustawień modułu w pliku applicationHost.config w udziale.

W przypadku korzystania z konfiguracji udostępnionej usług IIS wykonaj następujące kroki:

  1. Wyłącz konfigurację udostępnioną usług IIS.
  2. Uruchom instalatora.
  3. Wyeksportuj zaktualizowany plik applicationHost.config do udziału.
  4. Ponownie włącz konfigurację udostępnioną usług IIS.

Dzienniki instalatora wersji modułu i pakietu hostingu

Aby określić wersję zainstalowanego modułu ASP.NET Core:

  1. W systemie hostingu przejdź do folderu %windir%\System32\inetsrv.
  2. Znajdź plik aspnetcore.dll.
  3. Kliknij plik prawym przyciskiem myszy i wybierz polecenie Właściwości z menu kontekstowego.
  4. Wybierz kartę Szczegóły. Wersja pliku i wersja produktu reprezentują zainstalowaną wersję modułu.

Dzienniki instalatora pakietu hostingu dla modułu znajdują się w folderze C:\Users\%UserName%\AppData\Local\Temp. Plik ma nazwę dd_DotNetCoreWinSvrHosting__<timestamp>_000_AspNetCoreModule_x64.log.

Lokalizacje plików modułu, schematu i konfiguracji

Moduł

IIS (x86/amd64):

  • %windir%\System32\inetsrv\aspnetcore.dll

  • %windir%\SysWOW64\inetsrv\aspnetcore.dll

IIS Express (x86/amd64):

  • %ProgramFiles%\IIS Express\aspnetcore.dll

  • %ProgramFiles(x86)%\IIS Express\aspnetcore.dll

Schemat

IIS

  • %windir%\System32\inetsrv\config\schema\aspnetcore_schema.xml

IIS Express

  • %ProgramFiles%\IIS Express\config\schema\aspnetcore_schema.xml

Konfigurowanie

IIS

  • %windir%\System32\inetsrv\config\applicationHost.config

IIS Express

  • Visual Studio: {APPLICATION ROOT}\.vs\config\applicationHost.config

  • interfejs wiersza polecenia iisexpress.exe: %USERPROFILE%\Documents\IISExpress\config\applicationhost.config

Pliki można znaleźć, wyszukując plik aspnetcore w pliku applicationHost.config .

Dodatkowe zasoby