.NET .NET Aspire 内部ループネットワークの概要

2025-07-29

.NET .NET Aspire を使用して開発する利点の 1 つは、クラウドネイティブアプリをローカルで開発、テスト、デバッグできる点です。内部ループネットワークは、開発環境でアプリが相互に通信できるようにする .NET.NET Aspire の重要な側面です。この記事では、プロキシ、エンドポイント、エンドポイント構成、起動プロファイルを使用して、.NET.NET Aspire がさまざまなネットワークシナリオを処理する方法について説明します。

内部ループでのネットワーク

内部ループは、ターゲット環境にアプリをデプロイする前に、アプリをローカルで開発およびテストするプロセスです。 .NET .NET Aspire には、内部ループでのネットワークエクスペリエンスを簡素化および強化するためのツールと機能がいくつか用意されています。次に例を示します。

起動プロファイル: 起動プロファイルは、アプリをローカルで実行する方法を指定する構成ファイルです。起動プロファイル (launchSettings.json ファイルなど) を使用して、アプリのエンドポイント、環境変数、起動設定を定義できます。
Kestrel 構成: Kestrel 構成を使用すると、Kestrel Web サーバーがリッスンするエンドポイントを指定できます。アプリ設定で Kestrel エンドポイントを構成でき、.NET.NET Aspire は自動的にこれらの設定を使用してエンドポイントを作成します。
エンドポイント/エンドポイントの構成: エンドポイントは、アプリと依存するサービス (データベース、メッセージキュー、API など) との間の接続です。エンドポイントは、サービス名、ホストポート、スキーム、環境変数などの情報を提供します。エンドポイントは、アプリに暗黙的に (起動プロファイルを使用して) 追加することも、WithEndpointを呼び出すことによって明示的に追加することもできます。
プロキシ: .NET.NET Aspire は、アプリに追加するサービスバインドごとにプロキシを自動的に起動し、リッスンするプロキシのポートを割り当てます。その後、プロキシは、アプリがリッスンするポートに要求を転送します。これは、プロキシポートとは異なる場合があります。これにより、ポートの競合を回避し、一貫性のある予測可能な URL を使用してアプリとサービスにアクセスできます。

エンドポイントのしくみ

.NET .NET Aspire のサービスバインドには、アプリに必要な外部リソース (データベース、メッセージキュー、API など) を表す サービス と、アプリとサービスの間の接続を確立し、必要な情報を提供する バインド という 2 つの統合が含まれます。

では、2 つのサービスバインドの種類がサポートされています。暗黙的な、異なる環境でのアプリの動作を定義する指定された起動プロファイルに基づいて自動的に作成される、明示的な、を使用して手動で作成されます。

バインディングを作成すると、暗黙的でも明示的でも、.NET.NET Aspire は指定されたポートで軽量のリバースプロキシを起動し、アプリからサービスへの要求のルーティングと負荷分散を処理します。プロキシは .NET.NET Aspire 実装の詳細であり、構成や管理の問題は必要ありません。

エンドポイントのしくみを視覚化するには、.NET.NET Aspire スターターテンプレートの内部ループネットワーク図を検討してください。

コンテナーネットワークの管理方法

1 つ以上のコンテナーリソースを追加すると、 .NET.NET Aspire はコンテナー間のサービス検出を有効にする専用のコンテナーブリッジネットワークを作成します。このブリッジネットワークは、コンテナーが相互に通信できるようにする仮想ネットワークであり、DNS 名を使用してコンテナー間サービス検出用の DNS サーバーを提供します。

ネットワークの有効期間は、コンテナーリソースによって異なります。

すべてのコンテナーにセッションの有効期間がある場合、ネットワークもセッションベースであり、アプリホストプロセスが終了するとクリーンアップされます。
コンテナーに永続的な有効期間がある場合、ネットワークは永続的であり、アプリホストプロセスの終了後も実行されたままです。 Aspire は、後続の実行時にこのネットワークを再利用し、アプリホストが実行されていない場合でも永続的なコンテナーが通信を維持できるようにします。

コンテナーの有効期間の詳細については、「コンテナーリソースの有効期間」を参照してください。

コンテナーネットワークの名前付け規則を次に示します。

セッションネットワーク: aspire-session-network-<unique-id>-<app-host-name>
永続的なネットワーク: aspire-persistent-network-<project-hash>-<app-host-name>

各アプリホストインスタンスは、独自のネットワークリソースを取得します。唯一の違いは、ネットワークの有効期間と名前です。サービス検出は両方で同じように動作します。

コンテナーは、リソース名を使用してネットワーク上に自身を登録します。 Aspire は、コンテナー間のサービス検出にこの名前を使用します。たとえば、pgadmin コンテナーは、postgresを使用して postgres:5432 という名前のデータベースリソースに接続できます。

Note

プロジェクトやその他の実行可能ファイルなどのホストサービスは、コンテナーネットワークを使用しません。サービスの検出とコンテナーとの通信のために、公開されているコンテナーポートに依存します。サービス検出の詳細については、サービス検出の概要を参照してください。

Launch profiles

AddProjectを呼び出すと、アプリホストは プロパティ/launchSettings.json を検索して、エンドポイントの既定のセットを決定します。アプリホストは、次の規則を使用して特定の起動プロファイルを選択します。

launchProfileNameを呼び出すときに渡される明示的な AddProject 引数。
DOTNET_LAUNCH_PROFILE 環境変数。詳細については、環境変数 .NETを参照してください。
launchSettings.jsonで定義されている最初の起動プロファイル。

次の launchSettings.json ファイルについて考えてみます。

{
  "$schema": "http://json.schemastore.org/launchsettings.json",
  "profiles": {
    "http": {
      "commandName": "Project",
      "dotnetRunMessages": true,
      "launchBrowser": false,
      "inspectUri": "{wsProtocol}://{url.hostname}:{url.port}/_framework/debug/ws-proxy?browser={browserInspectUri}",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    },
    "https": {
      "commandName": "Project",
      "dotnetRunMessages": true,
      "launchBrowser": true,
      "inspectUri": "{wsProtocol}://{url.hostname}:{url.port}/_framework/debug/ws-proxy?browser={browserInspectUri}",
      "applicationUrl": "https://localhost:7239;http://localhost:5066",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    }
  }
}

この記事の残りの部分では、IDistributedApplicationBuilder API で builder という名前の変数に割り当てられた CreateBuilder() を作成したとします。

var builder = DistributedApplication.CreateBuilder(args);

http と https 起動プロファイルを指定するには、applicationUrl ファイルの両方の値を構成します。これらの URL は、このプロジェクトのエンドポイントを作成するために使用されます。これは次に相当します。

builder.AddProject<Projects.Networking_Frontend>("frontend")
       .WithHttpEndpoint(port: 5066)
       .WithHttpsEndpoint(port: 7239);

Important

launchSettings.json (または起動プロファイル) がない場合、既定ではバインディングはありません。

詳細については、.NET.NET Aspire と、起動プロファイルを参照してください。

Kestrelによって構成されたエンドポイント

.NET .NET Aspire では、Kestrel エンドポイントの構成がサポートされます。たとえば、HTTPS スキームとポート 5271 を使用して Kestrel エンドポイントを定義するプロジェクトの appsettings.json ファイルを考えてみましょう。

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning"
    }
  },
  "Kestrel": {
    "Endpoints": {
      "Https": {
        "Url": "https://*:5271"
      }
    }
  }
}

上記の構成では、Https エンドポイントを指定しています。 Url プロパティは https://*:5271に設定されています。つまり、エンドポイントはポート 5271 上のすべてのインターフェイスでリッスンします。詳細については、「ASP.NET Core Kestrel Web サーバーのエンドポイントを構成する」を参照してください。

Kestrel エンドポイントが構成されている場合、プロジェクトは構成済みの applicationUrl を launchSettings.json ファイルから削除する必要があります。

Note

applicationUrl ファイルにが存在し、Kestrel エンドポイントが構成されている場合、アプリホストは例外をスローします。

プロジェクトリソースを追加するときに、launchSettings.json ファイルの代わりに Kestrel エンドポイントを使用することを指定できるオーバーロードがあります。

builder.AddProject<Projects.Networking_ApiService>(
    name: "apiservice",
    configure: static project =>
    {
        project.ExcludeLaunchProfile = true;
        project.ExcludeKestrelEndpoints = false;
    })
    .WithHttpsEndpoint();

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

ポートとプロキシ

サービスバインディングを定義する場合、ホストポートは常にサービスの前にあるプロキシに渡されます。これにより、サービスの 1 つまたは複数のレプリカも同様に動作できます。さらに、WithReference API を使用するすべてのリソース依存関係は、環境変数のプロキシエンドポイントに依存します。

AddProject、WithHttpEndpoint、WithReplicasを呼び出す次のメソッドチェーンについて考えてみましょう。

builder.AddProject<Projects.Networking_Frontend>("frontend")
       .WithHttpEndpoint(port: 5066)
       .WithReplicas(2);

上記のコードは、次のネットワーク図になります。

上の図は、次の図を示しています。

アプリへのエントリポイントとしての Web ブラウザー。
5066 のホストポート。
Web ブラウザーとフロントエンドサービスレプリカの間に位置し、ポート 5066 をリッスンしているフロントエンドプロキシ。
ランダムに割り当てられたポート 65001 でリッスンしている frontend_0 フロントエンドサービスレプリカ。
ランダムに割り当てられたポート 65002 でリッスンしている frontend_1 フロントエンドサービスレプリカ。

WithReplicasの呼び出しがなければ、フロントエンドサービスは 1 つだけです。プロキシは引き続きポート 5066 でリッスンしますが、フロントエンドサービスはランダムなポートでリッスンします。

builder.AddProject<Projects.Networking_Frontend>("frontend")
       .WithHttpEndpoint(port: 5066);

次の 2 つのポートが定義されています。

5066 のホストポート。
基になるサービスがバインドされるランダムプロキシポート。

上の図は、次の図を示しています。

アプリへのエントリポイントとしての Web ブラウザー。
5066 のホストポート。
Web ブラウザーとフロントエンドサービスの間に位置し、ポート 5066 でリッスンしているフロントエンドプロキシ。
65001 のランダムポートでリッスンするフロントエンドサービス。

基になるサービスは、プロジェクトリソースの ASPNETCORE_URLS を介してこのポートを供給されます。サービスバインドで環境変数を指定して、他のリソースがこのポートにアクセスします。

builder.AddNpmApp("frontend", "../NodeFrontend", "watch")
       .WithHttpEndpoint(port: 5067, env: "PORT");

前のコードでは、ランダムポートを PORT 環境変数で使用できるようにします。アプリはこのポートを使用して、プロキシからの着信接続を受信します。次の図を考えてみましょう。

上の図は、次の図を示しています。

アプリへのエントリポイントとしての Web ブラウザー。
5067 のホストポート。
Web ブラウザーとフロントエンドサービスの間に位置し、ポート 5067 でリッスンしているフロントエンドプロキシ。
環境「65001」でリッスンしているフロントエンドサービス。

Tip

エンドポイントがプロキシされないようにするには、IsProxied 拡張メソッドを呼び出すときに、false プロパティを WithEndpoint に設定します。詳細については、「エンドポイント拡張機能の :に関するその他の考慮事項」を参照してください。

ホストポートを省略する

ホストポートを省略すると、.NET.NET Aspire はホストポートとサービスポートの両方に対してランダムなポートを生成します。これは、ポートの競合を回避し、ホストまたはサービスポートを気にしない場合に便利です。次のコードについて考えてみましょう。

builder.AddProject<Projects.Networking_Frontend>("frontend")
       .WithHttpEndpoint();

このシナリオでは、次の図に示すように、ホストポートとサービスポートの両方がランダムです。

上の図は、次の図を示しています。

アプリへのエントリポイントとしての Web ブラウザー。
65000 のランダムホストポート。
Web ブラウザーとフロントエンドサービスの間に位置し、ポート 65000 でリッスンしているフロントエンドプロキシ。
65001 のランダムポートでリッスンするフロントエンドサービス。

Container ports

コンテナーリソースを追加すると、.NET.NET Aspire はコンテナーにランダムなポートを自動的に割り当てます。コンテナーポートを指定するには、目的のポートを使用してコンテナーリソースを構成します。

builder.AddContainer("frontend", "mcr.microsoft.com/dotnet/samples", "aspnetapp")
       .WithHttpEndpoint(port: 8000, targetPort: 8080);

上記のコード:

frontend イメージから mcr.microsoft.com/dotnet/samples:aspnetappという名前のコンテナーリソースを作成します。
ホストをポート 8000 にバインドし、コンテナーのポート 8080 にマッピングすることで、http エンドポイントを公開します。

次の図を考えてみましょう。

docker ホストを使用してフロントエンドアプリのネットワーク図を .NET.NET Aspire します。

エンドポイント拡張メソッド

IResourceWithEndpoints インターフェイスを実装するすべてのリソースは、WithEndpoint 拡張メソッドを使用できます。この拡張機能にはいくつかのオーバーロードがあり、スキーム、コンテナーポート、ホストポート、環境変数名、およびエンドポイントがプロキシされるかどうかを指定できます。

また、エンドポイントを構成するデリゲートを指定できるオーバーロードもあります。これは、環境またはその他の要因に基づいてエンドポイントを構成する必要がある場合に便利です。次のコードについて考えてみましょう。

builder.AddProject<Projects.Networking_ApiService>("apiService")
       .WithEndpoint(
            endpointName: "admin",
            callback: static endpoint =>
       {
           endpoint.Port = 17003;
           endpoint.UriScheme = "http";
           endpoint.Transport = "http";
       });

上記のコードは、エンドポイントを構成するためのコールバックデリゲートを提供します。エンドポイントは admin という名前で、http スキームとトランスポート、および 17003 ホストポートを使用するように構成されます。コンシューマーは、このエンドポイントを名前で参照します。次の AddHttpClient 呼び出しを検討してください。

builder.Services.AddHttpClient<WeatherApiClient>(
    client => client.BaseAddress = new Uri("http://_admin.apiservice"));

Uri は、admin sentinel のプレフィックスが付いた _ エンドポイント名を使って構築されています。これは、admin セグメントが apiservice サービスに属するエンドポイント名であることを示す規則です。詳細については、.NET.NET Aspire サービス検出を参照してください。

Additional considerations

WithEndpoint 拡張メソッドを呼び出すと、callback オーバーロードは生の EndpointAnnotationを公開します。これにより、コンシューマーはエンドポイントのさまざまな側面をカスタマイズできます。

AllocatedEndpoint プロパティを使用すると、サービスのエンドポイントを取得または設定できます。 IsExternal プロパティと IsProxied プロパティは、エンドポイントの管理方法と公開方法を決定します。IsExternal はパブリックにアクセスできるかどうかを決定します。一方、IsProxied は DCP が管理し、内部ポートの違いとレプリケーションを可能にします。

Tip

独自のプロキシを実行し、DCP が既にポートをバインドしているためにポートバインドの問題が発生する外部実行可能ファイルをホストしている場合は、IsProxied プロパティを falseに設定してみてください。これにより、DCP がプロキシを管理できなくなり、実行可能ファイルがポートを正常にバインドできるようになります。

Name プロパティはサービスを識別しますが、Port プロパティと TargetPort プロパティは、それぞれ必要なポートとリッスンしているポートを指定します。

ネットワーク通信の場合、Protocol プロパティは TCP と UDPをサポートし、今後さらに多くの可能性が生じる可能性があり、Transport プロパティはトランスポートプロトコル (HTTP、HTTP2、HTTP3) を示します。最後に、サービスが URI アドレス指定可能な場合、UriScheme プロパティはサービス URI を構築するための URI スキームを提供します。

詳細については、EndpointAnnotation プロパティの使用可能なプロパティを参照してください。

Endpoint filtering

すべての .NET.NET Aspire プロジェクトリソースエンドポイントは、一連の既定のヒューリスティックに従います。一部のエンドポイントは実行時に ASPNETCORE_URLS に含まれており、一部は HTTP/HTTPS_PORTSとして公開され、一部の構成は Kestrel 構成から解決されます。既定の動作に関係なく、WithEndpointsInEnvironment 拡張メソッドを使用して、環境変数に含まれるエンドポイントをフィルター処理できます。

builder.AddProject<Projects.Networking_ApiService>("apiservice")
    .WithHttpsEndpoint() // Adds a default "https" endpoint
    .WithHttpsEndpoint(port: 19227, name: "admin")
    .WithEndpointsInEnvironment(
        filter: static endpoint =>
        {
            return endpoint.Name is not "admin";
        });

上記のコードでは、既定の HTTPS エンドポイントと、ポート 19227 の admin エンドポイントが追加されます。ただし、admin エンドポイントは環境変数から除外されます。これは、内部使用専用のエンドポイントを公開する場合に便利です。

次の方法で共有

.NET .NET Aspire 内部ループ ネットワークの概要

内部ループでのネットワーク

エンドポイントのしくみ

コンテナー ネットワークの管理方法

Launch profiles

Kestrelによって構成されたエンドポイント

ポートとプロキシ

ホスト ポートを省略する

Container ports

エンドポイント拡張メソッド

Additional considerations

Endpoint filtering

フィードバック

その他のリソース

.NET .NET Aspire 内部ループネットワークの概要

コンテナーネットワークの管理方法

ホストポートを省略する