Windows サービスでの ASP.NET Core のホスト

ASP.NET Core アプリは、IIS を 使用せずに、Windows サービスとして Windows にホストできます。 Windows サービスとしてホストされている場合、サーバーの再起動後にアプリが自動的に起動します。

前提条件

• ASP.NET Core SDK 7.0 以降
• PowerShell 6.2 以降

ワーカー サービス テンプレート

ASP.NET Core ワーカー サービス テンプレートは、実行時間が長いサービス アプリを作成する場合の出発点として利用できます。 テンプレートを Windows サービス アプリの基礎として使用するには:

1. .NET Core テンプレートからワーカー サービス アプリを作成します。
2. NuGet パッケージ Microsoft.Extensions.Hosting.WindowsServices をインストールします。
3. 「アプリの構成」セクションのガイダンスに従って、Windows サービスとして実行できるようにワーカー サービス アプリを更新します。

Visual Studio

1. 新しいプロジェクトを作成します。
2. [ワーカー サービス] を選択します。 [次へ] を選択します。
3. [プロジェクト名] フィールドにプロジェクト名を入力するか、既定のプロジェクト名をそのまま使用します。 作成 を選択します。
4. [新しい Worker サービスを作成します] ダイアログで、[作成] を選択します。

Visual Studio for Mac

1. 新しいプロジェクトを作成します。
2. サイドバーの [.NET Core] の下で [アプリ] を選択します。
3. [ASP.NET Core] の下の [ワーカー] を選択します。 [次へ] を選択します。
4. [ターゲット フレームワーク] で [.NET Core 3.0] またはそれ以降を選択します。 [次へ] を選択します。
5. [プロジェクト名] フィールドに名前を指定します。 [作成] を選択します。

.NET CLI

コマンド シェルから dotnet new コマンドと共にワーカー サービス (worker) テンプレートを使用します。 次の例では、ContosoWorker という名前のワーカー サービス アプリが作成されます。 このコマンドが実行されると、ContosoWorker アプリ用のフォルダーが自動的に作成されます。

dotnet new worker -o ContosoWorker

アプリの構成

Program.cs を更新して AddWindowsService を呼び出します。 アプリが Windows サービスとして実行している場合は、AddWindowsService:

• ホストの有効期間を WindowsServiceLifetime に設定します。
• コンテンツ ルートを AppContext.BaseDirectory に設定します。 詳しくは、「現在のディレクトリとコンテンツのルート」セクションをご覧ください。
• イベント ログへのログ記録を有効にします。
  • アプリケーション名が既定のソース名として使用されます。
  • 既定のログ レベルは、ホストを構築するために CreateDefaultBuilder が呼び出される ASP.NET Core テンプレートに基づくアプリに対して "警告" 以上です。
  • 既定のログ レベルを、appsettings.json/appsettings.{Environment}.json の Logging:EventLog:LogLevel:Default キーまたは他の構成プロバイダーでオーバーライドします。
  • 管理者のみが新しいイベント ソースを作成できます。 アプリケーション名を使用して、イベント ソースを作成できない場合、警告がアプリケーション ソースに記録され、イベント ログが無効になります。

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

次の Program.cs は、ServiceA を登録するために AddHostedServiceを呼び出します。

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

このトピックには、次のサンプル アプリが付属しています。

• バックグラウンド ワーカー サービスのサンプル: バックグラウンド タスク用にホステッド サービスを使用するワーカー サービス テンプレートに基づく、非 Web アプリのサンプルです。
• Web アプリ サービスのサンプル: バックグラウンド タスク用のホステッド サービスを使用する Windows サービスとして実行される Razor Pages Web アプリのサンプルです。

MVC のガイダンスについては、「ASP.NET Core MVC の概要」および「ASP.NET Core 2.2 から 3.0 への移行」にある記事を参照してください。

配置の種類

展開のシナリオに関する情報および注意事項については、「.NET Core アプリケーションの展開」をご覧ください。

SDK

Razor Pages または MVC フレームワークを使用する Web アプリ ベースのサービスでは、プロジェクト ファイルに Web SDK を指定します。

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

サービスでバックグラウンド タスク (ホステッド サービスなど) のみを実行する場合は、プロジェクト ファイルにワーカー SDK を指定します。

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

フレームワーク依存型展開 (FDD)

フレームワーク依存型展開 (FDD) は、ターゲット システムに .NET Core のシステム全体の共有バージョンが存在することに依存します。 この記事のガイダンスに従って、FDD シナリオを採用すると、フレームワーク依存型実行可能ファイル と呼ばれる実行可能ファイル ( .exe) が SDK によって生成されます。

Web SDK を使用している場合、web.config ファイル (通常 ASP.NET Core アプリを発行する際に生成されます) は、Windows サービス アプリに対しては必要ありません。 web.config ファイルの作成を無効にするには、true に設定した <IsTransformWebConfigDisabled> プロパティを追加します。

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

自己完結型の展開 (SCD)

自己完結型の展開 (SCD) は、ホスト システムに共有フレームワークが存在することに依存しません。 ランタイムとアプリの依存関係が、アプリと共に展開されます。

Windows ランタイム識別子 (RID) は、ターゲット フレームワークを格納する <PropertyGroup> に含まれます。

<RuntimeIdentifier>win-x64</RuntimeIdentifier>

複数の RID を発行するには、次の処理を実行します。

• セミコロンで区切られたリストの形式で RID を指定します。
• プロパティ名 <RuntimeIdentifiers> (複数) を使用します。

詳細については、「.NET Core の RID カタログ」を参照してください。

サービス ユーザー アカウント

サービス用のユーザー アカウントを作成するには、PowerShell 6 の管理コマンド シェルから New-LocalUser コマンドレットを使用します。

Windows 10 October 2018 Update (バージョン 1809/ビルド 10.0.17763) 以降:

New-LocalUser -Name {SERVICE NAME}

Windows 10 October 2018 Update (バージョン 1809/ビルド 10.0.17763) 以前の Windows OS:

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

入力を求められたら、強力なパスワードを指定します。

New-LocalUser コマンドレットに DateTime という有効期限で -AccountExpires パラメーターを指定しない場合、アカウントは期限切れになりません。

詳しくは、「Microsoft.PowerShell.LocalAccounts」および「Service User Accounts (サービス ユーザー アカウント)」をご覧ください。

Active Directory を使う場合、ユーザーを管理するための別の方法は、マネージド サービス アカウントを使うことです。 詳細については、「Group Managed Service Accounts Overview (グループ マネージド サービス アカウントの概要)」をご覧ください。

サービスとしてログオン権利

サービス ユーザー アカウントにサービスとしてログオン権利を確立するには、次の処理を実行します。

1. secpol.msc を実行して、ローカル セキュリティ ポリシー エディターを開きます。
2. [ローカル ポリシー] ノードを展開し、 [ユーザー権利の割り当て] を選択します。
3. [サービスとしてログオン] ポリシーを開きます。
4. [ユーザーまたはグループの追加] を選択します。
5. 次のいずれかの方法を使用して、オブジェクト名 (ユーザー アカウント) を指定します。
   1. オブジェクト名フィールドにユーザー アカウント ({DOMAIN OR COMPUTER NAME\USER}) を入力し、 [OK] を選択して、ポリシーにユーザーを追加します。
   2. [詳細] を選択します。 [検索開始] を選択します。 一覧からユーザー アカウントを選択します。 [OK] を選択します。 再度 [OK] を選択して、ポリシーにユーザーを追加します。
6. [OK] または [適用] を選択して、変更を受け入れます。

Windows サービスを作成して管理する

サービスを作成する

PowerShell コマンドを使用して、サービスを登録します。 PowerShell 6 の管理コマンド シェルから次のコマンドを実行します。

$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}: ホスト上のアプリの実行可能ファイルのパス (たとえば、d:\myservice)。 このパスに、アプリの実行可能ファイル名は含めないでください。 末尾のスラッシュは、必要ありません。
• {DOMAIN OR COMPUTER NAME\USER}:サービスのユーザー アカウント (Contoso\ServiceUser など)。
• {SERVICE NAME}:サービス名 (MyService など)。
• {EXE FILE PATH}: アプリの実行可能ファイルの完全なパス (d:\myservice\myservice.exe など)。 拡張子付きの実行可能ファイルのファイル名を含めます。
• {EXE FOLDER PATH}: アプリの実行可能ファイルの完全なフォルダー パス (d:\myservice など)。
• {DESCRIPTION}:サービスの説明 (My sample service など)。
• {DISPLAY NAME}:サービスの表示名 (My Service など)。

サービスを開始する

次の PowerShell 6 コマンドでサービスを開始します。

Start-Service -Name {SERVICE NAME}

このコマンドでサービスを開始するには数秒かかります。

サービスの状態を確認する

サービスの状態を確認するには、次の PowerShell 6 コマンドを使います。

Get-Service -Name {SERVICE NAME}

この状態は、次のいずれかの値として報告されます。

• Starting
• Running
• Stopping
• Stopped

サービスを停止する

次の PowerShell 6 コマンドでサービスを停止します。

Stop-Service -Name {SERVICE NAME}

サービスを削除する

サービスを停止した後、少ししてから、次の PowerShell 6 コマンドを使ってサービスを削除します。

Remove-Service -Name {SERVICE NAME}

プロキシ サーバーとロード バランサーのシナリオ

インターネットまたは企業ネットワークからの要求とやり取りするサービスやプロキシまたはロード バランサーの背後にあるサービスでは、追加の構成が必要になる場合があります。 詳細については、「プロキシ サーバーとロード バランサーを使用するために ASP.NET Core を構成する」を参照してください。

エンドポイントを構成する

既定では、ASP.NET Core は http://localhost:5000 にバインドされます。 ASPNETCORE_URLS 環境変数を設定して、URL とポートを構成します。

追加の URL とポートの構成方法については、関連するサーバーの記事を参照してください。

• ASP.NET Core Kestrel Web サーバーのエンドポイントを構成する
• ASP.NET Core での HTTP.sys Web サーバーの実装

上記のガイダンスでは、HTTPS エンドポイントのサポートについて説明しています。 たとえば、Windows サービスで認証が使用されている場合は、アプリを HTTPS 用に構成します。

Note

サービス エンドポイントをセキュリティで保護するために ASP.NET Core の HTTPS 開発証明書を使用することはできません。

現在のディレクトリとコンテンツのルート

Windows サービスに対して GetCurrentDirectory を呼び出して返される現在の作業ディレクトリは C:\WINDOWS\system32 フォルダーです。 system32 フォルダーは、サービスのファイル (設定ファイルなど) を保存するために適した場所ではありません。 次のいずれかの方法を使用して、サービスのアセットと設定ファイルを管理し、アクセスします。

ContentRootPath または ContentRootFileProvider を使用する

IHostEnvironment.ContentRootPath または ContentRootFileProvider を使用して、アプリのリソースを見つけます。

アプリがサービスとして実行されると、UseWindowsService によって ContentRootPath が AppContext.BaseDirectory に設定されます。

アプリの既定の設定ファイルである appsettings.json と appsettings.{Environment}.json は、ホストの構築中に CreateDefaultBuilder を呼び出すことで、アプリのコンテンツ ルートから読み込まれます。

ConfigureAppConfiguration の開発者コードによって読み込まれた他の設定ファイルについては、SetBasePath を呼び出す必要はありません。 次の例では、custom_settings.json ファイルはアプリのコンテンツ ルートに存在しており、明示的にベース パスを設定しなくても読み込まれます。

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

Windows サービス アプリから現在のディレクトリとして C:\WINDOWS\system32 フォルダーが返されるため、GetCurrentDirectory を使用してリソース パスを取得しないでください。

ディスク上の適切な場所にサービスのファイルを格納する

ファイルを含むフォルダーに対して IConfigurationBuilder を使用するときは、SetBasePath を使用して絶対パスを指定します。

トラブルシューティング

Windows サービス アプリのトラブルシューティングについては、「ASP.NET Core プロジェクトのトラブルシューティングとデバッグ」を参照してください。

一般的なエラー

• PowerShell の以前のバージョンまたはプレリリース バージョンが使用されています。
• 登録されたサービスに、dotnet publish コマンドからのアプリの発行済み出力が使用されません。 dotnet build コマンドの出力が、アプリの展開でサポートされていません。 発行された資産は、展開の種類に応じて次のいずれかのフォルダーにあります。
  • bin/Release/{TARGET FRAMEWORK}/publish (FDD)
  • bin/Release/{TARGET FRAMEWORK}/{RUNTIME IDENTIFIER}/publish (SCD)
• サービスが実行中の状態ではありません。
• アプリに使用されるリソース (証明書など) のパスが正しくありません。 Windows サービスのベース パスは、c:\Windows\System32 です。
• "サービスとしてログオンする" アクセス権がユーザーにありません。
• New-Service PowerShell コマンドの実行時に、ユーザーのパスワードの有効期限が切れていたか、正しく渡されていません。
• アプリに ASP.NET Core 認証が必要ですが、セキュリティで保護された接続 (HTTPS) 用に構成されていません。
• 要求 URL ポートが正しくないか、アプリで正しく構成されていません。

システム イベント ログとアプリケーション イベント ログ

システム イベント ログとアプリケーション イベント ログにアクセスします。

1. [スタート] メニューを開き、イベント ビューアーを検索し、イベント ビューアー アプリを選択します。
2. イベント ビューアーで [Windows ログ] ノードを開きます。
3. [システム] を選択してシステム イベント ログを開きます。 [Application] を選択して、アプリケーション イベント ログを開きます。
4. 失敗したアプリに関連するエラーを検索します。

コマンド プロンプトでアプリを実行する

多くのスタートアップ エラーでは、イベント ログに有用な情報が生成されません。 ホスティング システムのコマンド プロンプトでアプリを実行すると、エラーの原因がわかることがあります。 アプリからさらに詳細情報をログに記録するには、ログ レベルを低くするか、開発環境でアプリを実行します。

パッケージ キャッシュをクリアする

開発マシンで .NET Core SDK をアップグレードしたり、アプリ内のパッケージ バージョンを変更したりした直後に、機能しているアプリが失敗することがあります。 場合によっては、パッケージに統一性がないと、メジャー アップグレード実行時にアプリが破壊されることがあります。 これらの問題のほとんどは、次の手順で解決できます。

1. bin フォルダーと obj フォルダーを削除します。

2. コマンド シェルから dotnet nuget locals all --clear を実行して、パッケージ キャッシュをクリアします。

   パッケージ キャッシュをクリアするには、nuget.exe ツールを使用して nuget locals all -clear コマンドを実行する方法もあります。 nuget.exe は、Windows デスクトップ オペレーティング システムにバンドルされているインストールではなく、NuGet Web サイトから別に入手する必要があります。

3. プロジェクトを復元してリビルドします。

4. アプリを再展開する前に、サーバー上の展開フォルダー内のすべてのファイルを削除します。

低速または応答しないアプリ

"クラッシュ ダンプ" とはシステムのメモリのスナップショットであり、アプリのクラッシュ、起動の失敗、遅いアプリの原因を突き止めるのに役立ちます。

アプリのクラッシュまたは例外の発生

Windows エラー報告 (WER) からダンプを取得して分析します。

1. c:\dumps にクラッシュ ダンプ ファイルを保持するフォルダーを作成します。

2. 次のアプリケーションの実行可能ファイル名で EnableDumps PowerShell スクリプトを実行します。

   .\EnableDumps {APPLICATION EXE} c:\dumps
   

3. クラッシュが発生する条件の下でアプリを実行します。

4. クラッシュが発生した後、DisableDumps PowerShell スクリプトを実行します。

   .\DisableDumps {APPLICATION EXE}
   

アプリがクラッシュし、ダンプの収集が完了したら、アプリを普通に終了してかまいません。 PowerShell スクリプトにより、アプリごとに最大 5 つのダンプを収集する WER が構成されます。

警告

クラッシュ ダンプでは、大量のディスク領域 (1 つにつき最大、数ギガバイト) が使用される場合があります。

アプリが起動時または正常な実行中に応答しなくなる、または失敗する

アプリが起動時または正常な実行中に応答を停止するがクラッシュしない、または失敗するときは、「ユーザーモード ダンプ ファイル: 最適なツールの選択」を参照し、適切なツールを選択してダンプを生成します。

ダンプを分析する

ダンプはいくつかの方法で分析できます。 詳細については、「Analyzing a User-Mode Dump File」(ユーザー モード ダンプ ファイルの分析) を参照してください。

その他の技術情報

• サンプル コードを表示またはダウンロードします (ダウンロード方法)。
• Kestrel エンドポイント構成 (HTTPS 構成と SNI サポートを含む)
• ASP.NET Core の .NET 汎用ホスト
• ASP.NET Core プロジェクトのトラブルシューティングとデバッグ