working-with-aspire

.NET Aspire 13 の使用

AI アシスタント向け：MCP ツールを使用してください

重要： ユーザーが Aspire アプリケーションのデバッグを行う際は、curl、外部 HTTP 呼び出し、またはダッシュボードを手動で確認する方法を提案するのではなく、Aspire MCP ツールを使用してください。

タスク	MCP ツール	これは使用しない
リソースの状態を確認する	list_resources	❌ ダッシュボード API への curl
サービスログを取得する	list_console_logs	❌ curl、docker logs
トレースを表示する	list_traces	❌ OTLP エンドポイントへの curl
トレース内のエラーを検索する	list_trace_structured_logs	❌ ダッシュボードを手動で検索
利用可能な AppHost を一覧表示する	list_apphosts	❌ ファイルシステムを検索

MCP が構成されていない場合は、AppHost ディレクトリで aspire mcp init を実行するようユーザーに案内してください。

クイックリファレンス

タスク	リファレンスファイル
AppHost のパターン、リソース、ライフサイクル	app-host.md
Azure の統合（データベース、メッセージング、AI）	azure-integrations.md
データベースの統合（Postgres、SQL、Mongo）	database-integrations.md
キャッシュ（Redis、Valkey、Garnet）	caching-integrations.md
メッセージング（Kafka、RabbitMQ、NATS）	messaging-integrations.md
ポリグロット（Node.js、Python、Go、Rust、Java）	polyglot-integrations.md
デプロイ、CLI、aspire do パイプライン	deployment-cli.md
Aspire を使用したテスト	testing.md
エラーとトラブルシューティング	diagnostics.md
AI アシスタント向け MCP 統合	mcp-integration.md
VS Code 拡張機能	vs-code-extension.md
証明書の信頼設定	certificate-config.md
9.x から 13.x への移行	aspire-13-migration.md

よくある間違い

❌ 誤り：存在しない API や非推奨の API を使用する

誤り	正しい方法	理由
AddPythonUvicornApp	AddUvicornApp	メソッド名は AddUvicornApp です
AddNpmApp	AddViteApp または AddJavaScriptApp	AddNpmApp は 13.0 で削除されました
FastAPI に AddPythonApp を使用する	AddUvicornApp	ASGI（FastAPI、Starlette）には AddUvicornApp を使用します
Aspire.Hosting.NodeJs	Aspire.Hosting.JavaScript	パッケージ名は 13.0 で変更されました

❌ 誤り：appsettings.json にシークレットを格納する

// WRONG - secrets exposed in source control
// appsettings.json: { "Parameters": { "api-key": "secret123" } }

// CORRECT - use user-secrets for development
// dotnet user-secrets set "Parameters:api-key" "secret123"

Aspire 13 の破壊的変更

重要： Aspire 9.x からの移行には注意が必要です。詳細は aspire-13-migration.md を参照してください。

JavaScript／Node.js の変更（13.0）

// BEFORE (9.x) - REMOVED IN 13.0
builder.AddNpmApp("frontend", "../app", scriptName: "dev", args: ["--no-open"])

// AFTER (13.0) - Use AddJavaScriptApp or AddViteApp
builder.AddJavaScriptApp("frontend", "../app")
    .WithRunScript("dev")
    .WithArgs("--no-open");

// For Vite/React specifically:
builder.AddViteApp("frontend", "../app")
    .WithHttpEndpoint(env: "PORT");

// Package renamed: Aspire.Hosting.NodeJs → Aspire.Hosting.JavaScript

Azure Redis の変更（13.1）

// BEFORE (13.0) - DEPRECATED
builder.AddAzureRedisEnterprise("cache")

// AFTER (13.1)
builder.AddAzureManagedRedis("cache")

ネットワークコンテキストの変更（13.0）

// BEFORE (9.x) - containerHostName parameter removed
await resource.ProcessArgumentValuesAsync(
    executionContext, processValue, logger,
    containerHostName: "localhost", cancellationToken);

// AFTER (13.0) - Use NetworkIdentifier
await resource.ProcessArgumentValuesAsync(
    executionContext, processValue, logger, cancellationToken);

// Get endpoints with network context
var endpoint = api.GetEndpoint("http", KnownNetworkIdentifiers.DefaultAspireContainerNetwork);

発行 API の変更（13.0）

// BEFORE (9.x)
public class MyPublisher : IDistributedApplicationPublisher { }

// AFTER (13.0) - Use aspire do pipelines instead
// IDistributedApplicationPublisher is deprecated

Aspire 13.0 以降の新機能

証明書の信頼設定の自動化

// Automatic - no configuration needed
var pythonApi = builder.AddUvicornApp("api", "./api", "main:app");
var nodeApi = builder.AddJavaScriptApp("frontend", "./frontend");
// Both automatically trust development certificates

AI アシスタント向け MCP 統合

# Initialize MCP for Claude Code, GitHub Copilot, etc.
aspire mcp init

aspire do パイプラインシステム

aspire do build           # Build container images
aspire do push            # Push to registry
aspire do deploy          # Full deployment
aspire do diagnostics     # Show available steps

aspire init（既存プロジェクトの Aspirify）

aspire init               # Interactive setup
aspire init --single-file # Create .cs AppHost without .csproj

単一ファイルの AppHost

// apphost.cs - no project file needed
#:package Aspire.Hosting@*
#:package Aspire.Hosting.Redis@*

var builder = DistributedApplication.CreateBuilder(args);
var cache = builder.AddRedis("cache");
builder.Build().Run();

よくあるパターン

FastAPI + React（Vite）フルスタック

// Required packages:
// dotnet add package Aspire.Hosting.Python
// dotnet add package Aspire.Hosting.JavaScript  (NOT NodeJs!)
// dotnet add package Aspire.Hosting.PostgreSQL

var builder = DistributedApplication.CreateBuilder(args);

// Database
var db = builder.AddPostgres("db")
    .AddDatabase("appdata")
    .WithDataVolume();

// FastAPI backend - use AddUvicornApp (NOT AddPythonApp!)
var api = builder.AddUvicornApp("api", "../api", "main:app")
    .WithHttpEndpoint(port: 8000, env: "PORT")
    .WithReference(db)
    .WaitFor(db);

// React frontend - use AddViteApp (NOT AddNpmApp!)
builder.AddViteApp("frontend", "../frontend")
    .WithHttpEndpoint(env: "PORT")
    .WithExternalHttpEndpoints()
    .WithReference(api);

builder.Build().Run();

フロントエンドは環境変数から API URL を読み取ります：process.env.services__api__http__0

基本的な AppHost 構造

var builder = DistributedApplication.CreateBuilder(args);

// Database
var db = builder.AddPostgres("db")
    .AddDatabase("appdata")
    .WithDataVolume();

// API with database reference
var api = builder.AddProject<Projects.Api>("api")
    .WithReference(db)
    .WaitFor(db);

// Frontend with API reference
builder.AddViteApp("frontend", "../frontend")
    .WithHttpEndpoint(env: "PORT")
    .WithReference(api);

builder.Build().Run();

サービスディスカバリーパターン

// Producer exposes endpoint
var api = builder.AddProject<Projects.Api>("api")
    .WithHttpEndpoint(port: 5000, name: "api");

// Consumer references it (gets services__api__api__0 env var)
builder.AddProject<Projects.Web>("web")
    .WithReference(api);

ヘルスチェックと待機

var db = builder.AddPostgres("db");
var cache = builder.AddRedis("cache");

builder.AddProject<Projects.Api>("api")
    .WithReference(db)
    .WithReference(cache)
    .WaitFor(db)           // Wait for running
    .WaitForHealthy(cache); // Wait for healthy (requires health check)

特定のファイルを読むタイミング

次の場合は app-host.md を読んでください：

• 新しい AppHost プロジェクトを設定するとき
• リソースのライフサイクルイベントを理解するとき
• エンドポイントとネットワークを設定するとき
• パラメーターとシークレットを使用するとき

次の場合は azure-integrations.md を読んでください：

• Azure サービス（Cosmos、Service Bus、Storage）を使用するとき
• Azure エミュレーターをローカルで実行するとき
• RunAsEmulator() または RunAsContainer() を使用するとき
• Bicep の出力をカスタマイズするとき

次の場合は polyglot-integrations.md を読んでください：

• Node.js、Python、Go、Rust、または Java アプリを追加するとき
• フロントエンドフレームワーク（Vite、Angular、React）を使用するとき
• コンテナーをベースとした多言語サービスを使用するとき
• AddNpmApp から AddJavaScriptApp に移行するとき

次の場合は deployment-cli.md を読んでください：

• aspire deploy、aspire publish、または aspire do を使用するとき
• aspire init を使用して既存のプロジェクトを Aspire 化するとき
• CI/CD パイプラインを設定するとき
• マニフェストの形式を理解するとき

次の場合は mcp-integration.md を読んでください：

• AI アシスタントとの統合を設定するとき
• Claude Code、GitHub Copilot、または Cursor を設定するとき
• MCP アクセス対象からリソースを除外するとき

次の場合は vs-code-extension.md を読んでください：

• VS Code で Aspire を使用するとき
• 多言語アプリケーションをデバッグするとき
• VS Code で新しい Aspire プロジェクトを作成するとき

次の場合は certificate-config.md を読んでください：

• 多言語アプリの HTTPS を設定するとき
• カスタム証明機関を使用するとき
• サービス間の証明書の信頼に関する問題があるとき

次の場合は aspire-13-migration.md を読んでください：

• Aspire 9.x からアップグレードするとき
• 非推奨の API に関する警告が表示されるとき
• アップグレード後にコンテナーのネットワークに問題が発生したとき

次の場合は diagnostics.md を読んでください：

• ASPIRE* コンパイラーエラーが表示されるとき
• サービス検出の問題をデバッグするとき
• コンテナーの起動に関する問題を解決するとき