【C#】async Main完全ガイド｜Top-level statements・IHost・Ctrl+C・Graceful Shutdown・終了コードまで

// ① 同期 void: 最もシンプル
class Program1
{
    static void Main(string[] args)
    {
        Console.WriteLine($"args: {string.Join(",", args)}");
    }
}

// ② 同期 int: 終了コードを返す（CI / シェルスクリプトで有用）
class Program2
{
    static int Main(string[] args)
    {
        if (args.Length == 0)
        {
            Console.Error.WriteLine("引数が必要です");
            return 1;           // 異常終了
        }
        Process(args);
        return 0;                // 正常終了
    }
}

// ③ 非同期 Task: async/await を直接使える
class Program3
{
    static async Task Main(string[] args)
    {
        using var http = new HttpClient();
        string data = await http.GetStringAsync("https://api.example.com");
        Console.WriteLine(data);
    }
}

// ④ 非同期 Task<int>: 非同期 + 終了コード
class Program4
{
    static async Task<int> Main(string[] args)
    {
        try
        {
            await ExecuteAsync(args);
            return 0;
        }
        catch (Exception ex)
        {
            Console.Error.WriteLine(ex.Message);
            return 1;
        }
    }
}

// NG: async void は不可（Main では許されていない）
// static async void Main() { ... }  // コンパイルエラー CS5001

// C# 9 以降: Program.cs の冒頭にコードを書くだけで実行される
// クラス・Main メソッド・namespace が不要

// Program.cs
using System;

Console.WriteLine("Hello, World!");
await Task.Delay(1000);
Console.WriteLine("1秒経過");

// args はそのまま args 変数として使える
Console.WriteLine($"引数: {args.Length} 個");

// 終了コードも return で返せる
if (args.Length == 0)
    return 1;

return 0;

// コンパイラが裏で生成するコード（概念）
// internal class Program
// {
//     private static async Task<int> Main(string[] args)
//     {
//         Console.WriteLine("Hello, World!");
//         await Task.Delay(1000);
//         // ...
//         return 0;
//     }
// }

// 制約:
// - トップレベルステートメントは1プロジェクトに1ファイルまで
// - using や namespace はステートメントより先に書く
// - メソッド / クラス定義はステートメントより後に書く

// ソース: async Main
static async Task<int> Main(string[] args)
{
    await DoWorkAsync();
    return 0;
}

// コンパイラが生成する実体（概念）
// - CLR のエントリポイントは常に同期メソッド
// - async メソッドは .GetAwaiter().GetResult() で同期的に待つラッパーが挿入される
private static int $Main(string[] args)
{
    return Main(args).GetAwaiter().GetResult();
}

// 重要:
// - SynchronizationContext は Main では null（既定）
// - そのため .GetAwaiter().GetResult() でもデッドロックしない
// - ASP.NET Core の旧 Classic / UI スレッドで問題になる
//   「sync-over-async デッドロック」は Main では発生しない

static async Task<int> Main(string[] args)
{
    try
    {
        using var cts = new CancellationTokenSource();
        Console.CancelKeyPress += (_, e) =>
        {
            e.Cancel = true;   // デフォルトのプロセス即終了を防ぐ
            cts.Cancel();
        };

        await RunAsync(args, cts.Token);
        return 0;
    }
    catch (OperationCanceledException)
    {
        Console.Error.WriteLine("中止されました");
        return 130;   // SIGINT 慣習
    }
    catch (ArgumentException ex)
    {
        Console.Error.WriteLine($"引数エラー: {ex.Message}");
        return 2;
    }
    catch (Exception ex)
    {
        Console.Error.WriteLine($"エラー: {ex.Message}");
        return 1;
    }
}

// Environment.ExitCode でも終了コードは設定可能
Environment.ExitCode = 42;
// → main が return する値、または明示的な Environment.Exit() で採用される

// Environment.Exit(42) は「即時プロセス終了」なので finally / Dispose が走らない
// → 通常は return で終了コードを返す方が安全

static async Task<int> Main(string[] args)
{
    using var cts = new CancellationTokenSource();

    // Ctrl+C（SIGINT）を捕まえてトークンをキャンセル
    Console.CancelKeyPress += (sender, e) =>
    {
        Console.WriteLine("\nCtrl+C を検知 — 停止処理を開始");
        e.Cancel = true;           // ★ 即プロセス終了を防ぐ
        cts.Cancel();              // キャンセル伝搬
    };

    try
    {
        await ProcessAsync(cts.Token);
        return 0;
    }
    catch (OperationCanceledException)
    {
        Console.WriteLine("正常に中止されました");
        return 130;
    }
}

// アプリ側は渡された CancellationToken を全ての非同期呼び出しに伝搬させる
static async Task ProcessAsync(CancellationToken ct)
{
    for (int i = 0; i < 100; i++)
    {
        ct.ThrowIfCancellationRequested();
        await Task.Delay(100, ct);
        Console.WriteLine($"処理 {i}");
    }
}

// Linux / Docker / Kubernetes では SIGTERM で停止要求が来る
// .NET 6+ の IHostApplicationLifetime が自動で SIGTERM を捕捉する

// 手動でハンドルする場合（.NET 6+）
AppDomain.CurrentDomain.ProcessExit += (sender, e) =>
{
    Console.WriteLine("ProcessExit を検知 — クリーンアップ");
    // 注: ProcessExit ハンドラの実行時間は約 2〜3 秒に制限される
    // 長時間の後処理は IHostApplicationLifetime.ApplicationStopping で行う
};

// PosixSignalRegistration（.NET 7+）でより細かく制御できる
using var sigTerm = PosixSignalRegistration.Create(PosixSignal.SIGTERM, ctx =>
{
    Console.WriteLine("SIGTERM を受信");
    ctx.Cancel = true;  // デフォルトの終了動作をキャンセル
    // 自前で終了処理を開始
});

using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Logging;

// 最小構成の Console アプリ（.NET 7+）
// .NET 6 以前では Host.CreateDefaultBuilder(args).Build() を使う
var builder = Host.CreateApplicationBuilder(args);

// 設定（appsettings.json が自動読み込み）
builder.Services.Configure<AppOptions>(
    builder.Configuration.GetSection("App"));

// サービス登録
builder.Services.AddHttpClient();
builder.Services.AddTransient<OrderService>();

using var host = builder.Build();

// DI から取り出して実行
var svc = host.Services.GetRequiredService<OrderService>();
await svc.RunAsync(host.Services.GetRequiredService<IHostApplicationLifetime>().ApplicationStopping);

// IHostApplicationLifetime を経由すると:
// - Ctrl+C → ApplicationStopping がキャンセル
// - SIGTERM → 同じく
// - アプリの Dispose タイミングが統一される

// OrderService 側
public class OrderService(HttpClient http, ILogger<OrderService> logger, IOptions<AppOptions> opt)
{
    public async Task RunAsync(CancellationToken ct)
    {
        logger.LogInformation("処理開始: {BaseUrl}", opt.Value.BaseUrl);
        string body = await http.GetStringAsync(opt.Value.BaseUrl, ct);
        logger.LogInformation("取得完了: {Length} 文字", body.Length);
    }
}

// 定期実行・常駐処理は BackgroundService を使うのが定石
var builder = Host.CreateApplicationBuilder(args);
builder.Services.AddHostedService<PollingWorker>();

using var host = builder.Build();
await host.RunAsync();   // Ctrl+C / SIGTERM で終了

public class PollingWorker(ILogger<PollingWorker> logger) : BackgroundService
{
    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        while (!stoppingToken.IsCancellationRequested)
        {
            logger.LogInformation("ポーリング実行");
            await Task.Delay(TimeSpan.FromMinutes(1), stoppingToken);
        }
    }
}

static async Task<int> Main(string[] args)
{
    // ① 観測されなかった Task の例外
    TaskScheduler.UnobservedTaskException += (sender, e) =>
    {
        Console.Error.WriteLine($"UnobservedTask: {e.Exception}");
        e.SetObserved();   // プロセスを落とさない
    };

    // ② どこでもキャッチされなかった例外の最後の砦
    AppDomain.CurrentDomain.UnhandledException += (sender, e) =>
    {
        // このハンドラの後は必ずプロセス終了する（.NET 4+ 既定）
        var ex = e.ExceptionObject as Exception;
        Console.Error.WriteLine($"Unhandled: {ex}");
    };

    try
    {
        await RunAsync(args);
        return 0;
    }
    catch (OperationCanceledException)
    {
        return 130;   // Ctrl+C
    }
    catch (Exception ex)
    {
        Console.Error.WriteLine($"Fatal: {ex}");
        return 1;
    }
}

// Serilog 等のログ基盤を使う場合は
// catch で logger.LogCritical → Log.CloseAndFlush を必ず呼ぶ

// ① args パラメーター（最もシンプル）
// 実行: dotnet run -- --verbose 10
static async Task Main(string[] args)
{
    bool verbose = args.Contains("--verbose");
    int count = int.Parse(args.SkipWhile(a => a != "--count").Skip(1).FirstOrDefault() ?? "0");
}

// トップレベルステートメントでも args はそのまま使える
// Console.WriteLine($"args: {string.Join(",", args)}");

// ② Environment.GetCommandLineArgs() — 第1要素は実行ファイルのパス
string[] all = Environment.GetCommandLineArgs();
// all[0] = "MyApp.exe"（またはフルパス）
// all[1..] = 実際の引数

// ③ 環境変数
string? apiKey = Environment.GetEnvironmentVariable("API_KEY");
string workDir = Environment.GetEnvironmentVariable("WORK_DIR") ?? ".";

// ④ System.CommandLine（.NET 8+ 公式ライブラリ）— 本格的な CLI
// dotnet add package System.CommandLine --prerelease
var rootCommand = new RootCommand("サンプルアプリ");
var nameOption = new Option<string>("--name") { IsRequired = true };
rootCommand.AddOption(nameOption);
rootCommand.SetHandler(async (name) =>
{
    Console.WriteLine($"Hello, {name}");
    await Task.Delay(100);
}, nameOption);
return await rootCommand.InvokeAsync(args);

// Before (C# 7.0 以前): sync Main から Wait / GetAwaiter
class OldProgram
{
    static void Main(string[] args)
    {
        DoWorkAsync().GetAwaiter().GetResult();
        // または .Wait()
    }

    static async Task DoWorkAsync()
    {
        await Task.Delay(1000);
    }
}

// After (C# 7.1+): async Main
class NewProgram
{
    static async Task Main(string[] args)
    {
        await DoWorkAsync();
    }

    static async Task DoWorkAsync()
    {
        await Task.Delay(1000);
    }
}

// After (C# 9+): トップレベルステートメント
// Program.cs
await DoWorkAsync();

static async Task DoWorkAsync()
{
    await Task.Delay(1000);
}

// After (.NET 6+): IHost + DI（本格的なアプリ）
using var host = Host.CreateApplicationBuilder(args).Build();
var svc = host.Services.GetRequiredService<IMyService>();
await svc.ExecuteAsync();

// 移行のメリット:
// - スタックトレースが綺麗（GetAwaiter().GetResult() のノイズがない）
// - 例外処理が自然
// - CancellationToken を自然に伝搬できる

// NG: コンパイルエラー
// static async void Main(string[] args) { ... }
//   → CS5001: Program does not contain a static Main method

// OK: async Task Main を使う
static async Task Main(string[] args) { ... }

// 理由: void async では呼び出し側が完了を待てないため、
//   CLR のエントリポイントとして成立しない

// NG: fire-and-forget タスクを放置すると Main が先に終わって処理が完了しない
static async Task Main(string[] args)
{
    _ = LongRunningAsync();    // 結果を待たない
    // ここで Main が return → LongRunningAsync の続きは実行されない可能性
}

// OK: 必ず await する
static async Task Main(string[] args)
{
    await LongRunningAsync();
}

// 複数タスクを並行に実行する場合は Task.WhenAll
static async Task Main(string[] args)
{
    await Task.WhenAll(Task1Async(), Task2Async(), Task3Async());
}

// NG: HttpClient が Dispose されずにプロセスが終わる
static async Task Main(string[] args)
{
    var http = new HttpClient();
    await http.GetStringAsync("https://api.example.com");
    // Main が終わって http が GC されるが、接続プールが残ることがある
}

// OK: using で明示的に解放
static async Task Main(string[] args)
{
    using var http = new HttpClient();
    await http.GetStringAsync("https://api.example.com");
}   // ← ここで Dispose

// IAsyncDisposable なら await using
static async Task Main(string[] args)
{
    await using var dbContext = new AppDbContext();
    await dbContext.SaveChangesAsync();
}

// Program.cs（トップレベル）
await DoAsync();

// ローカル関数はトップレベルの下に書く
static async Task DoAsync()
{
    await Task.Delay(100);
}

// クラス定義もトップレベルの下に書く（C# 10+）
public class MyHelper
{
    public static void Log() => Console.WriteLine("log");
}

MyHelper.Log();   // ステートメント内から使える（宣言が後でも OK）