csharp-scripts

C# スクリプト

使用する場合

• C# の概念、API、または言語機能を、手軽な単一ファイルのプログラムでテストする場合
• 大規模なプロジェクトに統合する前に、ロジックを試作する場合

使用しない場合

• 複数のファイルやプロジェクト参照を含む完全なプロジェクトが必要な場合
• 既存の .NET ソリューション内で作業しており、そこにコードを追加したい場合
• プログラムが大きすぎる、または複雑すぎて単一ファイルに収まらない場合

入力

入力	必須	説明
C# コードまたは目的	はい	実行するコード、またはスクリプトで行う処理の説明

ワークフロー

ステップ 1：.NET SDK のバージョンを確認する

dotnet --version を実行して SDK がインストールされていることを確認し、メジャーバージョンをメモします。ファイルベースアプリには .NET 10 以降が必要です。バージョンが 10 未満の場合は、代わりに古い SDK 向けの代替方法に従ってください。

ステップ 2：スクリプトファイルを作成する

トップレベルステートメントを使用して、単一の .cs ファイルを作成します。.csproj ファイルとの競合を避けるため、既存のプロジェクトディレクトリの外に配置してください。

// hello.cs
Console.WriteLine("Hello from a C# script!");

var numbers = new[] { 1, 2, 3, 4, 5 };
Console.WriteLine($"Sum: {numbers.Sum()}");

ガイドライン：

• トップレベルステートメントを使用します（Main メソッド、クラス、名前空間の定型コードは不要です）
• using ディレクティブはファイルの先頭に配置します
• 型宣言（クラス、レコード、列挙型）はすべてのトップレベルステートメントの後に配置します

ステップ 3：スクリプトを実行する

dotnet hello.cs

ファイルを自動的にビルドして実行します。結果はキャッシュされるため、2 回目以降の実行は高速です。引数は -- の後に渡します。

dotnet hello.cs -- arg1 arg2 "multi word arg"

ステップ 4：NuGet パッケージを追加する（必要な場合）

ファイルの先頭に #:package ディレクティブを指定して、NuGet パッケージを参照します。必ずバージョンを指定してください。

#:package [email protected]

using Humanizer;

Console.WriteLine("hello world".Titleize());

ステップ 5：後片付けをする

ユーザーがスクリプトを使い終えたら、スクリプトファイルを削除します。ビルド成果物のキャッシュを消去するには、次を実行します。

dotnet clean hello.cs

Unix のシバン対応

Unix プラットフォームでは、.cs ファイルを直接実行可能にできます。

1. ファイルの先頭行にシバンを追加します。

   #!/usr/bin/env dotnet
   Console.WriteLine("I'm executable!");
   

2. 実行権限を設定します。

   chmod +x hello.cs
   

3. 直接実行します。

   ./hello.cs
   

シバンを追加する場合は、改行コードに LF（CRLF ではなく）を使用してください。このディレクティブは Windows では無視されます。

ソース生成 JSON

ファイルベースアプリでは、既定でネイティブ AOT が有効になります。JsonSerializer.Serialize<T>(value) のようなリフレクションベースの API は、AOT では実行時に失敗します。代わりにソース生成シリアル化を使用してください。

using System.Text.Json;
using System.Text.Json.Serialization;

var person = new Person("Alice", 30);
var json = JsonSerializer.Serialize(person, AppJsonContext.Default.Person);
Console.WriteLine(json);

var deserialized = JsonSerializer.Deserialize(json, AppJsonContext.Default.Person);
Console.WriteLine($"Name: {deserialized!.Name}, Age: {deserialized.Age}");

record Person(string Name, int Age);

[JsonSerializable(typeof(Person))]
partial class AppJsonContext : JsonSerializerContext;

プロジェクトへの変換

スクリプトが単一ファイルでは収まらなくなったら、完全なプロジェクトに変換します。

dotnet project convert hello.cs

.NET 9 以前の代替方法

.NET SDK のバージョンが 10 未満の場合、ファイルベースアプリは使用できません。代わりに、一時的なコンソールプロジェクトを使用します。

mkdir -p /tmp/csharp-script && cd /tmp/csharp-script
dotnet new console -o . --force

生成された Program.cs をスクリプトの内容に置き換え、dotnet run で実行します。NuGet パッケージは dotnet add package <name> で追加します。作業が終わったらディレクトリを削除してください。

検証

• dotnet --version が 10.0 以降を報告する（または代替方法を使用している）
• スクリプトがエラーなしでコンパイルできる（dotnet build <file>.cs で明示的に確認できます）
• dotnet <file>.cs が期待どおりの出力を生成する
• セッション終了後にスクリプトファイルとキャッシュされた成果物が削除されている

よくある問題

問題	解決策
.cs ファイルが .csproj のあるディレクトリ内にある	スクリプトをプロジェクトディレクトリの外に移動するか、dotnet run --file file.cs を使用します
#:package にバージョンが指定されていない	バージョンを指定します：#:package [email protected]、または最新バージョンには @* を指定します
リフレクションベースの JSON シリアル化が失敗する	JsonSerializerContext を使用してソース生成 JSON を利用します（ソース生成 JSON を参照）
ビルドの動作やバージョンに予期しない問題がある	ファイルベースアプリは、親ディレクトリから global.json、Directory.Build.props、Directory.Build.targets、および nuget.config を継承します。継承された設定が競合する場合は、スクリプトを独立したディレクトリに移動してください

詳細情報

ファイルベースアプリの詳細については、https://learn.microsoft.com/en-us/dotnet/core/sdk/file-based-apps を参照してください。