dotnet-aspire

Name: dotnet-aspire
Author: markpitt

github.com/markpitt開発24103 回インストール36 週間前に更新

dotnet-aspire について

.NET Aspire Integration Skill は、既存の .NET ソリューションへの .NET Aspire 導入や、Aspire を使った分散アプリケーション作成のためのモジュール式ガイドです。サービスのオーケストレーション、検出、構成、可観測性、リソース統合、デプロイを扱います。

主な機能

01AppHost と ServiceDefaults の設定ガイド
02サービスのオーケストレーションと検出パターン
03構成とシークレットの管理ガイド
04可観測性とローカルダッシュボードの設定
05リソース統合とデプロイのガイド

活用シーン

01複数サービスの .NET ソリューションへの Aspire 導入
02Aspire 対応の分散アプリケーション作成
03ローカルサービスのオーケストレーション設定
04クラウドデプロイ構成の準備

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/markpitt/claude-skills --skill dotnet-aspire

インストール後、Claude Code で/dotnet-aspireを入力して読み込まれたか確認します。

同梱ファイル

SKILL.md と一緒にインストールされる参考資料やスクリプト。

resources/

components.md

configuration-management.md

deployment.md

local-development.md

service-communication.md

詳細

.NET Aspire 統合スキル

このスキルは、既存の .NET ソリューションへの .NET Aspire の追加や、Aspire 対応の新しい分散アプリケーションの作成を支援します。オーケストレーション、サービスディスカバリー、コンポーネント統合、構成管理、デプロイに関するモジュール式のガイダンスを提供します。

.NET Aspire とは？

.NET Aspire は、可観測性と本番運用への対応を重視した、クラウド対応の分散アプリケーション構築スタックです。次の機能を提供します。

サービスオーケストレーション - 依存関係を管理しながら、複数のプロジェクトやサービスを連携させます
サービスディスカバリー - サービス間の検出と接続を自動化します
テレメトリと可観測性 - ロギング、メトリクス、分散トレーシングを標準で備えています
構成管理 - 強い型付けとシークレットに対応した一元的な構成管理を提供します
リソースのプロビジョニング - データベース、キャッシュ、メッセージング、クラウドサービスと統合します
開発者ダッシュボード - ローカルでの監視とデバッグのためのインターフェースを提供します

このスキルを使う場面

次のような場合にこのスキルを使用してください。

複数のサービスを含む既存の .NET ソリューションに Aspire を追加する
Aspire を使用した新しい分散アプリケーションを作成する
クラウドへのデプロイに向けて、マイクロサービスや分散システムをモダナイズする
ローカル開発とデプロイのためのサービスオーケストレーションを設定する
クラウドネイティブな可観測性と構成のパターンを統合する

必要なコンポーネント／機能は？

必要なもの	リソース	説明
全体構成	概要とセットアップ	分析から実行までの段階的な実装手順
データベース、キャッシュ、メッセージング	`resources/components.md`	利用可能なすべての Aspire コンポーネントパッケージと使用例
サービス間通信	`resources/service-communication.md`	サービスディスカバリー、HttpClient のパターン、レジリエンス
構成とシークレット	`resources/configuration-management.md`	環境設定、シークレット、機能フラグ
ローカル開発	`resources/local-development.md`	ダッシュボード、デバッグ、テスト、ヘルスチェック
本番環境へのデプロイ	`resources/deployment.md`	Azure Container Apps、Kubernetes、Docker Compose

概要とセットアップ

基本概念

.NET Aspire では、次の 2 つのプロジェクトを使用します。

AppHost - サービスとリソースをオーケストレーションし、開発者ダッシュボードを提供します
ServiceDefaults - すべてのサービスで共有する構成（OpenTelemetry、ヘルスチェック、サービスディスカバリー）を管理します

前提条件

# Install .NET Aspire workload
dotnet workload install aspire

# Verify installation
dotnet workload list  # Should show "aspire"

# Docker Desktop (for container resources)
# Ensure it's running before launching AppHost

基本的な実装の流れ

1. ソリューションを分析する

サービスを特定します（API、Web アプリ、ワーカー）
外部依存関係を一覧にします（データベース、Redis、メッセージキュー）
サービス間の通信パターンを特定します

2. Aspire プロジェクトを作成する

dotnet new aspire-apphost -n MyApp.AppHost
dotnet new aspire-servicedefaults -n MyApp.ServiceDefaults
dotnet sln add MyApp.AppHost/MyApp.AppHost.csproj
dotnet sln add MyApp.ServiceDefaults/MyApp.ServiceDefaults.csproj

3. サービスを構成する

各サービスに ServiceDefaults への参照を追加します
Program.cs で builder.AddServiceDefaults() を呼び出します
ASP.NET Core サービスでは app.MapDefaultEndpoints() を呼び出します

4. AppHost でオーケストレーションする

var builder = DistributedApplication.CreateBuilder(args);

var cache = builder.AddRedis("cache");
var database = builder.AddPostgres("postgres").AddDatabase("appdb");

var api = builder.AddProject<Projects.MyApi>("api")
    .WithReference(database)
    .WithReference(cache);

var web = builder.AddProject<Projects.MyWeb>("web")
    .WithReference(api)
    .WithExternalHttpEndpoints();

builder.Build().Run();

5. サービス間通信を更新する

ハードコードされた URL をサービス名に置き換えます
builder.AddServiceDefaults() のパターンに合わせて設定します

6. 実行して検証する

dotnet run --project MyApp.AppHost
# Opens dashboard at https://localhost:15001

主な決定事項

AppHost プロジェクトの命名：

慣例：[SolutionName].AppHost
例：ソリューション名が「ECommerceSystem」の場合、「ECommerceSystem.AppHost」を作成します

サービスリソース名：

AppHost では短く、わかりやすい名前を使います
例：「api」、「web」、「worker」、「cache」、「database」
これらの名前はサービスディスカバリーの URL に使用されます

リソース管理：

ローカル開発：Aspire が管理するコンテナー（PostgreSQL、Redis、RabbitMQ）を使用します
本番環境：azd による自動プロビジョニング、または手動で構成した Azure リソースを使用します
接続文字列：自動的に注入されるため、ハードコードが必要になることはほとんどありません

サービスディスカバリーの設定：

HttpClient の URL にはサービス名を使用します。例：https://localhost:7001 ではなく http://api
Aspire がサービス間のルーティングと認証を処理します
外部サービスには、エンドポイントを明示的に構成します

一般的なアーキテクチャ

Web API + フロントエンド

var api = builder.AddProject<Projects.Api>("api")
    .WithReference(database)
    .WithExternalHttpEndpoints();

var web = builder.AddProject<Projects.Web>("web")
    .WithReference(api)
    .WithExternalHttpEndpoints();

メッセージキューを使用したマイクロサービス

var messaging = builder.AddRabbitMQ("messaging");

var orderService = builder.AddProject<Projects.OrderService>("orders")
    .WithReference(messaging);

var inventoryService = builder.AddProject<Projects.InventoryService>("inventory")
    .WithReference(messaging);

マルチデータベースシステム

var postgres = builder.AddPostgres("postgres")
    .AddDatabase("users")
    .AddDatabase("products");

var mongo = builder.AddMongoDB("mongo")
    .AddDatabase("orders");

var userApi = builder.AddProject<Projects.UserApi>("userapi")
    .WithReference(postgres);

var orderApi = builder.AddProject<Projects.OrderApi>("orderapi")
    .WithReference(mongo);

リソースインデックス

実装の詳細なガイダンスについては、以下を参照してください。

コンポーネント - コンポーネントパッケージと統合パターン：resources/components.md
サービス間通信 - サービスディスカバリーとサービス間呼び出し：resources/service-communication.md
構成管理 - シークレット、環境変数、設定：resources/configuration-management.md
ローカル開発 - ダッシュボード機能、デバッグ、ヘルスチェック：resources/local-development.md
デプロイ - Azure Container Apps、Kubernetes、Docker Compose：resources/deployment.md

ベストプラクティス

サービスの構成

AppHost はビジネスロジックではなく、構成に重点を置きます
横断的関心事（可観測性、ヘルスチェック）には ServiceDefaults を使用します
各サービスがフォールバック構成で独立して実行できるようにします

リソース管理

ローカル開発の一貫性を保つため、Aspire が管理するリソースを使用します
.WithReference() を使って AppHost に明示的な依存関係を定義します
データベースにはデータ永続化を追加します：.WithDataVolume()

構成パターン

開発：appsettings.Development.json と .WithEnvironment() を使用します
本番環境：Azure Key Vault またはマネージドシークレットを使用します
ソース管理にシークレットを含めないようにし、ローカルではユーザーシークレットを使用します

可観測なサービス

ServiceDefaults を介して OpenTelemetry を有効にします（自動）
ローカルでのデバッグには開発者ダッシュボードを使用します
本番環境では Application Insights などにテレメトリをエクスポートします

よくある問題と解決策

サービス間で通信できない

AppHost のサービス名が HttpClient の URL と一致していることを確認します
すべてのサービスで AddServiceDefaults() が呼び出されていることを確認します
ASP.NET サービスで MapDefaultEndpoints() が呼び出されていることを確認します

接続文字列が注入されない

手動で構成する代わりに builder.AddNpgsqlDbContext<>() を使用します
AppHost とサービス間でデータベース／リソース名が一致していることを確認します
プロジェクトファイルに ServiceDefaults への参照があることを確認します

ダッシュボードが起動しない

Docker Desktop が実行中であることを確認します
ポートの競合がないか確認します（デフォルト：15001）
個々のサービスではなく、AppHost プロジェクトが実行されていることを確認します

ヘルスチェックが失敗する

ダッシュボードでリソースの起動ログを確認します
ローカルマシンでポートが利用可能か確認します
Docker に十分なリソースがあることを確認します

開始前チェックリスト

次のステップ

コンポーネントの詳細について → resources/components.md を参照してください
サービス間通信について → resources/service-communication.md を参照してください
構成について → resources/configuration-management.md を参照してください
ローカル開発について → resources/local-development.md を参照してください
デプロイについて → resources/deployment.md を参照してください

注意：まず単一のサービスから始め、通信が機能することを確認してから、複雑さを加えてください。本番環境にデプロイする前に、ダッシュボードを使ってローカルで問題をデバッグしてください。

どのプロジェクトをサービスとしてオーケストレーションする必要がありますか？
どのような外部リソースが必要ですか（データベース、Redis、ストレージなど）？
最小限の Aspire セットアップを使用しますか、それとも追加のコンポーネントを含めますか？
既存の Docker またはオーケストレーション構成はありますか？

2. 確認事項

実装を始める前に、ユーザーに確認します。

サービスの特定：

「ソリューション内で [X] 個のサービスを特定しました：[list]。これらすべてを Aspire のオーケストレーションに含めますか？」
「追加するサービスやプロジェクトはありますか？」

インフラストラクチャの要件：

「[database/Redis/etc.] への参照が見つかりました。これらのリソースを Aspire で管理しますか？」
「コンテナーリソースと接続文字列の設定のどちらを使用しますか？」

Aspire の構成：

「新しい AppHost プロジェクト '[SolutionName].AppHost' と ServiceDefaults プロジェクト '[SolutionName].ServiceDefaults' を作成しますか？」
「特定の命名規則を希望しますか？」

依存関係：

「どのサービスが互いに依存していますか？（これはサービス検出の設定に役立ちます）」
「起動順序に関する要件はありますか？」

3. 実装手順

手順 1：Aspire プロジェクトを作成する

AppHost プロジェクトを作成します：

dotnet new aspire-apphost -n [SolutionName].AppHost

AppHost プロジェクトは以下を行います。

すべてのサービスとリソースをオーケストレーションします
サービスの依存関係と構成を定義します
ローカル開発用の開発者ダッシュボードを提供します
アプリケーションの構成を含む Program.cs を格納します

ServiceDefaults プロジェクトを作成します：

dotnet new aspire-servicedefaults -n [SolutionName].ServiceDefaults

ServiceDefaults プロジェクトは以下を行います。

共通のサービス構成を提供します
OpenTelemetry、ヘルスチェック、サービス検出を設定します
一貫した動作のため、すべてのサービスに適用されます

プロジェクトをソリューションに追加します：

dotnet sln add [SolutionName].AppHost/[SolutionName].AppHost.csproj
dotnet sln add [SolutionName].ServiceDefaults/[SolutionName].ServiceDefaults.csproj

手順 2：サービスプロジェクトを構成する

各サービスプロジェクト（API、Web アプリ、ワーカー）について：

ServiceDefaults への参照を追加します：

dotnet add [ServiceProject] reference [SolutionName].ServiceDefaults/[SolutionName].ServiceDefaults.csproj

Program.cs を更新して、サービスの既定値を登録します：

// At the top of Program.cs, after builder creation
var builder = WebApplication.CreateBuilder(args);

// Add this line
builder.AddServiceDefaults();

// ... rest of service configuration ...

var app = builder.Build();

// Add this line before app.Run()
app.MapDefaultEndpoints();

app.Run();

ワーカーサービスの場合も、同様のパターンを使用します：

var builder = Host.CreateApplicationBuilder(args);

builder.AddServiceDefaults();

// ... service configuration ...

var host = builder.Build();
host.Run();

手順 3：AppHost を構成する

AppHost にプロジェクト参照を追加します：

dotnet add [SolutionName].AppHost reference [ServiceProject1]/[ServiceProject1].csproj
dotnet add [SolutionName].AppHost reference [ServiceProject2]/[ServiceProject2].csproj

AppHost の Program.cs を更新して、サービスをオーケストレーションします。

var builder = DistributedApplication.CreateBuilder(args);

// Add infrastructure resources
var cache = builder.AddRedis("cache");
var postgres = builder.AddPostgres("postgres")
    .AddDatabase("appdb");

// Add services with dependencies
var apiService = builder.AddProject<Projects.MyApi>("apiservice")
    .WithReference(postgres)
    .WithReference(cache);

var webApp = builder.AddProject<Projects.MyWebApp>("webapp")
    .WithReference(apiService)
    .WithExternalHttpEndpoints();

builder.Build().Run();

一般的なリソースメソッド：

.AddRedis("name") - Redis キャッシュ
.AddPostgres("name").AddDatabase("dbname") - PostgreSQL
.AddSqlServer("name").AddDatabase("dbname") - SQL Server
.AddRabbitMQ("name") - RabbitMQ メッセージング
.AddMongoDB("name").AddDatabase("dbname") - MongoDB
.AddAzureStorage("name") - Azure Storage

サービス構成メソッド：

.WithReference(resource) - 依存関係を追加し、接続情報を注入します
.WithExternalHttpEndpoints() - サービスへの外部アクセスを可能にします
.WithReplicas(count) - 複数のインスタンスを実行します
.WithEnvironment("KEY", "value") - 環境変数を追加します
.WithHttpsEndpoint(port: 7001) - HTTPS ポートを指定します

手順 4：必要な NuGet パッケージを追加する

Aspire パッケージはテンプレートによって自動的に追加されますが、次のパッケージが含まれていることを確認してください。

AppHost プロジェクト：

Aspire.Hosting.AppHost（通常はワークロード経由で含まれます）
リソース用の追加ホスティングパッケージ（例：Aspire.Hosting.PostgreSQL）

ServiceDefaults プロジェクト：

Microsoft.Extensions.Http.Resilience
Microsoft.Extensions.ServiceDiscovery
OpenTelemetry.Exporter.OpenTelemetryProtocol
OpenTelemetry.Extensions.Hosting
OpenTelemetry.Instrumentation.AspNetCore
OpenTelemetry.Instrumentation.Http
OpenTelemetry.Instrumentation.Runtime

サービスプロジェクト：

Aspire.Npgsql.EntityFrameworkCore.PostgreSQL（PostgreSQL を使用する場合）
Aspire.StackExchange.Redis（Redis を使用する場合）
データベース、メッセージングなどに必要なコンポーネントパッケージ

パッケージをインストールします：

dotnet add [Project] package [PackageName]

手順 5：サービス間通信を更新する

**他のサービスを呼び出すサービスでは、**サービス検出を使用します。

変更前（URL をハードコード）：

builder.Services.AddHttpClient("apiservice", client =>
{
    client.BaseAddress = new Uri("https://localhost:7001");
});

変更後（サービス検出）：

builder.Services.AddHttpClient("apiservice", client =>
{
    client.BaseAddress = new Uri("http://apiservice");
});

サービス名は、AppHost の AddProject<>() 呼び出しで指定した名前と一致します。

型付き HttpClient の場合：

builder.Services.AddHttpClient<IApiClient, ApiClient>(client =>
{
    client.BaseAddress = new Uri("http://apiservice");
});

手順 6：構成と接続文字列

リソースの接続文字列は自動的に注入されます。サービスの構成を更新します。

変更前：

builder.Services.AddDbContext<AppDbContext>(options =>
    options.UseNpgsql(builder.Configuration.GetConnectionString("DefaultConnection")));

変更後：

builder.AddNpgsqlDbContext<AppDbContext>("appdb");

接続名（「appdb」）は、AppHost のデータベース名と一致します。

Redis の場合：

builder.AddRedisClient("cache");

ステップ 7：検証とテスト

AppHost プロジェクトを実行します：

dotnet run --project [SolutionName].AppHost

次が起動します：

Aspire ダッシュボード（通常は https://localhost:15001）
設定済みのすべてのサービス
リソースコンテナー（Redis、PostgreSQL など）

確認項目：

ダッシュボードですべてのサービスが実行中と表示される
サービスディスカバリーを介してサービス間で通信できる
テレメトリデータがダッシュボードに表示される
リソースへの接続が正しく機能する

4. 高度な構成

外部サービス

ソリューションに含まれていないサービスの場合：

var externalApi = builder.AddProject<Projects.ExternalApi>("external-api")
    .WithHttpsEndpoint(port: 8001);

コンテナーリソース

コンテナーでサービスを実行します：

var myApi = builder.AddContainer("myapi", "myapiimage")
    .WithHttpEndpoint(port: 8000, targetPort: 80);

Azure リソース

Azure でホストされているリソースの場合：

var storage = builder.AddAzureStorage("storage")
    .AddBlobs("blobs");

var keyVault = builder.AddAzureKeyVault("keyvault");

カスタムリソース

カスタムリソースで Aspire を拡張します：

var customResource = builder.AddResource(new CustomResource("name"))
    .WithEndpoint("http", endpoint => endpoint.Port = 9000);

ベストプラクティス

1. サービスの構成

AppHost はビジネスロジックではなく、オーケストレーションに集中させます
横断的関心事には ServiceDefaults を使用します
各サービスを独立して実行できるようにします（フォールバック構成を用意します）

2. リソース管理

ローカル開発では Aspire が管理するリソースを使用します
本番環境へのデプロイでは接続文字列を使用します
データベースではリソースの永続化を構成します（データの損失を防ぎます）

3. 構成

ローカル環境での上書きには appsettings.Development.json を使用します
機密データはユーザーシークレットまたはキーコンテナーに保存します
環境ごとの構成を使用します

4. 依存関係

AppHost でサービスの依存関係を明示的に定義します
.WithReference() を使用して接続情報を注入します
データベースのマイグレーションでは起動順序を考慮します

5. 可観測性

分散トレーシングには組み込みの OpenTelemetry を活用します
ローカルでのデバッグにはダッシュボードを使用します
サービスごとに適切なログレベルを構成します

よくあるパターン

API ゲートウェイパターン

var apiGateway = builder.AddProject<Projects.ApiGateway>("gateway")
    .WithExternalHttpEndpoints();

var serviceA = builder.AddProject<Projects.ServiceA>("servicea");
var serviceB = builder.AddProject<Projects.ServiceB>("serviceb");

apiGateway.WithReference(serviceA).WithReference(serviceB);

メッセージキューを使用するワーカー

var messaging = builder.AddRabbitMQ("messaging");

var worker = builder.AddProject<Projects.Worker>("worker")
    .WithReference(messaging);

var api = builder.AddProject<Projects.Api>("api")
    .WithReference(messaging);

バックエンド API を使用する Web アプリ

var cache = builder.AddRedis("cache");
var database = builder.AddPostgres("postgres").AddDatabase("appdb");

var api = builder.AddProject<Projects.Api>("api")
    .WithReference(database)
    .WithReference(cache);

var web = builder.AddProject<Projects.Web>("web")
    .WithReference(api)
    .WithExternalHttpEndpoints();

トラブルシューティング

サービスディスカバリーが機能しない

サービスの Program.cs で builder.AddServiceDefaults() が呼び出されていることを確認します
HttpClient のサービス名が AppHost の AddProject 名と一致していることを確認します
ASP.NET サービスで app.MapDefaultEndpoints() が呼び出されていることを確認します

接続文字列が注入されない

AppHost とサービスの構成の両方でリソース名が一致していることを確認します
手動で AddDbContext を使う代わりに builder.AddNpgsqlDbContext<>() を使用します
ServiceDefaults への参照が存在することを確認します

ダッシュボードにアクセスできない

個々のサービスではなく、AppHost が実行中であることを確認します
ポートがブロックされていないことを確認します（デフォルト：15001）
AppHost のコンソール出力でダッシュボードの URL を確認します

リソースが起動しない

Docker Desktop が実行中であることを確認します（コンテナーリソースの場合）
既存のサービスとのポート競合を確認します
AppHost のコンソールで起動エラーを確認します

変更するファイル

既存のソリューションに Aspire を追加する場合、次のファイルを変更することになります：

ソリューションファイル（.sln） - AppHost と ServiceDefaults のプロジェクトを追加します
各サービスの Program.cs - サービスの既定値の登録を追加します
各サービスの .csproj - ServiceDefaults への参照を追加します
AppHost/Program.cs - オーケストレーションとリソースを定義します
サービス構成 - ハードコードされた URL をサービスディスカバリーに置き換えます
データベース構成 - Aspire のコンポーネントメソッドを使用します

前提条件

次のものがインストールされていることを確認してください：

.NET 8.0 SDK 以降
.NET Aspire ワークロード：dotnet workload install aspire
Docker Desktop（コンテナーリソースの場合）

インストールを確認します：

dotnet workload list

インストール済みのワークロードに「aspire」と表示されるはずです。

概要チェックリスト

Aspire の実装後、次の項目を確認してください。

追加リソース

特定のコンポーネントやパターンの詳細については、次を参照してください。

resources/components.md - Aspire のコンポーネントパッケージと構成
resources/deployment.md - Aspire アプリケーションの本番環境へのデプロイ

出力例

完了すると、ソリューション構成は次のようになります。

MySolution/
├── MySolution.sln
├── MySolution.AppHost/
│   ├── Program.cs                 # Orchestration configuration
│   ├── MySolution.AppHost.csproj
│   └── appsettings.json
├── MySolution.ServiceDefaults/
│   ├── Extensions.cs              # Service defaults implementation
│   └── MySolution.ServiceDefaults.csproj
├── MySolution.Api/
│   ├── Program.cs                 # Calls AddServiceDefaults()
│   └── MySolution.Api.csproj      # References ServiceDefaults
├── MySolution.Web/
│   ├── Program.cs                 # Calls AddServiceDefaults()
│   └── MySolution.Web.csproj      # References ServiceDefaults
└── MySolution.Worker/
    ├── Program.cs                 # Calls AddServiceDefaults()
    └── MySolution.Worker.csproj   # References ServiceDefaults

dotnet run --project MySolution.AppHost を実行すると、すべてのサービスが起動し、分散アプリケーションの監視とデバッグに使うダッシュボードが開きます。

Markdown 対応

ログインしてコメント

基本情報

作者: markpitt
リポジトリ: markpitt/claude-skills
カテゴリ: 開発
インストール数: 103
GitHub スター: 24

問題を報告