Bagikan melalui

File web.config

  • Artikel

web.config adalah file yang dibaca oleh IIS dan ASP.NET Core Module untuk mengonfigurasi aplikasi yang dihosting dengan IIS.

Lokasi file web.config

Untuk menyiapkan ASP.NET Core Module dengan benar, file web.config harus ada di jalur akar konten (biasanya jalur dasar aplikasi) dari aplikasi yang diterapkan. Ini adalah lokasi yang sama dengan jalur fisik situs web yang disediakan untuk IIS. File web.config diperlukan di akar aplikasi untuk memungkinkan penerbitan beberapa aplikasi menggunakan Web Deploy.

File sensitif ada di jalur fisik aplikasi, seperti {ASSEMBLY}.runtimeconfig.json, {ASSEMBLY}.xml (komentar Dokumentasi XML), dan {ASSEMBLY}.deps.json, di mana tempat penampung {ASSEMBLY} adalah nama rakitannya. Saat file web.config ada dan situs dimulai secara normal, IIS tidak menyajikan file sensitif ini jika diminta. Jika file web.config tidak ada, salah diberi nama, atau tidak dapat mengonfigurasi situs untuk startup normal, IIS mungkin menyajikan file sensitif secara publik.

File web.config harus selalu ada dalam penyebaran, diberi nama dengan benar, dan dapat mengonfigurasi situs untuk startup yang normal. Jangan pernah menghapus file web.config dari penyebaran produksi.

Jika file web.config tidak ada dalam proyek, file dibuat dengan processPath dan arguments yang benar untuk mengonfigurasi ASP.NET Core Module dan dipindahkan ke output yang diterbitkan.

Jika file web.config ada dalam proyek, file diubah dengan processPath dan arguments yang benar untuk mengonfigurasi ASP.NET Core Module dan dipindahkan ke output yang diterbitkan. Transformasi tidak mengubah pengaturan konfigurasi IIS dalam file.

File web.config mungkin menyediakan pengaturan konfigurasi IIS tambahan yang mengontrol modul IIS aktif. Untuk informasi tentang modul IIS yang mampu memproses permintaan dengan aplikasi ASP.NET Core, lihat topik modul IIS.

Membuat, mengubah, dan menerbitkan file web.config ditangani oleh target MSBuild (_TransformWebConfig) saat proyek diterbitkan. Target ini ada di target Web SDK (Microsoft.NET.Sdk.Web). SDK diatur di bagian atas file proyek:

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

Untuk mencegah agar Web SDK tidak mengubah file web.config, gunakan properti <IsTransformWebConfigDisabled> dalam file proyek:

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

Saat menonaktifkan Web SDK agar tidak mengubah file, processPath dan arguments harus diatur secara manual oleh pengembang. Untuk informasi lebih lanjut, lihat ASP.NET Core Module (ANCM) untuk IIS.

Konfigurasi Modul inti ASP.NET dengan web.config

Modul ASP.NET Core dikonfigurasi dengan bagian aspNetCore simpul system.webServer dalam file situs web.config .

File berikut web.config diterbitkan untuk penyebaran yang bergantung pada kerangka kerja dan mengonfigurasi Modul inti ASP.NET untuk menangani permintaan situs:

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

Berikut ini web.config diterbitkan untuk penyebaran mandiri:

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

Properti InheritInChildApplications diatur ke false untuk menunjukkan bahwa pengaturan yang ditentukan dalam <location> elemen tidak diwariskan oleh aplikasi yang berada di subdirektori aplikasi.

Saat aplikasi disebarkan ke Azure App Service, stdoutLogFile jalur diatur ke \\?\%home%\LogFiles\stdout. Jalur menyimpan log stdout ke LogFiles folder, yang merupakan lokasi yang secara otomatis dibuat oleh layanan.

Untuk informasi tentang konfigurasi sub-aplikasi IIS, lihat Konfigurasi tingkat lanjut.

aspNetCore Atribut elemen

Atribut Deskripsi Default
arguments

Atribut string opsional.

Argumen ke executable yang ditentukan dalam processPath.
disableStartUpErrorPage

Atribut Boolean opsional.

Jika true, halaman 502.5 - Kegagalan Proses ditekan, dan halaman kode status 502 yang dikonfigurasi di web.config prioritas.

 false
forwardWindowsAuthToken

Atribut Boolean opsional.

Jika true, token diteruskan ke proses turunan %ASPNETCORE_PORT% yang mendengarkan sebagai header 'MS-ASPNETCORE-WINAUTHTOKEN' per permintaan. Ini adalah tanggung jawab proses itu untuk memanggil CloseHandle pada token ini per permintaan.

 true
hostingModel

Atribut string opsional.

Menentukan model hosting sebagai dalam proses (InProcess/inprocess) atau di luar proses ().OutOfProcess/outofprocess

 OutOfProcess/outofprocess ketika tidak ada
processesPerApplication

Atribut bilangan bulat opsional.

Menentukan jumlah instans proses yang ditentukan dalam processPath pengaturan yang dapat dipisahkan per aplikasi.

†Untuk hosting dalam proses, nilainya terbatas pada 1.

Pengaturan processesPerApplication tidak disarankan. Atribut ini akan dihapus dalam rilis mendatang.

 Default: 1
Min: 1
Maks: 100†
processPath

Atribut string yang diperlukan.

Jalur ke executable yang meluncurkan proses mendengarkan permintaan HTTP. Jalur relatif didukung. Jika jalur dimulai dengan ., jalur dianggap relatif terhadap akar situs.
rapidFailsPerMinute

Atribut bilangan bulat opsional.

Menentukan berapa kali proses yang ditentukan di processPath diizinkan untuk crash per menit. Jika batas ini terlampaui, modul berhenti meluncurkan proses selama sisa menit.

Tidak didukung dengan hosting dalam proses.

 Default: 10
Min: 0
Maks: 100
requestTimeout

Atribut rentang waktu opsional.

Menentukan durasi di mana Modul ASP.NET Core menunggu respons dari proses yang mendengarkan pada %ASPNETCORE_PORT%.

Dalam versi Modul ASP.NET Core yang dikirim dengan rilis ASP.NET Core 2.1 atau yang lebih baru, requestTimeout ditentukan dalam jam, menit, dan detik.

Tidak berlaku untuk hosting dalam proses. Untuk hosting dalam proses, modul menunggu aplikasi memproses permintaan.

Nilai yang valid untuk segmen menit dan detik dari string berada dalam rentang 0-59. Penggunaan 60 dalam nilai untuk menit atau detik menghasilkan 500 - Kesalahan Server Internal.

 Default: 00:02:00
Min: 00:00:00
Maks: 360:00:00
shutdownTimeLimit

Atribut bilangan bulat opsional.

Durasi dalam hitungan detik bahwa modul menunggu executable dimatikan dengan lancar saat app_offline.htm file terdeteksi.

 Default: 10
Min: 0
Maks: 600
startupTimeLimit

Atribut bilangan bulat opsional.

Durasi dalam detik bahwa modul menunggu executable untuk memulai proses yang mendengarkan pada port. Jika batas waktu ini terlampaui, modul akan mematikan proses.

Saat menghosting dalam proses: Proses tidak dimulai ulang dan tidak menggunakan rapidFailsPerMinute pengaturan.

Saat menghosting di luar proses: Modul mencoba meluncurkan kembali proses ketika menerima permintaan baru dan terus mencoba memulai ulang proses pada permintaan masuk berikutnya kecuali aplikasi gagal memulai rapidFailsPerMinute berapa kali dalam menit bergulir terakhir.

Nilai 0 (nol) tidak dianggap sebagai batas waktu tak terbatas.

 Default: 120
Min: 0
Maks: 3600
stdoutLogEnabled

Atribut Boolean opsional.

Jika true, stdout dan stderr untuk proses yang ditentukan di processPath dialihkan ke file yang ditentukan dalam stdoutLogFile.

 false
stdoutLogFile

Atribut string opsional.

Menentukan jalur file relatif atau absolut yang stdout dan stderr dari proses yang ditentukan masuk processPath . Jalur relatif relatif terhadap akar situs. Jalur apa pun yang dimulai . relatif terhadap akar situs dan semua jalur lainnya diperlakukan sebagai jalur absolut. Folder apa pun yang disediakan di jalur dibuat oleh modul saat file log dibuat. Menggunakan pemisah garis bawah, tanda waktu, ID proses, dan ekstensi file (.log) ditambahkan ke segmen stdoutLogFile terakhir jalur. Jika .\logs\stdout disediakan sebagai nilai, contoh log stdout disimpan seperti stdout_20180205194132_1934.log di logs folder saat disimpan pada 5 Februari 2018 pukul 19:41:32 dengan ID proses 1934.

 aspnetcore-stdout

Atur variabel lingkungan

Variabel lingkungan dapat ditentukan untuk proses dalam processPath atribut . Tentukan variabel lingkungan dengan <environmentVariable> elemen turunan dari <environmentVariables> elemen koleksi. Variabel lingkungan yang ditetapkan di bagian ini lebih diutamakan daripada variabel lingkungan sistem.

Contoh berikut menetapkan dua variabel lingkungan di web.config. ASPNETCORE_ENVIRONMENT mengonfigurasi lingkungan aplikasi ke Development. Pengembang dapat mengatur sementara nilai ini dalam web.config file untuk memaksa Halaman Pengecualian Pengembang dimuat saat menelusuri kesalahan pengecualian aplikasi. CONFIG_DIR adalah contoh variabel lingkungan yang ditentukan pengguna, di mana pengembang telah menulis kode yang membaca nilai pada startup untuk membentuk jalur untuk memuat file konfigurasi aplikasi.

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

Catatan

Alternatif untuk mengatur lingkungan secara langsung web.config adalah menyertakan <EnvironmentName> properti dalam profil penerbitan (.pubxml) atau file proyek. Pendekatan ini mengatur lingkungan saat web.config proyek diterbitkan:

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

Peringatan

Hanya atur ASPNETCORE_ENVIRONMENT variabel lingkungan ke Development pada pementasan dan pengujian server yang tidak dapat diakses oleh jaringan yang tidak tepercaya, seperti Internet.

Konfigurasi IIS dengan web.config

Konfigurasi IIS dipengaruhi oleh <system.webServer> bagian web.config untuk skenario IIS yang berfungsi untuk aplikasi ASP.NET Core dengan Modul inti ASP.NET. Misalnya, konfigurasi IIS berfungsi untuk pemadatan dinamis. Jika IIS dikonfigurasi di tingkat server untuk menggunakan kompresi dinamis, <urlCompression> elemen dalam file aplikasi web.config dapat menonaktifkannya untuk aplikasi ASP.NET Core.

Untuk mengetahui informasi selengkapnya, lihat topik berikut:

Untuk mengatur variabel lingkungan untuk aplikasi individual yang berjalan di kumpulan aplikasi terisolasi (didukung untuk IIS 10.0 atau yang lebih baru), lihat AppCmd.exe bagian perintah topik Variabel<environmentVariables>Lingkungan dalam dokumentasi referensi IIS.

Bagian konfigurasi dari web.config

Bagian konfigurasi aplikasi ASP.NET 4.x di web.config tidak digunakan oleh aplikasi ASP.NET Core untuk konfigurasi:

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

Aplikasi ASP.NET Core dikonfigurasi menggunakan penyedia konfigurasi lain. Untuk informasi lebih lanjut, lihat Konfigurasi.

Mengubah web.config

Jika Anda perlu mengubah web.config saat penerbitan, lihat Mengubah web.config. Anda mungkin perlu mengubah web.config saat penerbitan untuk mengatur variabel lingkungan berdasarkan konfigurasi, profil, atau lingkungan.

Sumber Daya Tambahan: