Aspire 協調流程概觀

Aspire 提供 API，用於在分散式應用程式內表達資源和相依性。除了這些 API 之外，還有一些工具可以支援數個引人注目的場景。協調器用於 本機開發 目的，而且不支援在生產環境中使用。

在繼續之前，請考慮以下中使用的一些常用術語 Aspire：

應用程式模型：組成分散式應用程式的資源集合（DistributedApplication），定義於 Aspire.Hosting.ApplicationModel 命名空間內。如需更正式的定義，請參閱定義應用程式模型。
AppHost/Orchestrator 專案： .NET 協調 應用程式模型的專案，以 *.AppHost 尾碼（依慣例）。
資源：資源是應用程式的相依部分，例如 .NET 專案、容器、可執行檔、資料庫、快取或雲端服務。它代表可以管理或參考之應用程式的任何部分。
整合：整合是 AppHost 的 NuGet 套件，可建立資源模型，或是設定用戶端以用於取用應用程式的套件。如需詳細資訊，請參閱 Aspire 整合概觀。
參考：參考會定義資源之間的關係，以相依性表示，使用 WithReference API。如需詳細資訊，請參閱參考資源或參考現有資源。

注意

Aspire的編排旨在透過簡化雲端原生應用程式配置和互連的管理來增強您的 本地開發 體驗。雖然它是一個寶貴的開發工具，但它並不是用來取代生產環境系統，例如 Kubernetes，這些系統特別設計在該環境中表現出色。

定義應用程式模型

Aspire 可讓您有效率地建置、佈建、部署、設定、測試、執行及監控分散式應用程式。這些功能是由 應用程式模型所提供，該模型會定義解決方案中的 Aspire 資源及其互連。

應用程式模型不只是資源清單，它代表應用程式的完整拓撲。這包括資源、其相依性和組態之間的關聯性。資源可以包含應用程式所依賴的專案、可執行檔、容器、外部服務和雲端資源。

在您的 AppHost 專案中Aspire，您的Program檔案會定義您的應用程式模型：

var builder = DistributedApplication.CreateBuilder(args);

// Add resources to the app model

builder.Build().Run();

當您呼叫 DistributedApplication.CreateBuilder時，會取得的 IDistributedApplicationBuilder實例，用來設定應用程式模型。此產生器提供方法來新增資源、定義相依性，以及設定應用程式的整體結構。新增資源之後，請呼叫 Build 以建立應用程式模型。範本包含鏈結呼叫Build()的程式代碼，該代碼傳回DistributedApplication實例，然後呼叫Run()。

AppHost 專案

AppHost 專案會處理執行屬於專案一部分 Aspire 的所有專案。換句話說，它負責協調應用程式模型內的所有應用程式。專案本身是.NET使用 SDK 的Aspire可執行專案。從Aspire 13.0開始，可以設定Aspire.AppHost.Sdk為唯一的專案 SDK，這會隱含地將套件參考加入📦Aspire.Hosting.AppHost NuGet 套件。

<Project Sdk="Aspire.AppHost.Sdk/13.0.0">
    
    <PropertyGroup>
        <OutputType>Exe</OutputType>
        <TargetFramework>net10.0</TargetFramework>
        <!-- Omitted for brevity -->
    </PropertyGroup>

    <!-- Omitted for brevity -->

</Project>

注意

明確列出 SDK 和套件參考的替代方法仍然有效，而且不需要變更現有專案：

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

    <Sdk Name="Aspire.AppHost.Sdk" Version="13.0.0" />
    
    <PropertyGroup>
        <OutputType>Exe</OutputType>
        <TargetFramework>net10.0</TargetFramework>
        <!-- Omitted for brevity -->
    </PropertyGroup>

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

    <!-- Omitted for brevity -->

</Project>

下列程式碼描述具有兩個專案參考和快Program取的 AppHostRedis：

var builder = DistributedApplication.CreateBuilder(args);

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

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

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

builder.Build().Run();

上述程式代碼：

使用 CreateBuilder 方法建立新的應用程式模型建立器。
使用 Redis 方法，新增名為「cache」的 cacheAddRedis 資源。
使用 AddProject 方法新增名為「apiservice」的項目資源。
使用 AddProject 方法新增名為「webfrontend」的項目資源。
- 指定專案具有使用 WithExternalHttpEndpoints 方法的外部 HTTP 端點。
- 新增 cache 資源的參考，等待它準備妥當，然後使用 WithReference 和 WaitFor 方法。
- 新增 apiservice 資源的參考，等待它準備妥當，然後使用 WithReference 和 WaitFor 方法。
使用 Build 和 Run 方法來建置並執行應用程式模型。

範例程式代碼會使用主機整合 AspireRedis。

為了協助視覺化 AppHost 專案與其描述的資源之間的關係，請考慮下圖：

每個資源都必須以唯一方式命名。此圖顯示每個資源及其之間的關聯性。容器資源名為“cache”，專案資源的名稱為 “apiservice” 和 “webfrontend”。 Web 前端項目會參考快取和 API 服務專案。當您以這種方式表達參考時，網站前端專案會指出其相依於這兩個資源，分別是「快取」和「API 服務」。

內建資源類型

Aspire 專案是由一組資源所組成。在 📦Aspire.Hosting.AppHost NuGet 套件中，主要的基礎資源類型如下表所示：

方法	資源類型	描述
AddProject	ProjectResource	.NET 專案，例如 ASP.NET Core Web 應用程式。
`AddCSharpApp`	`CSharpAppResource`	C# 專案或檔案型應用程式，例如 .cs 檔案、 .csproj 檔案或專案目錄。
AddContainer	ContainerResource	容器映像檔，例如 Docker 映像檔。
AddExecutable	ExecutableResource	可執行檔案，例如 Node.js 應用程式。
AddParameter	ParameterResource	參數資源，可用來表示外部參數。

項目資源代表屬於應用程式模型的 .NET 專案。當您將專案參考新增至 AppHost 專案時， Aspire SDK 會在命名空間中 Projects 為每個參考專案產生類型。如需詳細資訊，請參閱 Aspire SDK：專案參考。或者，您可以使用該 AddCSharpApp 方法新增 C# 專案或檔案型應用程式，而無需專案參考。

若要將專案新增至應用程式模型，請使用 AddProject 方法：

var builder = DistributedApplication.CreateBuilder(args);

// Adds the project "apiservice" of type "Projects.AspireApp_ApiService".
var apiservice = builder.AddProject<Projects.AspireApp_ApiService>("apiservice");

您可以透過將相同專案的多個實例新增至應用程式模型，以複製並擴展專案的規模。若要設定複本，請使用 WithReplicas 方法：

var builder = DistributedApplication.CreateBuilder(args);

// Adds the project "apiservice" of type "Projects.AspireApp_ApiService".
var apiservice = builder.AddProject<Projects.AspireApp_ApiService>("apiservice")
                        .WithReplicas(3);

上述程式代碼會將「apiservice」項目資源的三個複本新增至應用程式模型。如需詳細資訊，請參閱 Aspire 儀表板：資源複本。

C# 應用程式資源代表屬於應用程式模型一部分的 C# 專案或檔案型應用程式。不同於 AddProject需要專案參考的，此 AddCSharpApp 方法可以使用 *.cs 檔案、 *.csproj 檔案或專案目錄的路徑來新增 C# 專案或檔案型應用程式。這對於新增 10 中 .NET 引入的檔案型應用程式或包含專案而不將專案參考新增至 AppHost 非常有用。

若要將 C# 應用程式新增至應用程式模型，請使用以下 AddCSharpApp 方法：

var builder = DistributedApplication.CreateBuilder(args);

// Adds a file-based C# app "inventoryservice" from a .cs file.
var inventoryService = builder.AddCSharpApp("inventoryservice", @"..\InventoryService.cs");

// Adds a C# project "catalogservice" from a project directory.
var catalogService = builder.AddCSharpApp("catalogservice", @"..\CatalogService");

該 AddCSharpApp 方法支援與 AddProject相同的配置選項，包括副本、環境變數和資源依賴關係。

注意

此 AddCSharpApp 方法會標示為實驗性，且需要 .NET 10 個 SDK 才能支援檔案型 C# 應用程式。如需檔案型應用程式的詳細資訊，請參閱 9.5 中的 Aspire 新功能文件。

參考資源

參考代表資源之間的相依性。例如，您可能會想像 Web 前端相依於快取的 Redis 案例。請考慮下列範例 AppHost Program C# 程式碼：

var builder = DistributedApplication.CreateBuilder(args);

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

builder.AddProject<Projects.AspireApp_Web>("webfrontend")
       .WithReference(cache);

“webfrontend” 專案資源使用 WithReference 新增對「快取」容器資源的依賴。這些相依性可以代表連接字串或服務探索資訊。在上述範例中，環境變數會插入名為 ConnectionStrings__cache的 “webfrontend” 資源。此環境變數包含連接字串，webfrontend 用來透過 Redis連線到 Aspire，例如，Redis。

連線字串和端點參考

通常表示專案資源之間的相依性。請考慮下列範例程式代碼：

var builder = DistributedApplication.CreateBuilder(args);

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

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

builder.AddProject<Projects.AspireApp_Web>("webfrontend")
       .WithReference(cache)
       .WithReference(apiservice);

專案間參考的處理方式與具有定義良好連接字串的資源的處理不同。與其將連接字串注入到「webfrontend」資源中，不如注入支援服務發現的環境變數。

方法	環境變數
`WithReference(cache)`	`ConnectionStrings__cache="localhost:62354"`
`WithReference(apiservice)`	`APISERVICE_HTTP="http://localhost:5455"` `APISERVICE_HTTPS="https://localhost:7356"` `services__apiservice__http__0="http://localhost:5455"` `services__apiservice__https__0="https://localhost:7356"`

將「apiservice」專案新增為參考，會使服務探索環境變數新增至前端。這是因為通常透過 HTTP/gRPC 進行項目對項目通訊。

Aspire 插入兩種類型的環境變數以供服務參考：

簡化格式（例如：APISERVICE_HTTP）：使用{RESOURCENAME}_{ENDPOINTNAME}的大寫模式。這種格式更簡單，更適合非.NET 語言和多語言場景。
.NET 服務探索格式（例如：services__apiservice__http__0）：使用小寫模式services__{servicename}__{endpointname}__{index}。由.NET的配置型服務發現使用此格式。

如需詳細資訊，請參閱服務發現Aspire。

若要從 ContainerResource 或 ExecutableResource取得特定端點，請使用下列其中一個端點 API：

然後呼叫 GetEndpoint API 以取得端點，以便在 WithReference 方法中引用該端點：

var builder = DistributedApplication.CreateBuilder(args);

var customContainer = builder.AddContainer("myapp", "mycustomcontainer")
                             .WithHttpEndpoint(port: 9043, name: "endpoint");

var endpoint = customContainer.GetEndpoint("endpoint");

var apiservice = builder.AddProject<Projects.AspireApp_ApiService>("apiservice")
                        .WithReference(endpoint);

方法	環境變數
`WithReference(endpoint)`	`MYAPP_ENDPOINT="https://localhost:9043"` `services__myapp__endpoint__0="https://localhost:9043"`

port 參數是容器正在接聽的埠。如需容器埠的詳細資訊，請參閱容器埠。如需服務探索的詳細資訊，請參閱服務Aspire探索。

服務端點環境變數格式

在上一節中，會使用 WithReference 方法來表示資源之間的相依性。當服務端點使得環境變數被插入到相依資源中時，格式可能不容易看出。本節提供可用格式的詳細資訊。

當一個資源相依於另一個資源時，AppHost 會將環境變數插入相依資源。這些環境變數設定相依資源以連接到其所依賴的資源。 Aspire 提供兩種環境變數格式，以支援不同的場景：

簡化格式（多語言友好）

簡化的格式使用大寫的模式 {RESOURCENAME}_{ENDPOINTNAME} 。此格式更容易從非.NET 語言使用，建議用於多語言案例。

請考慮下列環境變數範例：

APISERVICE_HTTP
APISERVICE_HTTPS

上述環境變數表示服務的 HTTP 和 HTTPS 端點 apiservice 。具名端點可能會以下列方式表示：

APISERVICE_MYENDPOINT

在上述範例中，apiservice 服務具有名為 myendpoint的具名端點。

注意

環境變數名稱是以資源名稱為基礎，而不是選用的連線名稱參數。即使使用 WithReference(resource, "customname") 來指定自訂連線名稱，產生的環境變數仍會使用資源的名稱（例如 APISERVICE_HTTP），而不是自訂名稱。

.NET 服務探索格式

.NET 服務探索格式由 .NET 的配置型服務探索所使用。服務端點環境變數名稱前面會加上 services__ （雙底線），然後是服務名稱、端點名稱，最後是索引。索引支援單一服務的多個端點，從第一個端點的 0 開始，並針對每個端點遞增。

請考慮下列環境變數範例：

services__apiservice__http__0
services__apiservice__https__0

上述環境變數表示服務的第一個 HTTP 和 HTTPS 端點 apiservice 。具名端點可能會以下列方式表示：

APISERVICE_MYENDPOINT

在上述範例中，apiservice 服務具有名為 myendpoint的具名端點。

將特定端點與 WithEnvironment 搭配使用

若要指定特定端點的自訂環境變數名稱，請使用結合WithEnvironment GetEndpoint的方法：

var projectA = builder.AddProject<Projects.ProjectA>("projecta");
var projectB = builder.AddProject<Projects.ProjectB>("projectb")
                      .WithEnvironment("PROJECTA_URL", projectA.GetEndpoint("https"));

這會產生具有服務 HTTPS 端點 URL PROJECTA_URL 的單一環境變數projecta。

參考現有的資源

在某些情況下，您應該參考現有的資源，這些資源可能是部署到雲端提供者的。例如，您可能想要參考 Azure 資料庫。在此情況下，您將依賴執行內容來動態判斷 AppHost 是在「執行」模式或「發佈」模式中執行。如果您要在本機執行並想要依賴雲端資源，您可以使用 IsRunMode 屬性來有條件地新增參考。您可以選擇改為在發佈模式中建立資源。有些主機整合功能支援提供直接的連接字串，可用來參考現有的資源。

同樣地，您可能想要整合 Aspire 到現有解決方案中的使用案例。一種常見的方法是將 AppHost 專案新增至 Aspire 現有解決方案。在 AppHost 中，您會將專案參考新增至 AppHost 並建置應用程式模型，以表達相依性。例如，某個專案可能相依於另一個專案。這些相依性會使用 WithReference 方法來表示。如需詳細資訊，請參閱將 Aspire 新增至現有的 .NET 應用程式。

執行上下文

IDistributedApplicationBuilder會公開執行內容（DistributedApplicationExecutionContext），其提供 AppHost 目前執行的相關信息。此內容可用來評估 AppHost 是否以「執行」模式執行，或作為發佈作業的一部分執行。請考慮下列屬性：

IsRunMode：如果目前作業正在執行，則傳回 true。
IsPublishMode：如果目前正在發佈作業，則傳回 true。

當您想要根據目前作業有條件地執行程式碼時，這項資訊很有用。請考慮下列範例，示範如何使用 IsRunMode 屬性。在此情況下，擴充方法是用來為 RabbitMQ 的本地開發執行產生穩定的節點名稱。

private static IResourceBuilder<RabbitMQServerResource> RunWithStableNodeName(
    this IResourceBuilder<RabbitMQServerResource> builder)
{
    if (builder.ApplicationBuilder.ExecutionContext.IsRunMode)
    {
        builder.WithEnvironment(context =>
        {
            // Set a stable node name so queue storage is consistent between sessions
            var nodeName = $"{builder.Resource.Name}@localhost";
            context.EnvironmentVariables["RABBITMQ_NODENAME"] = nodeName;
        });
    }

    return builder;
}

執行內容通常用來有條件地新增指向現有資源的資源或連接字串。請考慮下列範例，示範根據執行內容有條件地新增 Redis 或連接字串：

var builder = DistributedApplication.CreateBuilder(args);

var redis = builder.ExecutionContext.IsRunMode
    ? builder.AddRedis("redis")
    : builder.AddConnectionString("redis");

builder.AddProject<Projects.WebApplication>("api")
       .WithReference(redis);

builder.Build().Run();

在上述程式代碼中：

如果 AppHost 處於「執行」模式， Redis 則會新增容器資源。
如果 AppHost 處於「發佈」模式，則會新增連接字串。

當您在本機執行時，可以輕鬆地反轉此邏輯來連線到現有的 Redis 資源，並在發佈時建立新的 Redis 資源。

重要

Aspire 提供通用的API來控制資源建構器的模態，允許資源根據執行模式的不同行為。 Fluent API 前面會加上 RunAs* 和 PublishAs*。 RunAs* API 會影響本機開發（或執行模式）行為，而 PublishAs* API 會影響資源的發佈。如需 Azure 資源如何使用這些 API 的詳細資訊，請參閱使用現有的 Azure 資源。

另請參閱

意見反應

此頁面對您有幫助嗎？

Last updated on 2025-11-11