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

[アーティクル]
12/15/2024

.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 スターターテンプレートの内部ループネットワーク図を検討してください。

起動プロファイル

AddProjectを呼び出すと、アプリホストは Properties/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 値の両方を launchSettingsjson ファイルで構成します。これらの URL は、このプロジェクトのエンドポイントを作成するために使用されます。これは次に相当します。

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

大事な

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

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

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

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

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

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

Kestrel エンドポイントが構成されている場合、launchSettings から構成された applicationUrl をプロジェクトから削除するようにしてください。これは、json ファイルです。

手記

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

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

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 でリッスンしているフロントエンドサービス。

ヒント

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

ホストポートを省略する

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

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

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

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

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

コンテナーポート

コンテナーリソースを追加すると、.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 エンドポイントを公開します。

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

フロントエンドアプリのネットワーキング図を示すために、 .NET Aspire し、docker ホストを使用します。

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

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 サービス検出を参照してください。

その他の考慮事項

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

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

ヒント

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

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

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

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

エンドポイントのフィルター処理

すべての .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 内部ループネットワークの概要

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

エンドポイントのしくみ

起動プロファイル

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

ポートとプロキシ

ホストポートを省略する

コンテナーポート

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

その他の考慮事項

エンドポイントのフィルター処理

その他のリソース

次の方法で共有

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

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

エンドポイントのしくみ

起動プロファイル

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

ポートとプロキシ

ホスト ポートを省略する

コンテナー ポート

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

その他の考慮事項

エンドポイントのフィルター処理

その他のリソース

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

ホストポートを省略する

コンテナーポート