Aspire 內環網路概述

使用進行 Aspire 開發的優點之一是它使您能夠在本機開發、測試和調試雲端原生應用程式。內部迴圈網路是其中一個關鍵層面 Aspire ，可讓您的應用程式在開發環境中彼此通訊。在本文中，您將瞭解如何使用 Aspire Proxy、端點、端點設定和啟動設定檔來處理各種網路案例。

內部迴圈中的網路連接

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

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

端點的運作方式

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

Aspire 支援兩種服務繫結型別： 隱含、根據定義不同環境中應用程式行為的指定啟動設定檔自動建立，以及 明確、使用 WithEndpoint手動建立。

建立繫結（無論是隱含或明確）時， Aspire 都會在指定的連接埠上啟動輕量型反向 Proxy，處理從應用程式到服務的請求的路由和負載平衡。 Proxy 是一個 Aspire 實作細節，不需要設定或管理。

為了協助視覺化端點的運作方式，請考慮 Aspire 入門範本內部迴圈網路圖：

容器網路管理方式

當您新增一或多個容器資源時， Aspire 會建立專用的容器橋接器網路，以啟用容器之間的服務探索。此網橋網路是一個虛擬網路，可讓容器彼此通訊，並透過使用 DNS 名稱的 DNS 伺服器提供容器對容器的服務探索。

網路的存留期取決於容器資源：

如果所有容器都有工作階段存留期，則網路也是以工作階段為基礎，並在 AppHost 程序結束時清除。
如果任何容器具有持續性生命週期，則網路是持久性的，並在 AppHost 進程終止後保持執行。 Aspire 在後續執行中重複使用此網路，即使 AppHost 未執行，也允許持久性容器繼續通訊。

如需容器存留期的詳細資訊，請參閱容器資源存留期。

以下是容器網路的命名慣例：

工作階段網路： aspire-session-network-<unique-id>-<app-host-name>
持續性網路： aspire-persistent-network-<project-hash>-<app-host-name>

每個 AppHost 執行個體都會取得自己的網路資源。唯一的差異在於網路的存留期和名稱;服務探索的運作方式與兩者相同。

容器會使用其資源名稱在網路上自行註冊。 Aspire 會使用此名稱進行容器之間的服務探索。例如，pgadmin 容器可以透過 postgres 連接到名為 postgres:5432 的資料庫資源。

Note

主機服務，例如專案或其他可執行檔，不會使用容器網路。它們依賴公開的容器埠來進行服務探索和與容器的通訊。如需服務探索的詳細資訊，請參閱服務探索概觀。

啟動設定檔

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

呼叫 launchProfileName 時傳遞的明確 AddProject 參數。
DOTNET_LAUNCH_PROFILE 環境變數。如需詳細資訊，請參閱環境變數。
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（或啟動配置檔），則預設不會有任何系結。

如需詳細資訊，請參閱 Aspire 並啟動設定檔。

Kestrel 設定的端點

Aspire 支援 Kestrel 端點設定。例如，想像一個專案使用 appsettings.json 檔案來定義一個具有 HTTPS 協議和埠 5271 的 Kestrel 端點：

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

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

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

Note

如果存在 applicationUrl 於 launchSettings.json 檔案中，且已設定 Kestrel 端點，則 AppHost 會擲回例外狀況。

當您新增專案資源時，可以使用多載來指定應該使用 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 上運行的前端服務。

Tip

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

省略主機埠

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

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

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

上圖描述下列各項：

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

貨櫃港口

當您新增容器資源時， 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 端點。

請考慮下圖：

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 服務的端點名稱的慣例。如需詳細資訊，請參閱服務發現Aspire。

其他考慮

呼叫 WithEndpoint 擴充方法時，callback 多載會公開原始 EndpointAnnotation，使使用者能自訂端點的多個層面。

AllocatedEndpoint 屬性可讓您取得或設定服務的端點。 IsExternal 和 IsProxied 屬性會決定端點的管理和公開方式：IsExternal 決定是否應該公開存取端點，同時 IsProxied 確保 DCP 管理它，允許內部埠差異和複寫。

Tip

如果您執行一個會自行運行代理的外部可執行程式，並且因為 DCP 已經綁定埠而遇到埠綁定問題，請嘗試將 IsProxied 屬性設置為 false。這可防止 DCP 管理 proxy，讓您的可執行檔能成功綁定端口。

Name 屬性會識別服務，而 Port 和 TargetPort 屬性分別指定所需的埠和接聽埠。

對於網路通訊，Protocol 屬性支援 TCP 和 UDP，未來可能會有更多，而 Transport 屬性表示傳輸通訊協定（HTTP、HTTP2、HTTP3）。最後，如果服務可透過 URI 定址，則 UriScheme 屬性會提供用來構建服務 URI 的 URI 方案。

如需詳細資訊，請參閱 EndpointAnnotation 屬性的可用屬性。

端點篩選

所有專案資源端點都 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 端點會從環境變數中排除。當您只想要公開端點以供內部使用時，這非常有用。

意見反應

此頁面對您有幫助嗎？

Last updated on 2025-10-02

共用方式為

Aspire 內環網路概述

內部迴圈中的網路連接

端點的運作方式

容器網路管理方式

啟動設定檔

Kestrel 設定的端點

端口和代理伺服器

省略主機埠

貨櫃港口

端點擴充方法

其他考慮

端點篩選

意見反應

其他資源