File web.config

File web.config là file được IIS và ASP.NET Core Module đọc để cấu hình ứng dụng được host với IIS.

Vị trí file `web.config`

Để thiết lập ASP.NET Core Module đúng cách, file web.config phải có mặt tại đường dẫn content root (thường là đường dẫn gốc của ứng dụng) của ứng dụng đã triển khai. Đây là vị trí tương tự như đường dẫn vật lý của website được cung cấp cho IIS. File web.config cần có ở thư mục gốc của ứng dụng để cho phép publish nhiều ứng dụng bằng Web Deploy.

Các file nhạy cảm tồn tại trên đường dẫn vật lý của ứng dụng, chẳng hạn như {ASSEMBLY}.runtimeconfig.json, {ASSEMBLY}.xml (chú thích XML Documentation), và {ASSEMBLY}.deps.json. Khi file web.config có mặt và site khởi động bình thường, IIS sẽ không phục vụ các file nhạy cảm này nếu chúng được yêu cầu. Nếu file web.config bị thiếu, đặt tên không đúng, hoặc không thể cấu hình site để khởi động bình thường, IIS có thể phục vụ các file nhạy cảm một cách công khai.

File web.config phải luôn có mặt trong deployment, được đặt tên đúng, và có khả năng cấu hình site để khởi động bình thường. Không bao giờ xóa file web.config khỏi một deployment production.

Nếu file web.config không có trong project, file sẽ được tạo với processPath và arguments đúng để cấu hình ASP.NET Core Module và chuyển đến published output.

Nếu file web.config có trong project, file sẽ được chuyển đổi với processPath và arguments đúng để cấu hình ASP.NET Core Module và chuyển đến published output. Quá trình chuyển đổi không thay đổi các cài đặt cấu hình IIS trong file.

File web.config có thể cung cấp thêm các cài đặt cấu hình IIS để kiểm soát các IIS module đang hoạt động. Để biết thông tin về các IIS module có khả năng xử lý yêu cầu với các ứng dụng ASP.NET Core, xem bài viết IIS modules.

MSBuild target (_TransformWebConfig) xử lý việc tạo, chuyển đổi, và publish file web.config khi project được publish. Target này có trong Web SDK targets (Microsoft.NET.Sdk.Web). SDK được đặt ở đầu project file:

xml

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

Để ngăn Web SDK chuyển đổi file web.config, dùng thuộc tính <IsTransformWebConfigDisabled> trong project file:

xml

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

Khi vô hiệu hóa Web SDK khỏi việc chuyển đổi file, developer nên đặt thủ công processPath và arguments. Để biết thêm thông tin, xem ASP.NET Core Module (ANCM) for IIS.

Cấu hình ASP.NET Core Module với `web.config`

ASP.NET Core Module được cấu hình với phần aspNetCore của node system.webServer trong file web.config của site.

File web.config sau được publish cho một framework-dependent deployment và cấu hình ASP.NET Core Module để xử lý các yêu cầu site:

xml

<?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>

File web.config sau được publish cho một self-contained deployment:

xml

<?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>

Thuộc tính InheritInChildApplications được đặt thành false để chỉ ra rằng các cài đặt được chỉ định trong phần tử <location> không được kế thừa bởi các ứng dụng nằm trong thư mục con của ứng dụng.

Khi ứng dụng được triển khai lên Azure App Service, đường dẫn stdoutLogFile được đặt thành \\?\%home%\LogFiles\stdout. Đường dẫn lưu log stdout vào thư mục LogFiles, đây là vị trí được dịch vụ tự động tạo.

Để biết thông tin về cấu hình sub-application của IIS, xem Advanced configuration.

Các thuộc tính của phần tử `aspNetCore`

Thuộc tính	Mô tả	Mặc định
`arguments`	Thuộc tính string tùy chọn. Các đối số cho tệp thực thi được chỉ định trong `processPath`.
`disableStartUpErrorPage`	Thuộc tính Boolean tùy chọn. Nếu true, trang 502.5 - Process Failure bị ẩn và trang mã trạng thái 502 được cấu hình trong `web.config` sẽ ưu tiên.	`false`
`forwardWindowsAuthToken`	Thuộc tính Boolean tùy chọn. Nếu true, token được chuyển tiếp đến tiến trình con đang lắng nghe trên `%ASPNETCORE_PORT%` dưới dạng header 'MS-ASPNETCORE-WINAUTHTOKEN' cho mỗi yêu cầu.	`true`
`hostingModel`	Thuộc tính string tùy chọn. Chỉ định mô hình hosting là in-process (`InProcess`/`inprocess`) hoặc out-of-process (`OutOfProcess`/`outofprocess`).	`OutOfProcess`/`outofprocess` khi không có
`processesPerApplication`	Thuộc tính integer tùy chọn. Chỉ định số lượng instance của tiến trình được chỉ định trong `processPath` có thể được khởi động cho mỗi ứng dụng.	Default: `1`, Min: `1`, Max: `100`
`processPath`	Thuộc tính string bắt buộc. Đường dẫn đến tệp thực thi khởi chạy tiến trình lắng nghe các yêu cầu HTTP.
`rapidFailsPerMinute`	Thuộc tính integer tùy chọn. Chỉ định số lần tiến trình được chỉ định trong `processPath` được phép crash mỗi phút.	Default: `10`, Min: `0`, Max: `100`
`requestTimeout`	Thuộc tính timespan tùy chọn. Chỉ định thời gian ASP.NET Core Module chờ phản hồi từ tiến trình lắng nghe trên `%ASPNETCORE_PORT%`.	Default: `00:02:00`, Min: `00:00:00`, Max: `360:00:00`
`shutdownTimeLimit`	Thuộc tính integer tùy chọn. Thời gian tính bằng giây module chờ tệp thực thi tắt gracefully khi phát hiện file `app_offline.htm`.	Default: `10`, Min: `0`, Max: `600`
`startupTimeLimit`	Thuộc tính integer tùy chọn. Thời gian tính bằng giây module chờ tệp thực thi khởi động tiến trình lắng nghe trên cổng.	Default: `120`, Min: `0`, Max: `3600`
`stdoutLogEnabled`	Thuộc tính Boolean tùy chọn. Nếu true, `stdout` và `stderr` cho tiến trình được chỉ định trong `processPath` được chuyển hướng đến file được chỉ định trong `stdoutLogFile`.	`false`
`stdoutLogFile`	Thuộc tính string tùy chọn. Chỉ định đường dẫn file tương đối hoặc tuyệt đối để ghi `stdout` và `stderr`.	`aspnetcore-stdout`

Đặt biến môi trường

Biến môi trường có thể được chỉ định cho tiến trình trong thuộc tính processPath. Chỉ định biến môi trường bằng phần tử con <environmentVariable> của phần tử collection <environmentVariables>. Biến môi trường được đặt trong phần này ưu tiên hơn biến môi trường hệ thống.

Ví dụ sau đặt hai biến môi trường trong web.config. ASPNETCORE_ENVIRONMENT cấu hình môi trường của ứng dụng thành Development. Developer có thể tạm thời đặt giá trị này trong file web.config để buộc Developer Exception Page tải khi debug exception của ứng dụng. CONFIG_DIR là ví dụ về biến môi trường do người dùng định nghĩa, trong đó developer đã viết code đọc giá trị khi khởi động để hình thành đường dẫn tải file cấu hình của ứng dụng.

xml

<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>

Thay thế cho việc đặt môi trường trực tiếp trong web.config là bao gồm thuộc tính <EnvironmentName> trong publish profile (.pubxml) hoặc project file. Cách tiếp cận này đặt môi trường trong web.config khi project được publish:

``xml <PropertyGroup> <EnvironmentName>Development</EnvironmentName> </PropertyGroup>``

Chỉ đặt biến môi trường ASPNETCORE_ENVIRONMENT thành Development trên các server staging và testing không thể truy cập từ các mạng không đáng tin cậy, như Internet.

Cấu hình IIS với `web.config`

Cấu hình IIS bị ảnh hưởng bởi phần <system.webServer> của web.config cho các kịch bản IIS hoạt động với các ứng dụng ASP.NET Core cùng ASP.NET Core Module. Ví dụ, cấu hình IIS hoạt động cho dynamic compression (nén động). Nếu IIS được cấu hình ở cấp server để sử dụng dynamic compression, phần tử <urlCompression> trong file web.config của ứng dụng có thể vô hiệu hóa nó cho một ứng dụng ASP.NET Core.

Để biết thêm thông tin, xem các bài viết sau:

Để đặt biến môi trường cho các ứng dụng riêng lẻ chạy trong các app pool cô lập (hỗ trợ cho IIS 10.0 trở lên), xem phần AppCmd.exe command của bài viết Environment Variables <environmentVariables> trong tài liệu tham khảo IIS.

Các phần cấu hình của `web.config`

Các phần cấu hình của ứng dụng ASP.NET 4.x trong web.config không được sử dụng bởi các ứng dụng ASP.NET Core để cấu hình:

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

Các ứng dụng ASP.NET Core được cấu hình bằng các configuration provider (nhà cung cấp cấu hình) khác. Để biết thêm thông tin, xem Configuration.

Chuyển đổi web.config

Nếu bạn cần chuyển đổi web.config khi publish, xem Transform web.config. Bạn có thể cần chuyển đổi web.config khi publish để đặt biến môi trường dựa trên configuration, profile, hoặc environment.

File web.config

Vị trí file web.config

Cấu hình ASP.NET Core Module với web.config

Các thuộc tính của phần tử aspNetCore