Plik web.config

  • Artykuł

Jest web.config to plik odczytywany przez usługi IIS i moduł ASP.NET Core w celu skonfigurowania aplikacji hostowanej za pomocą usług IIS.

Lokalizacja pliku web.config

Aby poprawnie skonfigurować moduł ASP.NET Core Module, plik web.config musi znajdować się w ścieżce głównej zawartości (zazwyczaj to ścieżka podstawowa aplikacji) wdrożonej aplikacji. Jest to ta sama lokalizacja, co ścieżka fizyczna witryny internetowej dostarczona do usług IIS. Plik web.config jest wymagany w katalogu głównym aplikacji, aby umożliwić publikowanie wielu aplikacji przy użyciu narzędzia Web Deploy.

Poufne pliki istnieją na ścieżce fizycznej aplikacji, na przykład {ASSEMBLY}.runtimeconfig.json, {ASSEMBLY}.xml (komentarze dokumentacji XML) i {ASSEMBLY}.deps.json, gdzie symbol zastępczy {ASSEMBLY} jest nazwą zestawu. Gdy plik web.config występuje i witryna jest uruchamiana normalnie, usługi IIS nie obsługują tych poufnych plików, jeśli są one żądane. Jeśli brakuje pliku web.config, został on niepoprawnie nazwany, lub nie można skonfigurować lokacji na potrzeby normalnego uruchamiania, usługi IIS mogą publicznie obsługiwać poufne pliki.

Plik web.config musi występować we wdrożeniu przez cały czas, poprawnie nazwany, i w stanie skonfigurować lokację pod kątem normalnego uruchamiania. Nigdy nie usuwaj pliku web.config z wdrożenia produkcyjnego.

Jeśli plik web.config nie występuje w projekcie, zostanie on utworzony z poprawną wartością processPath i arguments w celu skonfigurowania modułu ASP.NET Core Module i przeniesiony do opublikowanych danych wyjściowych.

Jeśli plik web.config występuje w projekcie, zostanie on przekształcony przy użyciu poprawnego processPath i arguments w celu skonfigurowania modułu ASP.NET Core Module i przeniesiony do opublikowanych danych wyjściowych. Przekształcenie nie modyfikuje ustawień konfiguracji usług IIS w pliku.

Plik web.config może zawierać dodatkowe ustawienia konfiguracji usług IIS kontrolujące aktywne moduły usług IIS. Aby uzyskać informacje na temat modułów usług IIS, które mogą przetwarzać żądania za pomocą aplikacji ASP.NET Core, zobacz temat Moduły usług IIS.

Tworzenie, przekształcanie i publikowanie pliku web.config jest obsługiwane przez obiekt docelowy MSBuild (_TransformWebConfig) po opublikowaniu projektu. Ten element docelowy znajduje się w elementach docelowych zestawu Web SDK (Microsoft.NET.Sdk.Web). Zestaw SDK jest ustawiany w górnej części pliku projektu:

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

Aby uniemożliwić przekształcanie pliku web.config za pomocą internetowego zestawu SDK, użyj właściwości <IsTransformWebConfigDisabled> w pliku projektu:

<PropertyGroup>
  <IsTransformWebConfigDisabled>true</IsTransformWebConfigDisabled>
</PropertyGroup>

Podczas wyłączania w internetowym zestawie SDK możliwości przekształcania pliku element processPath i arguments powinien zostać ręcznie ustawiony przez dewelopera. Aby uzyskać więcej informacji, zobacz Moduł ASP.NET Core Module (ANCM) dla usług IIS.

Konfiguracja modułu podstawowego ASP.NET za pomocą polecenia web.config

Moduł ASP.NET Core jest skonfigurowany z sekcją aspNetCoresystem.webServer węzła w pliku lokacji web.config .

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>

W przypadku wdrożenia samodzielnego opublikowano następujące web.config elementy:

<?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 Konfiguracja zaawansowana.

aspNetCore Atrybuty elementu

Atrybut opis 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 elemencie web.config ma pierwszeństwo.

 false
forwardWindowsAuthToken

Opcjonalny atrybut logiczny.

Jeśli to prawda, token jest przekazywany do procesu podrzędnego nasłuchiwania %ASPNETCORE_PORT% w nagłówku "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 gdy nie jest obecny
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. 60 Użycie wartości 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 a stderr dla procesu określonego w elemecie 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 5 lutego 2018 r. o godzinie 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.

Konfiguracja usług IIS za pomocą polecenia web.config

Na konfigurację usług IIS wpływa <system.webServer> sekcja scenariuszy web.config usług IIS, które działają dla aplikacji ASP.NET Core z modułem ASP.NET Core. Na przykład konfiguracja usług IIS jest funkcjonalna dla kompresji dynamicznej. Jeśli usługi IIS są skonfigurowane na poziomie serwera do korzystania z kompresji dynamicznej, <urlCompression> element w pliku aplikacji web.config może wyłączyć go dla aplikacji ASP.NET Core.

Aby uzyskać więcej informacji, zobacz następujące tematy:

Aby ustawić zmienne środowiskowe dla poszczególnych aplikacji działających w izolowanych pulach aplikacji (obsługiwanych dla usług IIS 10.0 lub nowszych), zobacz AppCmd.exe sekcję poleceń w temacie Zmienne <environmentVariables> środowiskowe w dokumentacji referencyjnej usług IIS.

Sekcje konfiguracji web.config

Sekcje konfiguracji aplikacji ASP.NET 4.x w programie web.config nie są używane przez aplikacje ASP.NET Core do konfiguracji:

  • <system.web>
  • <appSettings>
  • <connectionStrings>
  • <location>

Aplikacje ASP.NET Core są konfigurowane przy użyciu innych dostawców konfiguracji. Aby uzyskać więcej informacji, zobacz Konfiguracja.

Przekształcanie pliku web.config

Jeśli musisz przekształcić web.config podczas publikowania, zobacz Przekształcanie web.config. Może być konieczne przekształcenie web.config podczas publikowania w celu ustawienia zmiennych środowiskowych na podstawie konfiguracji, profilu lub środowiska.

Dodatkowe zasoby