クイック スタート: 初めての Aspire ソリューションを構築する

クラウドネイティブ アプリでは、多くの場合、データベース、ストレージおよびキャッシュ ソリューション、メッセージング プロバイダー、その他の Web サービスなどのさまざまなサービスへの接続が必要になります。 Aspire は、これらの種類のサービス間の接続と構成を合理化するように設計されています。 このクイック スタートでは、 Aspire スターター アプリケーション テンプレート ソリューションを作成する方法について説明します。

このクイック スタートでは、次のタスクについて説明します。

Prerequisites

Aspireを使用するには、次のものがローカルにインストールされている必要があります。

• .NET 8.0 または .NET 9.0。
  • Aspire 9.4 以降では、.NET 10 Preview 5 以降がサポートされています。
• OCI 準拠のコンテナー ランタイム。次に例を示します。
  • Docker デスクトップ または Podman。 詳細については、「コンテナー ランタイム」を参照してください。
• 次のような統合開発者環境 (IDE) またはコード エディター。
  • Visual Studio 2022 バージョン 17.9 以降 (任意)
  • Visual Studio Code (任意)
    • C# Dev Kit： 拡張機能（省略可能）
  • JetBrains Rider とプラグインAspire（省略可能）

詳細については、Aspireセットアップとツール、および SDK のAspireに関する説明を参照してください。

Aspire テンプレートを作成する

新しい Aspire スターター アプリケーションを作成するには、Visual Studio、Visual Studio Code、または .NET CLI のいずれかを使用できます。

dotnet new install Aspire.ProjectTemplates

dotnet new aspire-starter --use-redis-cache --output AspireSample

使用可能なテンプレートの詳細については、「 Aspire テンプレート」を参照してください。

アプリをローカルでテストする

サンプル アプリには、最小限の API プロジェクトと通信するフロントエンド Blazor アプリが含まれています。 API プロジェクトは、偽の 気象データをフロントエンドに提供するために使用されます。 フロントエンド アプリは、サービス検出を使用して API プロジェクトに接続するように構成されています。 API プロジェクトは、Redisで出力キャッシュを使用するように構成されています。 これで、サンプル アプリをテストする準備ができました。 次の条件を確認する必要があります。

• 気象データは、サービス検出を使用して API プロジェクトから取得され、天気ページに表示されます。
• 後続の要求は、AspireRedis 統合によって構成された出力キャッシュによって処理されます。

dotnet dev-certs https --trust

dotnet run --project AspireSample/AspireSample.AppHost

1. アプリは、ブラウザーに Aspire ダッシュボードを表示します。 ダッシュボードの詳細については、後で説明します。 ここでは、リソースの一覧で webfrontend プロジェクトを見つけて、プロジェクトの localhost エンドポイントを選択します。

   

   webfrontend アプリのホーム ページに "Hello, world!" と表示されます。

2. 左側のナビゲーションを使用して、ホーム ページから天気ページに移動します。 天気ページに気象データが表示されます。 予測テーブルで表される値の一部をメモしておきます。

3. ページを 10 秒間更新し続けます。 10 秒以内に、キャッシュされたデータが返されます。 最終的には、データがランダムに生成され、キャッシュが更新されるため、異なる気象データのセットが表示されます。

おめでとうございます! 最初の Aspire ソリューションを作成して実行しました。 アプリを停止するには、ブラウザー ウィンドウを閉じます。

次に、新しい Aspire ソリューションの構造とその他の機能を調査します。

Aspire ダッシュボードを調べる

Aspire プロジェクトを実行すると、アプリのさまざまな部分を監視するために使用するダッシュボードが起動します。 ダッシュボードは次のスクリーンショットのようになります。

左側のナビゲーションを使用して各ページにアクセスし、 Aspire リソースに関するさまざまな情報を表示します。

• リソース: アプリの状態、エンドポイント アドレス、読み込まれた環境変数など、.NET プロジェクト内のすべての個々の Aspire プロジェクトの基本情報を一覧表示します。

• コンソール: アプリ内の各プロジェクトからのコンソール出力を表示します。

• 構造化: 構造化ログをテーブル形式で表示します。 これらのログでは、基本的なフィルター処理、自由形式の検索、ログ レベルのフィルター処理もサポートされています。 apiservice と webfrontendからのログが表示されます。 行の右端にある [表示] ボタンを選択すると、各ログ エントリの詳細を展開できます。

• トレース: あなたのアプリケーションのトレースを表示します。これにより、アプリケーション内のリクエスト経路を追跡できます。 /weather の要求を見つけて、ページの右側にある [表示] を選択します。 ダッシュボードには、アプリのさまざまな部分を通過する段階で要求が表示されます。

  

• メトリック: 公開されているさまざまなインストルメントとメーター、およびアプリの対応するディメンションが表示されます。 メトリックは、使用可能なディメンションに基づいてフィルターを条件付きで公開します。

  

詳細については、ダッシュボードの概要Aspire参照してください。

Aspire ソリューションの構造を理解する

このソリューションは、次のプロジェクトで構成されます。

• AspireSample.ApiService: ASP.NET Core 最小限の API プロジェクトを使用して、フロントエンドにデータを提供します。 このプロジェクトは、共有 の AspireSample.ServiceDefaults プロジェクトに依存します。
• AspireSample.AppHost: アプリのさまざまなプロジェクトとサービスに接続して構成するように設計されたオーケストレーター プロジェクトです。 オーケストレーターは、スタートアップ プロジェクトとして設定する必要があります。これは、の AspireSample.ApiService および AspireSample.Web プロジェクトによって異なります。
• AspireSample.ServiceDefaults: Aspire、サービス検出、テレメトリに関連するソリューション内のプロジェクト全体で再利用される構成を管理するための共有プロジェクト。
• AspireSample.Web: 既定の ASP.NET Core サービス構成を持つ BlazorAspire アプリ プロジェクトは、このプロジェクトは の AspireSample.ServiceDefaults プロジェクトに依存します。 詳細については、サービスの既定値Aspire参照してください。

AspireSample ディレクトリは、次の構造のようになります。

└───📂 AspireSample
     ├───📂 AspireSample.ApiService
     │    ├───📂 Properties
     │    │    └─── launchSettings.json
     │    ├─── appsettings.Development.json
     │    ├─── appsettings.json
     │    ├─── AspireSample.ApiService.csproj
     │    └─── Program.cs
     ├───📂 AspireSample.AppHost
     │    ├───📂 Properties
     │    │    └─── launchSettings.json
     │    ├─── appsettings.Development.json
     │    ├─── appsettings.json
     │    ├─── AspireSample.AppHost.csproj
     │    └─── AppHost.cs
     ├───📂 AspireSample.ServiceDefaults
     │    ├─── AspireSample.ServiceDefaults.csproj
     │    └─── Extensions.cs
     ├───📂 AspireSample.Web
     │    ├───📂 Components
     │    │    ├───📂 Layout
     │    │    │    ├─── MainLayout.razor
     │    │    │    ├─── MainLayout.razor.css
     │    │    │    ├─── NavMenu.razor
     │    │    │    └─── NavMenu.razor.css
     │    │    ├───📂 Pages
     │    │    │    ├─── Counter.razor
     │    │    │    ├─── Error.razor
     │    │    │    ├─── Home.razor
     │    │    │    └─── Weather.razor
     │    │    ├─── _Imports.razor
     │    │    ├─── App.razor
     │    │    └─── Routes.razor
     │    ├───📂 Properties
     │    │    └─── launchSettings.json
     │    ├───📂 wwwroot
     │    │    ├───📂 bootstrap
     │    │    │    ├─── bootstrap.min.css
     │    │    │    └─── bootstrap.min.css.map
     │    │    ├─── app.css
     │    │    └─── favicon.png
     │    ├─── appsettings.Development.json
     │    ├─── appsettings.json
     │    ├─── AspireSample.Web.csproj
     │    ├─── Program.cs
     │    └─── WeatherApiClient.cs
     └─── AspireSample.sln

スターター プロジェクトを調べる

Aspire ソリューション内の各プロジェクトは、アプリの構成で役割を果たします。 *.Web プロジェクトは、フロントエンド UI を提供する標準的な ASP.NET CoreBlazor アプリです。 詳細については、「ASP.NET Core 9.0 の新機能: Blazor」を参照してください。 *.ApiService プロジェクトは、最小限の API テンプレート プロジェクト ASP.NET Core 標準です。 どちらのプロジェクトも、* に依存します。ServiceDefaults プロジェクトです。これは、ソリューション内のプロジェクト間で再利用される構成を管理するために使用される共有プロジェクトです。

このクイック スタートで関心のある 2 つのプロジェクトは、* です。AppHost と *。ServiceDefaults プロジェクトについては、次のセクションで詳しく説明します。

Aspire ホスト プロジェクト

*。AppHost プロジェクトは、ローカルの開発オーケストレーターとして機能します。

<Project Sdk="Microsoft.NET.Sdk">

  <Sdk Name="Aspire.AppHost.Sdk" Version="9.5.0" />

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net9.0</TargetFramework>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
    <UserSecretsId>2aa31fdb-0078-4b71-b953-d23432af8a36</UserSecretsId>
  </PropertyGroup>

  <ItemGroup>
    <ProjectReference Include="..\AspireSample.ApiService\AspireSample.ApiService.csproj" />
    <ProjectReference Include="..\AspireSample.Web\AspireSample.Web.csproj" />
  </ItemGroup>

  <ItemGroup>
    <PackageReference Include="Aspire.Hosting.AppHost" Version="9.5.1" />
    <PackageReference Include="Aspire.Hosting.Redis" Version="9.5.1" />
  </ItemGroup>

</Project>

詳細については、Aspire参照してください。

AppHost.cs プロジェクトの ファイルについて考えてみましょう。

var builder = DistributedApplication.CreateBuilder(args);

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

var apiService = builder.AddProject<Projects.AspireSample_ApiService>("apiservice");

builder.AddProject<Projects.AspireSample_Web>("webfrontend")
    .WithExternalHttpEndpoints()
    .WithReference(cache)
    .WaitFor(cache)
    .WithReference(apiService)
    .WaitFor(apiService);

builder.Build().Run();

以前に .NET 汎用ホストまたは ASP.NET Core Web ホストを使用したことがある場合は、AppHost プログラミング モデルとビルダー パターンをよく理解している必要があります。 上記のコード:

• IDistributedApplicationBuilderの呼び出しから DistributedApplication.CreateBuilder() インスタンスを作成します。
• AddRedis という名前の "cache" を呼び出して、Redis サーバーをアプリに追加し、戻り値を cacheという名前の変数 (IResourceBuilder<RedisResource>型) に割り当てます。
• AddProject プロジェクトの詳細と共にジェネリック型パラメーターを指定して呼び出し、AspireSample.ApiService プロジェクトをアプリケーション モデルに追加します。 これは、 Aspireの基本的な構成要素の 1 つであり、アプリ内のプロジェクト間のサービス検出と通信を構成するために使用されます。 "apiservice" 名前引数は、アプリケーション モデル内のプロジェクトを識別するために使用され、後で通信するプロジェクトによって使用されます。
• AddProject 再度呼び出します。今度は、AspireSample.Web プロジェクトをアプリケーション モデルに追加します。 複数の呼び出しをWithReferenceにチェーンし、cacheとapiService変数を渡す。 WithReference API は、Aspireのもう 1 つの基本的な API であり、アプリケーション モデルに追加されるプロジェクトにサービス検出情報または接続文字列構成を挿入します。 さらに、WaitFor API の呼び出しは、cache プロジェクトを開始する前に apiService リソースと AspireSample.Web リソースを確実に使用するために使用されます。 詳細については、Aspire「オーケストレーション: リソースの待機」を参照してください。

最後に、アプリがビルドされ、実行されます。 DistributedApplication.Run() メソッドは、アプリとそのすべての依存関係を開始します。 詳細については、オーケストレーションの概要Aspire参照してください。

Aspire サービスのデフォルト設定プロジェクト

*.ServiceDefaults プロジェクトは、ソリューション内のプロジェクト全体で再利用される構成を管理するために使用される共有プロジェクトです。 このプロジェクトにより、すべての依存サービスが同じ回復性、サービス検出、および OpenTelemetry 構成を共有できるようになります。 共有Aspire プロジェクト ファイルには、IsAspireSharedProjectとして設定されたtrue プロパティが含まれています。

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <TargetFramework>net9.0</TargetFramework>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
    <IsAspireSharedProject>true</IsAspireSharedProject>
  </PropertyGroup>

  <ItemGroup>
    <FrameworkReference Include="Microsoft.AspNetCore.App" />

    <PackageReference Include="Microsoft.Extensions.Http.Resilience" Version="9.9.0" />
    <PackageReference Include="Microsoft.Extensions.ServiceDiscovery" Version="9.5.1" />
    <PackageReference Include="OpenTelemetry.Exporter.OpenTelemetryProtocol" Version="1.13.0" />
    <PackageReference Include="OpenTelemetry.Extensions.Hosting" Version="1.13.0" />
    <PackageReference Include="OpenTelemetry.Instrumentation.AspNetCore" Version="1.12.0" />
    <PackageReference Include="OpenTelemetry.Instrumentation.Http" Version="1.12.0" />
    <PackageReference Include="OpenTelemetry.Instrumentation.Runtime" Version="1.12.0" />
  </ItemGroup>

</Project>

サービスの既定のプロジェクトでは、IHostApplicationBuilderという名前の AddServiceDefaults 型の拡張メソッドが公開されます。 テンプレートからのサービスの既定のプロジェクトは出発点であり、ニーズに合わせてカスタマイズできます。 詳細については、サービスの既定値Aspire参照してください。

サービス通信を調整する

Aspire には、アプリのさまざまな部分間の接続と通信の構成に役立つオーケストレーション機能が用意されています。 の AspireSample.AppHost プロジェクトでは、アプリケーション モデルに AspireSample.ApiService および AspireSample.Web プロジェクトが追加されました。 また、フロントエンドとして"webfrontend"、API プロジェクトリファレンスとしてBlazor"apiservice"という名前も宣言しました。 さらに、Redis というラベルが付いた "cache" サーバー リソースが追加されました。 これらの名前は、アプリ内のプロジェクト間のサービス検出と通信を構成するために使用されます。

フロントエンド アプリは、API プロジェクトとの通信に使用される型指定された HttpClient を定義します。

namespace AspireSample.Web;

public class WeatherApiClient(HttpClient httpClient)
{
    public async Task<WeatherForecast[]> GetWeatherAsync(
        int maxItems = 10,
        CancellationToken cancellationToken = default)
    {
        List<WeatherForecast>? forecasts = null;

        await foreach (var forecast in 
            httpClient.GetFromJsonAsAsyncEnumerable<WeatherForecast>(
                "/weatherforecast", cancellationToken))
        {
            if (forecasts?.Count >= maxItems)
            {
                break;
            }
            if (forecast is not null)
            {
                forecasts ??= [];
                forecasts.Add(forecast);
            }
        }

        return forecasts?.ToArray() ?? [];
    }
}

public record WeatherForecast(DateOnly Date, int TemperatureC, string? Summary)
{
    public int TemperatureF => 32 + (int)(TemperatureC / 0.5556);
}

HttpClient は、サービス検出を使用するように構成されています。 Program.cs プロジェクトの ファイルの次のコードについて考えてみましょう。

using AspireSample.Web;
using AspireSample.Web.Components;

var builder = WebApplication.CreateBuilder(args);

// Add service defaults & Aspire client integrations.
builder.AddServiceDefaults();
builder.AddRedisOutputCache("cache");

// Add services to the container.
builder.Services.AddRazorComponents()
    .AddInteractiveServerComponents();

builder.Services.AddHttpClient<WeatherApiClient>(client =>
    {
        // This URL uses "https+http://" to indicate HTTPS is preferred over HTTP.
        // Learn more about service discovery scheme resolution at https://aka.ms/dotnet/sdschemes.
        client.BaseAddress = new("https+http://apiservice");
    });

var app = builder.Build();

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error", createScopeForErrors: true);
    // The default HSTS value is 30 days. You may want to change this for production scenarios, see https://aka.ms/aspnetcore-hsts.
    app.UseHsts();
}

app.UseHttpsRedirection();

app.UseAntiforgery();

app.UseOutputCache();

app.MapStaticAssets();

app.MapRazorComponents<App>()
    .AddInteractiveServerRenderMode();

app.MapDefaultEndpoints();

app.Run();

上記のコード:

• AddServiceDefaultsを呼び出し、アプリの共有の既定値を構成します。
• AddRedisOutputCache コンテナー connectionName をアプリケーション モデルに追加するときに使用した Redis と同じ "cache" を呼び出します。 これにより、出力キャッシュに Redis を使用するようにアプリが構成されます。
• AddHttpClient を呼び出し、HttpClient.BaseAddress を "https+http://apiservice"するように構成します。 これは、API プロジェクトをアプリケーション モデルに追加するときに使用された名前で、サービス検出が構成されると、API プロジェクトの正しいアドレスに自動的に解決されます。

詳細については、「 クラス HTTP 要求を作成する」を参照してください。

Aspire CLI (コマンドラインインターフェース)

Aspire CLI (aspire コマンド) は、polyglot Aspire プロジェクトを作成、管理、実行、発行するためのコマンドライン機能を提供するクロスプラットフォーム ツールです。 Aspire CLI を使用して、開発ワークフローを合理化し、分散アプリケーションのサービスを調整します。

詳細については、「 CLI の概要」と「 CLI のインストール」を参照してください。

こちらも参照ください

• Aspire 統合の概要
• Aspireにおけるサービス検出
• Aspire サービスの既定値
• 健康診断 Aspire
• Aspire テレメトリー
• localhost の信頼されていない Aspire 証明書のトラブルシューティング

次のステップ