Host ASP.NET Core di Layanan Windows

Aplikasi ASP.NET Core dapat dihosting di Windows sebagai Layanan Windows tanpa menggunakan IIS. Saat dihosting sebagai Layanan Windows, aplikasi secara otomatis dimulai setelah server di-boot ulang.

Prasyarat

• ASP.NET Core SDK 7.0 atau yang lebih baru
• PowerShell 6.2 atau yang lebih baru

Templat Layanan Pekerja

Templat Layanan Pekerja Inti ASP.NET menyediakan titik awal untuk menulis aplikasi layanan yang berjalan lama. Untuk menggunakan templat sebagai dasar untuk aplikasi Windows Service:

1. Buat aplikasi Layanan Pekerja dari templat .NET Core.
2. Instal paket NuGet Microsoft.Extensions.Hosting.WindowsServices.
3. Ikuti panduan di bagian Konfigurasi aplikasi untuk memperbarui aplikasi Layanan Pekerja sehingga dapat berjalan sebagai Layanan Windows.

Visual Studio

1. Buat proyek baru.
2. Pilih Layanan Pekerja. Pilih Selanjutnya.
3. Berikan nama proyek di bidang Nama proyek atau terima nama proyek default. Pilih Buat.
4. Dalam dialog Buat layanan Pekerja baru, pilih Buat.

Visual Studio untuk Mac

1. Buat proyek baru.
2. Pilih Aplikasi di bawah .NET Core di bar samping.
3. Pilih Pekerja di bawah ASP.NET Core. Pilih Selanjutnya.
4. Pilih .NET Core 3.0 atau yang lebih baru untuk Kerangka Kerja Target. Pilih Selanjutnya.
5. Berikan nama di bidang Nama Proyek. Pilih Buat.

.NET Core CLI

Gunakan templat Layanan Pekerja (worker) dengan perintah baru dotnet dari shell perintah. Dalam contoh berikut, aplikasi Layanan Pekerja dibuat bernama ContosoWorker. Folder untuk ContosoWorker aplikasi dibuat secara otomatis saat perintah dijalankan.

dotnet new worker -o ContosoWorker

Konfigurasi aplikasi

Perbarui Program.cs untuk memanggil AddWindowsService. Saat aplikasi berjalan sebagai Layanan Windows, AddWindowsService:

• Mengatur masa pakai host ke WindowsServiceLifetime.
• Mengatur akar konten ke AppContext.BaseDirectory. Untuk informasi selengkapnya, lihat bagian Direktori saat ini dan akar konten.
• Memungkinkan pengelogan ke log peristiwa:
  • Nama aplikasi digunakan sebagai nama sumber default.
  • Tingkat log default adalah Peringatan atau lebih tinggi untuk aplikasi berdasarkan templat ASP.NET Core yang memanggil CreateDefaultBuilder untuk membangun host.
  • Ambil alih tingkat log default dengan Logging:EventLog:LogLevel:Default kunci di appsettings.json/appsettings.{Environment}.json atau penyedia konfigurasi lainnya.
  • Hanya administrator yang dapat membuat sumber peristiwa baru. Ketika sumber peristiwa tidak dapat dibuat menggunakan nama aplikasi, peringatan dicatat ke sumber Aplikasi dan log peristiwa dinonaktifkan.

Pertimbangkan kelas berikut ServiceA :

namespace SampleApp.Services;

public class ServiceA : BackgroundService
{
    public ServiceA(ILoggerFactory loggerFactory)
    {
        Logger = loggerFactory.CreateLogger<ServiceA>();
    }

    public ILogger Logger { get; }

    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        Logger.LogInformation("ServiceA is starting.");

        stoppingToken.Register(() => Logger.LogInformation("ServiceA is stopping."));

        while (!stoppingToken.IsCancellationRequested)
        {
            Logger.LogInformation("ServiceA is doing background work.");

            await Task.Delay(TimeSpan.FromSeconds(5), stoppingToken);
        }

        Logger.LogInformation("ServiceA has stopped.");
    }
}

Panggilan AddHostedService berikut Program.cs untuk mendaftar ServiceA:

using SampleApp.Services;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorPages();

builder.Services.AddWindowsService();
builder.Services.AddHostedService<ServiceA>();

var app = builder.Build();

app.MapRazorPages();

app.Run();

Contoh aplikasi berikut menyertai topik ini:

• Sampel Layanan Pekerja Latar Belakang: Sampel aplikasi non-web berdasarkan templat Layanan Pekerja yang menggunakan layanan yang dihosting untuk tugas latar belakang.
• Sampel Web App Service: Razor Sampel aplikasi web Pages yang berjalan sebagai Layanan Windows dengan layanan yang dihosting untuk tugas latar belakang.

Untuk panduan MVC, lihat artikel di bawah Gambaran Umum ASP.NET Core MVC dan Migrasi dari ASP.NET Core 2.2 ke 3.0.

Jenis penyebaran

Untuk informasi dan saran tentang skenario penyebaran, lihat penyebaran aplikasi .NET Core.

SDK

Untuk layanan berbasis aplikasi web yang menggunakan Razor kerangka kerja Pages atau MVC, tentukan Web SDK dalam file proyek:

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

Jika layanan hanya menjalankan tugas latar belakang (misalnya, layanan yang dihosting), tentukan SDK Pekerja dalam file proyek:

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

Penyebaran yang bergantung pada kerangka kerja (FDD)

Penyebaran yang bergantung pada kerangka kerja (FDD) bergantung pada keberadaan versi .NET Core di seluruh sistem bersama pada sistem target. Ketika skenario FDD diadopsi mengikuti panduan dalam artikel ini, SDK menghasilkan executable (.exe), yang disebut executable yang bergantung pada kerangka kerja.

Jika menggunakan Web SDK, file web.config , yang biasanya diproduksi saat menerbitkan aplikasi ASP.NET Core, tidak perlu untuk aplikasi Windows Services. Untuk menonaktifkan pembuatan file web.config , tambahkan properti yang <IsTransformWebConfigDisabled> diatur ke true.

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

Penyebaran mandiri (SCD)

Penyebaran mandiri (SCD) tidak bergantung pada keberadaan kerangka kerja bersama pada sistem host. Runtime dan dependensi aplikasi disebarkan dengan aplikasi.

Pengidentifikasi Runtime Windows (RID) disertakan dalam <PropertyGroup> yang berisi kerangka kerja target:

<RuntimeIdentifier>win7-x64</RuntimeIdentifier>

Untuk menerbitkan beberapa RID:

• Berikan RID dalam daftar yang dibatasi titik koma.
• Gunakan nama <properti RuntimeIdentifiers> (plural).

Untuk informasi selengkapnya, lihat Katalog .NET Core RID.

Akun pengguna layanan

Untuk membuat akun pengguna untuk layanan, gunakan cmdlet New-LocalUser dari shell perintah PowerShell 6 administratif.

Pada Pembaruan Windows 10 Oktober 2018 (versi 1809/build 10.0.17763) atau yang lebih baru:

New-LocalUser -Name {SERVICE NAME}

Pada OS Windows yang lebih lama dari Pembaruan Windows 10 Oktober 2018 (versi 1809/build 10.0.17763):

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

Berikan kata sandi yang kuat saat diminta.

-AccountExpires Kecuali parameter disediakan ke cmdlet New-LocalUser dengan kedaluwarsa DateTime, akun tidak kedaluwarsa.

Untuk informasi selengkapnya, lihat Microsoft.PowerShell.LocalAccounts dan Akun Pengguna Layanan.

Pendekatan alternatif untuk mengelola pengguna saat menggunakan Direktori Aktif adalah menggunakan Akun Layanan Terkelola. Untuk informasi selengkapnya, lihat Gambaran Umum Akun Layanan Terkelola Grup.

Masuk sebagai hak layanan

Untuk menetapkan Log masuk sebagai hak layanan untuk akun pengguna layanan:

1. Buka editor Kebijakan Keamanan Lokal dengan menjalankan secpol.msc.
2. Perluas simpul Kebijakan Lokal dan pilih Penetapan Hak Pengguna.
3. Buka kebijakan Masuk sebagai layanan.
4. Pilih Tambahkan Pengguna atau Grup.
5. Berikan nama objek (akun pengguna) menggunakan salah satu pendekatan berikut:
   1. Ketik akun pengguna ({DOMAIN OR COMPUTER NAME\USER}) di bidang nama objek dan pilih OK untuk menambahkan pengguna ke kebijakan.
   2. Pilih Tingkat Lanjut. Pilih Temukan Sekarang. Pilih akun pengguna dari daftar. Pilih OK. Pilih OK lagi untuk menambahkan pengguna ke kebijakan.
6. Pilih OK atau Terapkan untuk menerima perubahan.

Membuat dan mengelola Layanan Windows

Membuat layanan

Gunakan perintah PowerShell untuk mendaftarkan layanan. Dari shell perintah PowerShell 6 administratif, jalankan perintah berikut:

$acl = Get-Acl "{EXE PATH}"
$aclRuleArgs = "{DOMAIN OR COMPUTER NAME\USER}", "Read,Write,ReadAndExecute", "ContainerInherit,ObjectInherit", "None", "Allow"
$accessRule = New-Object System.Security.AccessControl.FileSystemAccessRule($aclRuleArgs)
$acl.SetAccessRule($accessRule)
$acl | Set-Acl "{EXE PATH}"

New-Service -Name {SERVICE NAME} -BinaryPathName "{EXE FILE PATH} --contentRoot {EXE FOLDER PATH}" -Credential "{DOMAIN OR COMPUTER NAME\USER}" -Description "{DESCRIPTION}" -DisplayName "{DISPLAY NAME}" -StartupType Automatic

• {EXE PATH}: Jalur aplikasi yang dapat dieksekusi pada host (misalnya, d:\myservice). Jangan sertakan nama file aplikasi yang dapat dieksekusi di jalur. Garis miring berikutnya tidak diperlukan.
• {DOMAIN OR COMPUTER NAME\USER}: Akun pengguna layanan (misalnya, Contoso\ServiceUser).
• {SERVICE NAME}: Nama layanan (misalnya, MyService).
• {EXE FILE PATH}: Jalur aplikasi yang dapat dieksekusi penuh (misalnya, d:\myservice\myservice.exe). Sertakan nama file yang dapat dieksekusi dengan ekstensi.
• {EXE FOLDER PATH}: Jalur folder aplikasi yang dapat dieksekusi penuh (misalnya d:\myservice).
• {DESCRIPTION}: Deskripsi layanan (misalnya, My sample service).
• {DISPLAY NAME}: Nama tampilan layanan (misalnya, My Service).

Memulai layanan

Mulai layanan dengan perintah PowerShell 6 berikut ini:

Start-Service -Name {SERVICE NAME}

Perintah membutuhkan waktu beberapa detik untuk memulai layanan.

Menentukan status layanan

Untuk memeriksa status layanan, gunakan perintah PowerShell 6 berikut ini:

Get-Service -Name {SERVICE NAME}

Status dilaporkan sebagai salah satu nilai berikut:

• Starting
• Running
• Stopping
• Stopped

Menghentikan layanan

Hentikan layanan dengan perintah PowerShell 6 berikut ini:

Stop-Service -Name {SERVICE NAME}

Menghapus layanan

Setelah penundaan singkat untuk menghentikan layanan, hapus layanan dengan perintah PowerShell 6 berikut:

Remove-Service -Name {SERVICE NAME}

Skenario server proksi dan penyeimbang beban

Layanan yang berinteraksi dengan permintaan dari Internet atau jaringan perusahaan dan berada di belakang proksi atau penyeimbang muatan mungkin memerlukan konfigurasi tambahan. Untuk informasi selengkapnya, lihat Mengonfigurasi ASP.NET Core untuk bekerja dengan server proxy dan memuat penyeimbang.

Mengonfigurasi titik akhir

Secara default, ASP.NET Core mengikat ke http://localhost:5000. Konfigurasikan URL dan port dengan mengatur ASPNETCORE_URLS variabel lingkungan.

Untuk pendekatan KONFIGURASI URL dan port tambahan, lihat artikel server yang relevan:

• Mengonfigurasi titik akhir untuk server web ASP.NET Core Kestrel
• Implementasi server web HTTP.sys di ASP.NET Core

Panduan sebelumnya mencakup dukungan untuk titik akhir HTTPS. Misalnya, konfigurasikan aplikasi untuk HTTPS saat autentikasi digunakan dengan Layanan Windows.

Catatan

Penggunaan sertifikat pengembangan ASP.NET Core HTTPS untuk mengamankan titik akhir layanan tidak didukung.

Direktori saat ini dan akar konten

Direktori kerja saat ini yang dikembalikan dengan memanggil GetCurrentDirectory Layanan Windows adalah folder C:\WINDOWS\system32 . Folder system32 bukan lokasi yang cocok untuk menyimpan file layanan (misalnya, file pengaturan). Gunakan salah satu pendekatan berikut untuk memelihara dan mengakses aset layanan dan file pengaturan.

Menggunakan ContentRootPath atau ContentRootFileProvider

Gunakan IHostEnvironment.ContentRootPath atau ContentRootFileProvider untuk menemukan sumber daya aplikasi.

Saat aplikasi berjalan sebagai layanan, UseWindowsService mengatur ContentRootPath ke AppContext.BaseDirectory.

File pengaturan default aplikasi, appsettings.json dan appsettings.{Environment}.json, dimuat dari akar konten aplikasi dengan memanggil CreateDefaultBuilder selama konstruksi host.

Untuk file pengaturan lain yang dimuat oleh kode pengembang di ConfigureAppConfiguration, tidak perlu memanggil SetBasePath. Dalam contoh berikut, custom_settings.json file ada di akar konten aplikasi dan dimuat tanpa mengatur jalur dasar secara eksplisit:

public class Program
{
    public static void Main(string[] args)
    {
        CreateHostBuilder(args).Build().Run();
    }

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .UseWindowsService()
            .ConfigureAppConfiguration((hostingContext, config) =>
            {
                config.AddJsonFile("custom_settings.json");
            })
            .ConfigureServices((hostContext, services) =>
            {
                services.AddHostedService<Worker>();
            });
}

Jangan coba gunakan GetCurrentDirectory untuk mendapatkan jalur sumber daya karena aplikasi Layanan Windows mengembalikan folder C:\WINDOWS\system32 sebagai direktorinya saat ini.

Menyimpan file layanan di lokasi yang sesuai pada disk

Tentukan jalur absolut dengan SetBasePath saat menggunakan IConfigurationBuilder ke folder yang berisi file.

Pemecahan Masalah

Untuk memecahkan masalah aplikasi Layanan Windows, lihat Memecahkan masalah dan men-debug proyek ASP.NET Core.

Kesalahan umum

• PowerShell versi lama atau pra-rilis sedang digunakan.
• Layanan terdaftar tidak menggunakan output aplikasi yang diterbitkan dari perintah terbitkan dotnet. Output perintah build dotnet tidak didukung untuk penyebaran aplikasi. Aset yang diterbitkan ditemukan di salah satu folder berikut tergantung pada jenis penyebaran:
  • bin/Release/{TARGET FRAMEWORK}/publish (FDD)
  • bin/Release/{TARGET FRAMEWORK}/{RUNTIME IDENTIFIER}/publish (SCD)
• Layanan ini tidak dalam status BERJALAN.
• Jalur ke sumber daya yang digunakan aplikasi (misalnya, sertifikat) salah. Jalur dasar Layanan Windows adalah c:\Windows\System32.
• Pengguna tidak memiliki hak Masuk sebagai layanan .
• Kata sandi pengguna kedaluwarsa atau salah diteruskan saat menjalankan New-Service perintah PowerShell.
• Aplikasi ini memerlukan autentikasi ASP.NET Core tetapi tidak dikonfigurasi untuk koneksi aman (HTTPS).
• Port URL permintaan salah atau tidak dikonfigurasi dengan benar di aplikasi.

Log Peristiwa Sistem dan Aplikasi

Akses Log Peristiwa Sistem dan Aplikasi:

1. Buka menu Mulai, cari Pemantau Peristiwa, dan pilih aplikasi Pemantau Peristiwa.
2. Di Pemantau Peristiwa, buka simpul Log Windows.
3. Pilih Sistem untuk membuka Log Peristiwa Sistem. Pilih Aplikasi untuk membuka Log Peristiwa Aplikasi.
4. Cari kesalahan yang terkait dengan aplikasi yang gagal.

Jalankan aplikasi pada prompt perintah

Banyak kesalahan startup tidak menghasilkan informasi yang berguna dalam log peristiwa. Anda dapat menemukan penyebab beberapa kesalahan dengan menjalankan aplikasi pada prompt perintah pada sistem hosting. Untuk mencatat detail tambahan dari aplikasi, turunkan tingkat log atau jalankan aplikasi di lingkungan Pengembangan.

Menghapus cache paket

Aplikasi yang berfungsi mungkin gagal segera setelah meningkatkan .NET Core SDK pada komputer pengembangan atau mengubah versi paket dalam aplikasi. Dalam beberapa kasus, paket yang tidak melekat dapat merusak aplikasi saat melakukan peningkatan besar. Sebagian besar masalah ini dapat diperbaiki dengan mengikuti instruksi berikut:

1. Hapus folder bin dan obj.

2. Bersihkan cache paket dengan mengeksekusi lokal dotnet nuget semuanya --clear dari shell perintah.

   Menghapus cache paket juga dapat dicapai dengan alat nuget.exe dan menjalankan perintah nuget locals all -clear. nuget.exe bukan instalasi yang dibundel dengan sistem operasi desktop Windows dan harus diperoleh secara terpisah dari situs web NuGet.

3. Pulihkan dan bangun ulang proyek.

4. Hapus semua file di folder penyebaran di server sebelum menyebarkan ulang aplikasi.

Aplikasi lambat atau tidak responsif

Crash dump adalah rekam jepret memori sistem dan dapat membantu menentukan penyebab crash aplikasi, kegagalan startup, atau aplikasi lambat.

Aplikasi mengalami crash atau mengalami pengecualian

Dapatkan dan analisis cadangan dari Pelaporan Galat Windows (WER):

1. Buat folder untuk menyimpan file crash dump di c:\dumps.

2. Jalankan skrip EnableDumps PowerShell dengan nama aplikasi yang dapat dieksekusi:

   .\EnableDumps {APPLICATION EXE} c:\dumps
   

3. Jalankan aplikasi dalam kondisi yang menyebabkan crash terjadi.

4. Setelah crash terjadi, jalankan skrip DisableDumps PowerShell:

   .\DisableDumps {APPLICATION EXE}
   

Setelah aplikasi crash dan pengumpulan cadangan selesai, aplikasi diizinkan untuk berakhir secara normal. Skrip PowerShell mengonfigurasi WER untuk mengumpulkan hingga lima cadangan per aplikasi.

Peringatan

Crash dump mungkin memakan ruang disk dalam jumlah besar (masing-masing hingga beberapa gigabyte).

Aplikasi tidak responsif, gagal selama startup, atau berjalan secara normal

Saat aplikasi macet (berhenti merespons tetapi tidak crash), gagal selama startup, atau berjalan secara normal, lihat File Cadangan Mode Pengguna: Memilih Alat Terbaik untuk memilih alat yang sesuai untuk menghasilkan cadangan.

Menganalisis cadangan

Cadangan dapat dianalisis menggunakan beberapa pendekatan. Untuk informasi selengkapnya, lihat Menganalisis File Cadangan Mode Pengguna.

Sumber Daya Tambahan:

• Melihat atau mengunduh kode sampel (cara mengunduh)
• Kestrel konfigurasi titik akhir (termasuk konfigurasi HTTPS dan dukungan SNI)
• Host Generik .NET di ASP.NET Core
• Memecahkan masalah dan mendebug proyek ASP.NET Core