Windows Hizmetinde ASP.NET Core Barındırma

ASP.NET Core uygulaması, IIS kullanılmadan Bir Windows Hizmeti olarak Windows'ta barındırılabilir. Windows Hizmeti olarak barındırıldığında, sunucu yeniden başlatıldıktan sonra uygulama otomatik olarak başlatılır.

Ön koşullar

• ASP.NET Core SDK 7.0 veya üzeri
• PowerShell 6.2 veya üzeri

Çalışan Hizmeti şablonu

ASP.NET Temel Çalışan Hizmeti şablonu, uzun süre çalışan hizmet uygulamaları yazmak için bir başlangıç noktası sağlar. Şablonu bir Windows Hizmeti uygulamasının temeli olarak kullanmak için:

1. .NET Core şablonundan bir Çalışan Hizmeti uygulaması oluşturun.
2. Microsoft.Extensions.Hosting.WindowsServices NuGet paketini yükleyin.
3. Windows Hizmeti olarak çalışabilmesi için Çalışan Hizmeti uygulamasını güncelleştirmek için Uygulama yapılandırması bölümündeki yönergeleri izleyin.

Visual Studio

1. Yeni bir proje oluşturma.
2. Çalışan Hizmeti'ne tıklayın. İleri’yi seçin.
3. Proje adı alanına bir proje adı girin veya varsayılan proje adını kabul edin. Create'u seçin.
4. Yeni Çalışan hizmeti oluştur iletişim kutusunda Oluştur'u seçin.

Mac için Visual Studio

1. Yeni bir proje oluşturma.
2. Kenar çubuğunda .NET Core altında Uygulama'ya tıklayın.
3. ASP.NET Core altında Çalışan'ı seçin. İleri’yi seçin.
4. Hedef Çerçeve için .NET Core 3.0 veya üzerini seçin. İleri’yi seçin.
5. Proje Adı alanına bir ad girin. Create'u seçin.

.NET Core CLI

Çalışan Hizmeti (worker) şablonunu bir komut kabuğundan dotnet new komutuyla kullanın. Aşağıdaki örnekte adlı ContosoWorkerbir Çalışan Hizmeti uygulaması oluşturulur. Komut yürütülürken uygulama için ContosoWorker otomatik olarak bir klasör oluşturulur.

dotnet new worker -o ContosoWorker

Uygulama yapılandırması

AddWindowsService'i çağırmak için Program.cs dosyasını güncelleştirin. Uygulama Bir Windows Hizmeti olarak çalışırken, AddWindowsService:

• Konak ömrünü olarak WindowsServiceLifetimeayarlar.
• İçerik kökünü AppContext.BaseDirectory olarak ayarlar. Daha fazla bilgi için Geçerli dizin ve içerik kök bölümüne bakın.
• Olay günlüğünde günlüğe kaydetmeyi etkinleştirir:
  • Uygulama adı varsayılan kaynak adı olarak kullanılır.
  • Varsayılan günlük düzeyi, konağı derlemeye çağıran CreateDefaultBuilder bir ASP.NET Core şablonunu temel alan bir uygulama için Uyarı veya üzeridir.
  • Varsayılan günlük düzeyini veya başka bir yapılandırma sağlayıcısındaki Logging:EventLog:LogLevel:Defaultappsettings.json/appsettings.{Environment}.json anahtarla geçersiz kılın.
  • Yalnızca yöneticiler yeni olay kaynakları oluşturabilir. Bir olay kaynağı uygulama adı kullanılarak oluşturulamıyorsa, Uygulama kaynağına bir uyarı kaydedilir ve olay günlükleri devre dışı bırakılır.

Aşağıdaki ServiceA sınıfı göz önünde bulundurun:

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.");
    }
}

Kaydetmek ServiceAiçin aşağıdaki Program.cs çağrılarAddHostedService:

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();

Bu konuya aşağıdaki örnek uygulamalar eşlik ediyor:

• Arka Plan Çalışanı Hizmeti Örneği: Arka plan görevleri için barındırılan hizmetleri kullanan Çalışan Hizmeti şablonunu temel alan web uygulaması olmayan bir örnek.
• Web App Service Örneği: Razor Arka plan görevleri için barındırılan hizmetlere sahip bir Windows Hizmeti olarak çalışan sayfalar web uygulaması örneği.

MVC kılavuzu için ASP.NET Core MVC'ye Genel Bakış ve ASP.NET Core 2.2'den 3.0'a geçiş altındaki makalelere bakın.

Dağıtım türü

Dağıtım senaryoları hakkında bilgi ve öneri için bkz . .NET Core uygulama dağıtımı.

SDK

Pages veya MVC çerçevelerini kullanan Razor web uygulaması tabanlı bir hizmet için proje dosyasında Web SDK'sını belirtin:

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

Hizmet yalnızca arka plan görevlerini (örneğin, barındırılan hizmetler) yürütürse, proje dosyasında Çalışan SDK'sını belirtin:

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

Çerçeveye bağımlı dağıtım (FDD)

Çerçeveye bağımlı dağıtım (FDD), hedef sistemde .NET Core'un paylaşılan bir sistem genelinde sürümünün bulunmasına dayanır. Bu makaledeki yönergeleri izleyerek FDD senaryosu benimsendiğinde SDK, çerçeveye bağımlı yürütülebilir dosya olarak adlandırılan bir yürütülebilir dosya (.exe) oluşturur.

Web SDK'sı kullanılıyorsa, normalde bir ASP.NET Core uygulaması yayımlanırken oluşturulan bir web.config dosyası Bir Windows Hizmetleri uygulaması için gereksizdir. web.config dosyasının oluşturulmasını devre dışı bırakmak için, özelliğini olarak ekleyintrue<IsTransformWebConfigDisabled>.

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

Bağımsız dağıtım (SCD)

Bağımsız dağıtım (SCD), konak sisteminde paylaşılan bir çerçevenin varlığına güvenmez. Çalışma zamanı ve uygulamanın bağımlılıkları uygulamayla birlikte dağıtılır.

Hedef çerçeveyi içeren içinde <PropertyGroup> bir Windows Çalışma Zamanı Tanımlayıcısı (RID) bulunur:

<RuntimeIdentifier>win7-x64</RuntimeIdentifier>

Birden çok RID için yayımlamak için:

• RID'leri noktalı virgülle ayrılmış bir listede belirtin.
• RuntimeIdentifiers> (çoğul) özellik adını <kullanın.

Daha fazla bilgi için bkz . .NET Core RID Kataloğu.

Hizmet kullanıcı hesabı

Bir hizmet için kullanıcı hesabı oluşturmak için, yönetim PowerShell 6 komut kabuğundan New-LocalUser cmdlet'ini kullanın.

Windows 10 Ekim 2018 Güncelleştirmesi (sürüm 1809/derleme 10.0.17763) veya üzeri:

New-LocalUser -Name {SERVICE NAME}

Windows 10 Ekim 2018 Güncelleştirmesi önceki Windows işletim sisteminde (sürüm 1809/derleme 10.0.17763):

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

İstendiğinde güçlü bir parola sağlayın.

-AccountExpires New-LocalUser cmdlet'ine süresi dolmadan DateTimeparametre sağlanmadığı sürece hesabın süresi dolmaz.

Daha fazla bilgi için bkz . Microsoft.PowerShell.LocalAccounts ve Hizmet Kullanıcı Hesapları.

Active Directory kullanırken kullanıcıları yönetmeye alternatif bir yaklaşım, Yönetilen Hizmet Hesaplarını kullanmaktır. Daha fazla bilgi için bkz . Grup Yönetilen Hizmet Hesaplarına Genel Bakış.

Hizmet hakları olarak oturum açma

Hizmet kullanıcı hesabının hizmet olarak oturum açma haklarını oluşturmak için:

1. secpol.msc dosyasını çalıştırarak Yerel Güvenlik İlkesi düzenleyicisini açın.
2. Yerel İlkeler düğümünü genişletin ve Kullanıcı Hakları Ataması'nı seçin.
3. Hizmet olarak oturum aç ilkesini açın.
4. Kullanıcı veya Grup Ekle'yi seçin.
5. Aşağıdaki yaklaşımlardan birini kullanarak nesne adını (kullanıcı hesabı) belirtin:
   1. Nesne adı alanına kullanıcı hesabını ({DOMAIN OR COMPUTER NAME\USER}) yazın ve kullanıcıyı ilkeye eklemek için Tamam'ı seçin.
   2. Gelişmiş'i seçin. Şimdi Bul'u seçin. Listeden kullanıcı hesabını seçin. Tamam'ı seçin. Kullanıcıyı ilkeye eklemek için yeniden Tamam'ı seçin.
6. Değişiklikleri kabul etmek için Tamam'ı veya Uygula'yı seçin.

Windows Hizmeti oluşturma ve yönetme

Bir servis oluşturmak

Bir hizmeti kaydetmek için PowerShell komutlarını kullanın. Yönetim PowerShell 6 komut kabuğundan aşağıdaki komutları yürütebilirsiniz:

$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}: Uygulamanın ana bilgisayar üzerindeki yürütülebilir dosyasının yolu (örneğin, d:\myservice). Uygulamanın yürütülebilir dosya adını yola eklemeyin. Sondaki eğik çizgi gerekli değildir.
• {DOMAIN OR COMPUTER NAME\USER}: Hizmet kullanıcı hesabı (örneğin, Contoso\ServiceUser).
• {SERVICE NAME}: Hizmet adı (örneğin, MyService).
• {EXE FILE PATH}: Uygulamanın tam yürütülebilir yolu (örneğin, d:\myservice\myservice.exe). Yürütülebilir dosyanın dosya adını uzantıya ekleyin.
• {EXE FOLDER PATH}: Uygulamanın tam yürütülebilir klasör yolu (örneğin d:\myservice).
• {DESCRIPTION}: Hizmet açıklaması (örneğin, My sample service).
• {DISPLAY NAME}: Hizmet görünen adı (örneğin, My Service).

Bir hizmet başlatın

Aşağıdaki PowerShell 6 komutuyla bir hizmet başlatın:

Start-Service -Name {SERVICE NAME}

Komutun başlatılması birkaç saniye sürer.

Bir hizmetin durumunu belirleme

Bir hizmetin durumunu denetlemek için aşağıdaki PowerShell 6 komutunu kullanın:

Get-Service -Name {SERVICE NAME}

Durum aşağıdaki değerlerden biri olarak bildirilir:

• Starting
• Running
• Stopping
• Stopped

Bir hizmet durdurun

Aşağıdaki PowerShell 6 komutuyla bir hizmeti durdurun:

Stop-Service -Name {SERVICE NAME}

Hizmeti kaldırma

Bir hizmeti durdurmak için kısa bir gecikmeden sonra, aşağıdaki PowerShell 6 komutuyla bir hizmeti kaldırın:

Remove-Service -Name {SERVICE NAME}

Ara sunucu ve yük dengeleyici senaryoları

İnternet'ten veya şirket ağından gelen isteklerle etkileşim kuran ve ara sunucu veya yük dengeleyicinin arkasında olan hizmetler ek yapılandırma gerektirebilir. Daha fazla bilgi için bkz. ASP.NET Core'u ara sunucular ve yük dengeleyicilerle çalışacak şekilde yapılandırma.

Uç noktaları yapılandırma

Varsayılan olarak, ASP.NET Core öğesine http://localhost:5000bağlanır. Ortam değişkenini ayarlayarak URL'yi ASPNETCORE_URLS ve bağlantı noktasını yapılandırın.

Ek URL ve bağlantı noktası yapılandırma yaklaşımları için ilgili sunucu makalesine bakın:

• ASP.NET Core Kestrel web sunucusu için uç noktaları yapılandırma
• ASP.NET Core'da HTTP.sys web sunucusu uygulaması

Yukarıdaki kılavuz, HTTPS uç noktaları için desteği kapsar. Örneğin, bir Windows Hizmeti ile kimlik doğrulaması kullanıldığında uygulamayı HTTPS için yapılandırın.

Dekont

Hizmet uç noktasının güvenliğini sağlamak için ASP.NET Core HTTPS geliştirme sertifikasının kullanılması desteklenmez.

Geçerli dizin ve içerik kökü

Bir Windows Hizmeti için çağrılarak GetCurrentDirectory döndürülen geçerli çalışma dizini C:\WINDOWS\system32 klasörüdür. system32 klasörü, bir hizmetin dosyalarını (örneğin, ayarlar dosyaları) depolamak için uygun bir konum değildir. Bir hizmetin varlık ve ayar dosyalarını korumak ve bu dosyalara erişmek için aşağıdaki yaklaşımlardan birini kullanın.

ContentRootPath veya ContentRootFileProvider kullanma

IHostEnvironment.ContentRootPath kullanın veya ContentRootFileProvider bir uygulamanın kaynaklarını bulun.

Uygulama bir hizmet olarak çalıştığında, UseWindowsService öğesini AppContext.BaseDirectory olarak ayarlar ContentRootPath.

Uygulamanın varsayılan ayar dosyaları appsettings.json ve appsettings.{Environment}.json, konak oluşturma sırasında CreateDefaultBuilder çağrılarak uygulamanın içerik kökünden yüklenir.

içinde ConfigureAppConfigurationgeliştirici kodu tarafından yüklenen diğer ayarlar dosyaları için çağrısı SetBasePathyapmanıza gerek yoktur. Aşağıdaki örnekte, custom_settings.json dosya uygulamanın içerik kökünde bulunur ve açıkça bir temel yol ayarlanmadan yüklenir:

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>();
            });
}

Bir Windows Hizmeti uygulaması geçerli dizini olarak C:\WINDOWS\system32 klasörünü döndürdüğünden, kaynak yolu almak için kullanmayı GetCurrentDirectory denemeyin.

Bir hizmetin dosyalarını diskte uygun bir konumda depolama

dosyaları içeren klasöre kullanırken ile SetBasePathIConfigurationBuilder mutlak bir yol belirtin.

Sorun giderme

Windows Hizmeti uygulamasında sorun gidermek için bkz . ASP.NET Core projelerinin sorunlarını giderme ve hatalarını ayıklama.

Sık karşılaşılan hatalar

• PowerShell'in eski veya yayın öncesi sürümü kullanılıyor.
• Kayıtlı hizmet, uygulamanın dotnet publish komutundan yayımlanan çıkışını kullanmaz. Dotnet build komutunun çıkışı uygulama dağıtımı için desteklenmez. Yayımlanan varlıklar, dağıtım türüne bağlı olarak aşağıdaki klasörlerden birinde bulunur:
  • bin/Release/{TARGET FRAMEWORK}/publish (FDD)
  • bin/Release/{TARGET FRAMEWORK}/{RUNTIME IDENTIFIER}/publish (SCD)
• Hizmet ÇALıŞıYOR durumunda değil.
• Uygulamanın kullandığı kaynakların yolları (örneğin, sertifikalar) yanlıştır. Windows Hizmetinin temel yolu c:\Windows\System32'dir.
• Kullanıcının hizmet olarak oturum açma hakları yoktur.
• PowerShell komutu yürütülürken kullanıcının parolasının New-Service süresi doldu veya yanlış geçirildi.
• Uygulama ASP.NET Çekirdek kimlik doğrulaması gerektirir ancak güvenli bağlantılar (HTTPS) için yapılandırılmamış.
• İstek URL'si bağlantı noktası hatalı veya uygulamada doğru yapılandırılmamış.

Sistem ve Uygulama Olay Günlükleri

Sistem ve Uygulama Olay Günlüklerine erişin:

1. Başlat menüsü açın, Olay Görüntüleyicisi arayın ve Olay Görüntüleyicisi uygulamasını seçin.
2. Olay Görüntüleyicisi'da Windows Günlükleri düğümünü açın.
3. Sistem Olay Günlüğü'nü açmak için Sistem'i seçin. Uygulama Olay Günlüğü'nü açmak için Uygulama'ya tıklayın.
4. Başarısız uygulamayla ilişkili hataları arayın.

Uygulamayı komut isteminde çalıştırma

Birçok başlatma hatası, olay günlüklerinde yararlı bilgiler üretmez. Uygulamayı barındırma sisteminde bir komut isteminde çalıştırarak bazı hataların nedenini bulabilirsiniz. Uygulamadan ek ayrıntıları günlüğe kaydetmek için günlük düzeyini azaltın veya uygulamayı Geliştirme ortamında çalıştırın.

Paket önbelleklerini temizleme

Çalışan bir uygulama, geliştirme makinesindeki .NET Core SDK'sını yükselttikten veya uygulama içindeki paket sürümlerini değiştirdikten hemen sonra başarısız olabilir. Bazı durumlarda, tutarsız paketler ana yükseltmeler yaparken bir uygulamayı bozabilir. Bu sorunların çoğu şu yönergeleri izleyerek düzeltilebilir:

1. Bölme ve obj klasörlerini silin.

2. dotnet nuget locals all --clear komutunu komut kabuğundan yürüterek paket önbelleklerini temizleyin .

   Paket önbelleklerini temizleme işlemi nuget.exe aracıyla ve komutu nuget locals all -clearyürütülerek de gerçekleştirilebilir. nuget.exe, Windows masaüstü işletim sistemiyle paketlenmiş bir yükleme değildir ve NuGet web sitesinden ayrı olarak alınmalıdır.

3. Projeyi geri yükleyin ve yeniden oluşturun.

4. Uygulamayı yeniden dağıtmadan önce sunucudaki dağıtım klasöründeki tüm dosyaları silin.

Yavaş veya yanıt vermeyen uygulama

Kilitlenme bilgi dökümü, sistem belleğinin anlık görüntüsüdür ve uygulama kilitlenmesinin, başlatma hatasının veya yavaş uygulamanın nedenini belirlemeye yardımcı olabilir.

Uygulama kilitleniyor veya bir özel durumla karşılaşıyor

Windows Hata Bildirimi (WER) dökümünü alma ve analiz etme:

1. kilitlenme dökümü dosyalarının konumunda c:\dumpstutulacağı bir klasör oluşturun.

2. EnableDumps PowerShell betiğini uygulama yürütülebilir adıyla çalıştırın:

   .\EnableDumps {APPLICATION EXE} c:\dumps
   

3. Kilitlenmeye neden olan koşullar altında uygulamayı çalıştırın.

4. Kilitlenme oluştuktan sonra DisableDumps PowerShell betiğini çalıştırın:

   .\DisableDumps {APPLICATION EXE}
   

Bir uygulama kilitlenip döküm toplama işlemi tamamlandıktan sonra uygulamanın normal şekilde sonlandırılmasına izin verilir. PowerShell betiği, WER'yi uygulama başına en fazla beş döküm toplayacak şekilde yapılandırır.

Uyarı

Kilitlenme bilgi dökümleri büyük miktarda disk alanı kaplayabilir (her biri birkaç gigabayta kadar).

Uygulama yanıt vermiyor, başlatma sırasında başarısız oluyor veya normal şekilde çalışıyor

Uygulama yanıt vermemeye başladığında (yanıt vermeyi durdurduğunda ancak kilitlenmediğinde), başlatma sırasında başarısız olduğunda veya normal şekilde çalıştığında bkz . Kullanıcı Modu Döküm Dosyaları: Dökümü oluşturmak için uygun bir aracı seçmek için En İyi Aracı Seçme.

Dökümü analiz etme

Döküm, çeşitli yaklaşımlar kullanılarak analiz edilebilir. Daha fazla bilgi için bkz . Kullanıcı Modu Döküm Dosyasını Çözümleme.

Ek kaynaklar

• Örnek kodu görüntüleme veya indirme (indirme)
• Kestrel uç nokta yapılandırması (HTTPS yapılandırması ve SNI desteği içerir)
• ASP.NET Core'da .NET Genel Ana Bilgisayarı
• ASP.NET Core projelerinde sorun giderme ve hata ayıklama