.NET .NET Aspire 內部循環網路概觀

發行項
12/12/2024

使用 .NET.NET Aspire 進行開發的優點之一，就是可讓您在本機開發、測試及偵錯雲端原生應用程式。內部循環網路是 .NET.NET Aspire 的重要層面，可讓您的應用程式在開發環境中彼此通訊。在本文中，您將學習 .NET.NET Aspire 如何使用代理、端點、端點設定和啟動設定檔來處理各種網路情境。

內部迴圈中的網路功能

內迴圈是在本機開發和測試應用程式的過程，然後再將其部署到目標環境。 .NET .NET Aspire 提供數個工具和功能，以簡化和增強內部迴圈中的網路體驗，例如：

啟動設定檔：啟動設定檔是指定如何在本機執行應用程式的組態檔。您可以使用啟動設定檔（例如 launchSettings。json 檔案）來定義應用程式的端點、環境變數和啟動設定。
Kestrel 組態：Kestrel 組態可讓您指定 Kestrel Web server 接聽的端點。您可以在應用程式設定中設定 Kestrel 端點，.NET.NET Aspire 會自動使用這些設定來建立端點。
端點/端點組態：端點是您應用程式與其相依服務之間的連線，例如資料庫、消息佇列或 API。端點會提供服務名稱、主機埠、配置和環境變數等資訊。您可以透過隱含方式（透過啟動設定檔）或明確地呼叫 WithEndpoint，將端點新增至您的應用程式。
Proxy：.NET.NET Aspire 會自動針對您新增至應用程式的每個服務系結啟動 Proxy，並指派 Proxy 接聽的埠。然後，代理伺服器會將要求轉送至您的應用程式所接聽的埠，這可能與代理伺服器的埠不同。如此一來，您就可以避免埠衝突，並使用一致且可預測的URL來存取您的應用程式和服務。

端點的運作方式

.NET .NET Aspire 中的服務系結牽涉到兩個整合：服務代表應用程式所需的外部資源（例如資料庫、消息佇列或 API），以及系結，以建立應用程式和服務之間的連線並提供必要資訊。

.NET .NET Aspire 支援兩種服務綁定類型：隱含，由指定的啟動概要自動建立以定義應用程式在不同環境中的行為；明確，則是透過 WithEndpoint手動建立。

創建綁定時，無論是隱含還是明確，.NET.NET Aspire 會在指定的端口上啟動輕量級反向代理，為來自應用程式的請求進行服務的路由和負載均衡。代理是 .NET.NET Aspire 實作細節，不需要任何設定或管理上的關注。

若要協助可視化端點的運作方式，請考慮 .NET.NET Aspire 入門範本內部循環網路圖表：

啟動設定檔

當您呼叫 AddProject時，應用程式主機會尋找 Properties/launchSettings。json 用來判斷預設的端點集。應用程式主機會使用下列規則來選取特定的啟動設定檔：

呼叫 launchProfileName時傳遞的明確 AddProject 自變數。
DOTNET_LAUNCH_PROFILE 環境變數。如需詳細資訊，請參閱環境變數。
在 launchSettings 中定義的第一個啟動配置檔案。json。

考慮以下 啟動設定。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 啟動設定檔，請在 launchSettings 中設定兩者 applicationUrl 值。json 檔案。這些 URL 可用來建立此專案的端點。這相當於：

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

重要

如果沒有 launchSettings。json（或啟動配置檔），預設不會有任何系結。

如需詳細資訊，請參閱 .NET.NET Aspire 和啟動配置檔。

Kestrel 設定的端點

.NET .NET Aspire 支援 Kestrel 端點設定。例如，請考慮一個專案的 appsettingsjson 檔案，其中定義了一個 Kestrel 端點，使用 HTTPS 協定和埠 5271。

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

上述組態會指定 Https 端點。 Url 屬性設定為 https://*:5271，這表示端點會在埠 5271 上接聽所有介面。如需詳細資訊，請參閱為 ASP.NET Core Kestrel 網頁 server設定端點。

設定 Kestrel 端點後，專案應該從 json 檔案中移除任何已設定的。

注意

如果 applicationUrl 存在於 launchSettings 中。json 檔案和 Kestrel 端點已設定，應用程式主機將會擲回例外狀況。

當您新增項目資源時，有一個多載可讓您指定應該使用Kestrel端點，而不是 launchSettings。json 檔案：

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

如需詳細資訊，請參閱 AddProject。

端口和代理伺服器

當定義服務綁定時，主機端口一律提供給位於服務前方的代理。這可讓服務的單一或多個復本運作方式類似。此外，所有使用 WithReference API 的資源相依性都依賴於環境變數中的代理端點。

請考慮以下呼叫 AddProject、WithHttpEndpoint和 WithReplicas的方法鏈：

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

上述程式代碼會產生下列網路圖表：

上圖描述下列各項：

網頁瀏覽器作為應用程式的進入點。
主機埠 5066。
位於網頁瀏覽器與前端服務複本之間的前端代理伺服器，接聽 5066 埠。
已指派隨機埠號65001，frontend_0前端服務複本正在此埠上進行接聽。
在隨機分配的端口 65002 上監聽 frontend_1 前端服務複本。

如果沒有呼叫 WithReplicas，則只有一個前端服務。代理伺服器依然監聽在埠 5066，但前端服務會監聽在隨機的埠上：

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

已定義兩個埠：

主機埠 5066。
基礎服務將系結至的隨機 Proxy 埠。

上圖描述下列各項：

網頁瀏覽器作為應用程式的進入點。
主機埠 5066。
位於網頁瀏覽器與前端服務之間的前端代理伺服器，負責監聽5066埠口。
接聽隨機埠 65001 的前端服務。

基礎服務會透過專案資源的 ASPNETCORE_URLS 來提供此埠。在服務系結上指定環境變數，以存取此埠的其他資源：

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

上述程式代碼會在 PORT 環境變數中提供隨機埠。應用程式會使用此埠接聽來自 Proxy 的連入連線。請考慮下圖：

上圖描述下列各項：

網頁瀏覽器作為應用程式的進入點。
主機埠 5067。
介於網頁瀏覽器與前端服務之間的前端代理，負責監聽埠 5067。
接聽環境 65001 的前端服務。

提示

若要避免端點被 proxy，請在呼叫 IsProxied 擴充方法時，將 false 屬性設定為 WithEndpoint。如需詳細資訊，請參閱端點延伸模組：的其他考慮。

省略主機埠

當您省略主機埠時，.NET.NET Aspire 會產生主機和服務埠的隨機埠。當您想要避免埠衝突且不在意主機或服務埠時，這會很有用。請考慮下列程式代碼：

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

在此案例中，主機和服務埠都是隨機的，如下圖所示：

上圖描述下列各項：

網頁瀏覽器作為應用程式的進入點。
一個隨機的主機埠：65000。
位於網頁瀏覽器與前端服務之間的前端代理（Proxy），監聽 65000 埠口。
接聽隨機埠 65001 的前端服務。

貨櫃港口

當您新增容器資源時，.NET.NET Aspire 會自動將隨機埠指派給容器。若要指定容器埠，請配置容器資源並設定所需的埠：

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

上述程式代碼：

從 mcr.microsoft.com/dotnet/samples:aspnetapp 映射建立名為 frontend的容器資源。
藉由將主機系結至埠 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 管理 proxy，讓您的可執行檔能成功綁定端口。

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 設定的端點

端口和代理伺服器

省略主機埠

貨櫃港口

端點擴充方法

其他考慮

端點篩選

其他資源