【.NET Aspire入門】第1回 クラウドネイティブ開発の全体像とセットアップ

はじめに

複数のサービス、データベース、キャッシュ、メッセージブローカーが連携する分散アプリケーションを .NET で開発するとき、多くのチームが同じところでつまずきます。ローカル環境の立ち上げ手順が属人化し、接続文字列やポート番号が各所に散らばり、ログとメトリクスとトレースを横断して追う仕組みは後回しになりがちです。個々のサービスは素直に書けても、それらを束ねて動かす部分に手間がかかります。

.NET Aspire は、この「束ねる」部分を .NET のコードとして扱えるようにするためのツール群です。本連載では、Aspire を使ったクラウドネイティブ開発を基礎から実践まで段階的に解説していきます。第1回となる今回は、Aspire が何を解決するのかという全体像と、開発環境のセットアップ、最初のプロジェクト作成、そして開発時ダッシュボードの確認までを丁寧に追っていきます。

.NET Aspire とは何か

.NET Aspire は、クラウドネイティブな .NET アプリケーションを構築・実行・運用するためのオープンソースのフレームワークです。すでに一般提供（GA）されており、実運用のプロジェクトで採用できる段階に達しています。単一のライブラリというより、いくつかの役割を持った部品の集合として捉えると理解しやすくなります。

• アプリケーションモデル（AppHost） — どのサービスやリソースをどう接続して起動するかを C# のコードで宣言する、システム全体のオーケストレーターです。
• インテグレーション — Redis、PostgreSQL、SQL Server、RabbitMQ などのリソースを NuGet パッケージとして追加し、接続設定や可観測性の配線を自動化する部品です。
• ServiceDefaults — 各サービスに共通で組み込むロギング、メトリクス、トレース、ヘルスチェック、サービスディスカバリーの既定値をまとめたプロジェクトです。
• 開発ダッシュボード — 起動中の全サービスの状態、ログ、分散トレース、メトリクスを一画面で確認できる Web UI です。

重要なのは、Aspire がアプリケーションのランタイムを置き換えるものではないという点です。ASP.NET Core やワーカーサービスはこれまでどおりの書き方で動きます。Aspire が受け持つのは、それらを開発時に一括で起動し、リソースへ接続し、動作を観測できるようにする「外側」の部分です。

なぜ Aspire を使うのか

従来、複数サービスとインフラをローカルで動かす際は、docker-compose の YAML にサービス定義、環境変数、依存関係を書き連ねるのが一般的でした。動くには動きますが、いくつかの負担が残ります。環境変数と接続文字列の管理が煩雑になり、サービス側のコードとインフラ定義が別の場所・別の言語に分かれ、デバッガをアタッチしにくく、可観測性は別途組み込む必要がありました。

Aspire はこの構成情報を C# の AppHost に集約します。同じ内容を型付きのコードで表現できるため、補完やリファクタリングが効き、リソースとサービスの関係が一箇所で読み取れるようになります。

// AppHost/AppHost.cs — システム全体を C# で宣言する
var builder = DistributedApplication.CreateBuilder(args);

// インフラリソースを追加
var cache = builder.AddRedis("cache");
var db = builder.AddPostgres("postgres")
    .AddDatabase("appdb");

// API サービスを追加し、リソースへの参照を渡す
var api = builder.AddProject("api")
    .WithReference(cache)
    .WithReference(db);

// フロントエンドを追加し、API を参照させる
builder.AddProject("web")
    .WithReference(api)
    .WaitFor(api);

builder.Build().Run();

ここで WithReference を呼ぶと、Aspire は該当サービスへ接続文字列やエンドポイント情報を環境変数として自動的に注入します。接続文字列を手書きして配布する必要がなくなり、サービスディスカバリーによって http://api のような論理名で相互に呼び出せるようになります。開発体験の面では、次の点が実務での判断材料になります。

• 起動が一手順になる — AppHost を実行するだけで、依存リソースを含む全サービスが立ち上がります。
• 可観測性が既定で入る — OpenTelemetry ベースのログ・メトリクス・トレースが最初から配線されます。
• 本番への地続き感 — 開発時のリソース定義を土台に、Azure Container Apps や Kubernetes 向けのデプロイ生成へつなげられます。

開発環境のセットアップ

まず前提となるツールを揃えます。以前のバージョンでは dotnet workload install aspire によるワークロードのインストールが必要でしたが、現在の Aspire はワークロードを必要としません。テンプレートとインテグレーションはすべて通常の NuGet パッケージとして提供されます。この変更により、SDK のバージョン管理が単純になりました。

• .NET 10 SDK — 最新の LTS である .NET 10 を推奨します。
• コンテナランタイム — Redis や PostgreSQL などをコンテナとして起動するため、Docker Desktop または Podman が必要です。
• IDE — Visual Studio 2022 最新版、または C# Dev Kit を入れた VS Code / JetBrains Rider のいずれか。

次に、プロジェクトテンプレートを NuGet から導入します。あわせて、コマンドラインから Aspire を扱う aspire CLI を入れておくと、以降の作業が簡潔になります。

# Aspire のプロジェクトテンプレートを追加
dotnet new install Aspire.ProjectTemplates

# aspire CLI をグローバルツールとして導入
dotnet tool install -g aspire

# 導入の確認
aspire --version

Visual Studio を使う場合は、インストーラーで「ASP.NET と Web 開発」ワークロードを選択しておけば、Aspire のプロジェクトテンプレートが利用できます。専用のプレビューコンポーネントを追加する必要はありません。

最初の Aspire プロジェクトを作成する

スターターテンプレートから新しいソリューションを作成します。aspire CLI を使う方法と、使い慣れた dotnet new を使う方法のどちらでも構いません。

# aspire CLI を使う場合
aspire new aspire-starter --name MyFirstAspireApp

# もしくは dotnet new を使う場合
dotnet new aspire-starter -n MyFirstAspireApp
cd MyFirstAspireApp

生成されるソリューションは、役割の異なる複数のプロジェクトで構成されます。

MyFirstAspireApp/
├── MyFirstAspireApp.AppHost/          # オーケストレーター
├── MyFirstAspireApp.ServiceDefaults/  # 共通の既定設定
├── MyFirstAspireApp.ApiService/       # バックエンド API
└── MyFirstAspireApp.Web/              # フロントエンド

この4つのうち、Aspire ならではの要が AppHost と ServiceDefaults です。ApiService と Web は通常の ASP.NET Core プロジェクトなので、まずはこの2つに注目します。

AppHost — システムを組み立てる場所

AppHost プロジェクトは Aspire.AppHost.Sdk を使う特別なプロジェクトで、どのプロジェクトをどのリソースと接続して起動するかを宣言します。スターターの初期状態は、Redis キャッシュを介して Web と API がつながる最小構成になっています。

// MyFirstAspireApp.AppHost/AppHost.cs
var builder = DistributedApplication.CreateBuilder(args);

// Redis キャッシュ（コンテナとして起動）
var cache = builder.AddRedis("cache");

// API サービス。キャッシュを参照する
var apiService = builder.AddProject("apiservice");

// Web フロントエンド。キャッシュと API を参照する
builder.AddProject("webfrontend")
    .WithReference(cache)
    .WithReference(apiService)
    .WaitFor(apiService);

builder.Build().Run();

AddRedis のような呼び出しは、対応するインテグレーションのパッケージ（この場合は Aspire.Hosting.Redis）が AppHost に参照されていることで使えるようになります。WaitFor は、参照先が起動を終えるまで当該サービスの開始を待たせる指定で、起動順序に依存する初期化を安定させたいときに役立ちます。

ServiceDefaults — 各サービスに共通の土台を配る

ServiceDefaults は、すべてのサービスプロジェクトが参照する共有ライブラリです。OpenTelemetry によるログ・メトリクス・トレース、標準的なヘルスチェック、サービスディスカバリー、HTTP クライアントの回復性（リトライやタイムアウト）を一括で構成する拡張メソッドを提供します。

// 各サービスの Program.cs の冒頭で共通設定を適用する
var builder = WebApplication.CreateBuilder(args);

// ServiceDefaults を適用（OpenTelemetry・ヘルスチェック・サービスディスカバリー）
builder.AddServiceDefaults();

var app = builder.Build();

// /health と /alive のヘルスチェックエンドポイントを公開
app.MapDefaultEndpoints();

app.MapGet("/", () => "Hello from ApiService");

app.Run();

AddServiceDefaults の実体は ServiceDefaults プロジェクト内の拡張メソッドです。テンプレートが生成したコードをそのまま使えますが、中身を開いて確認しておくと、可観測性がどのように配線されているかが把握できます。

// ServiceDefaults/Extensions.cs（抜粋）
public static TBuilder AddServiceDefaults(this TBuilder builder)
    where TBuilder : IHostApplicationBuilder
{
    builder.ConfigureOpenTelemetry();
    builder.AddDefaultHealthChecks();

    builder.Services.AddServiceDiscovery();
    builder.Services.ConfigureHttpClientDefaults(http =>
    {
        // 既定でリトライ・サーキットブレーカーなどの回復性を付与
        http.AddStandardResilienceHandler();
        // 論理名によるサービス解決を有効化
        http.AddServiceDiscovery();
    });

    return builder;
}

この土台があるため、サービス側のコードでは http://apiservice のような論理名で HTTP 呼び出しを書くだけで、実際のホストやポートは Aspire が解決し、その通信は自動的にトレース対象になります。

開発ダッシュボードを起動して確認する

準備が整ったら、AppHost プロジェクトを起動します。起動対象は常に AppHost で、個々のサービスを直接実行するわけではありません。

# AppHost を起動すると、依存リソースを含む全サービスが立ち上がる
cd MyFirstAspireApp.AppHost
dotnet run

# aspire CLI を使う場合はソリューション直下で
aspire run

起動すると、コンソールに開発ダッシュボードの URL が表示されます。URL には認証トークンが含まれており、初回はそのリンクからアクセスします。ダッシュボードでは、次の情報を一画面で確認できます。

• Resources — 各サービスとコンテナの起動状態、割り当てられたエンドポイント、環境変数を一覧できます。
• Console logs — 全サービスの標準出力を集約して表示します。
• Structured logs — 構造化ログを属性で絞り込みながら追えます。
• Traces — サービスをまたぐリクエストの分散トレースを、各区間の所要時間とともに可視化します。
• Metrics — リクエスト数やレイテンシなどのメトリクスをグラフで確認できます。

とくにトレースの表示は、複数サービスにまたがる処理のどこで時間がかかっているかを掴むのに有効です。追加のエージェントや外部の監視基盤を用意しなくても、開発の初日から可観測性が手元にある状態になります。Web の画面を数回操作してからダッシュボードのトレースを開くと、Web から API、API からキャッシュへとリクエストが流れていく様子がそのまま見て取れます。

デバッグについても特別な手順は不要です。Visual Studio では AppHost をスタートアッププロジェクトに設定して F5 を押せば、配下の各サービスに設定したブレークポイントで停止します。複数プロセスを一度に立ち上げつつ、通常のデバッグ体験がそのまま得られる点が Aspire の扱いやすさのひとつです。

まとめ

今回は、.NET Aspire の全体像と、開発環境のセットアップから最初のプロジェクト作成、ダッシュボードの確認までを追いました。押さえておきたい要点は次のとおりです。

• Aspire の役割 — アプリのランタイムではなく、複数サービスとリソースを束ねて起動・観測する外側の仕組みです。
• AppHost — システム構成を C# で宣言するオーケストレーターで、接続情報を自動注入します。
• ServiceDefaults — 可観測性・ヘルスチェック・サービスディスカバリーを各サービスへ共通で配ります。
• ワークロード不要 — 現在はテンプレートもインテグレーションも NuGet で提供され、導入が単純になりました。
• ダッシュボード — ログ・トレース・メトリクスを開発初日から一画面で確認できます。

エンハンスド株式会社では、.NET Aspire を用いた分散アプリケーションの設計と、既存 .NET システムのクラウドネイティブ化を支援しています。オーケストレーション構成の見直しや可観測性の導入をご検討の際は、現状の構成を踏まえた初期のご相談から承りますので、お気軽にお問い合わせください。

---

次回予告：「第2回：データベースとキャッシングの統合」では、SQL Server、PostgreSQL、Redis などのデータストアを .NET Aspire アプリケーションに統合する方法を詳しく解説します。

このテーマの全体像は .NET モダナイゼーション完全ガイド にまとめています。

本連載「.NET Aspire 入門」全6回

1. 第1回 クラウドネイティブ開発の全体像とセットアップ（本記事）
2. 第2回 データベースとキャッシュの統合
3. 第3回 メッセージングとイベント駆動アーキテクチャ
4. 第4回 可観測性とモニタリング
5. 第5回 デプロイメントとスケーリング
6. 第6回 本番運用のベストプラクティス

実務目線の総論は .NET Aspire で実現するクラウドネイティブ開発の実践ガイド もあわせてご覧ください。