.NET .NET Aspire 協調流程概觀

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

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

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

注意

.NET .NET Aspire的協調流程旨在藉由簡化雲端原生應用程式的設定和互連的管理，來增強 本機開發 體驗。 雖然它是一個寶貴的開發工具，但它並不是用來取代生產環境系統，例如 Kubernetes，這些系統特別設計在該環境中表現出色。

定義應用程式模型

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

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

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

var builder = DistributedApplication.CreateBuilder(args);

// Add resources to the app model

builder.Build().Run();

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

應用程式主機專案

應用程式主項目會處理執行屬於 .NET.NET Aspire 專案的所有專案。 換句話說，它負責協調應用程式模型內的所有應用程式。 專案本身是一個可執行專案，參考了 .NET NuGet 套件，並使用 📦。

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

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

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

    <!-- Omitted for brevity -->

</Project>

下列程式碼描述了應用程式主機 Program，該主機具有兩個項目參考，以及一個 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")
       .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 方法來建置並執行應用程式模型。

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

若要協助將應用程式主機專案與其描述的資源之間的關聯性可視化，請考慮下圖：

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

內建資源類型

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

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

項目資源代表屬於應用程式模型的 .NET 專案。 當您將項目參考新增至應用程式主專案時，.NET.NET Aspire SDK 會在每個參考專案的 Projects 命名空間中產生類型。 如需詳細資訊，請參閱 .NET.NET Aspire SDK：項目參考。

若要將專案新增至應用程式模型，請使用 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」 項目資源的三個複本新增至應用程式模型。 如需詳細資訊，請參閱 .NET.NET Aspire 儀表板：資源復本。

參考資源

參考代表資源之間的相依性。 例如，您可能會想像 Web 前端相依於快取的 Redis 案例。 請考慮下列範例應用程式主機 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連線到 .NET 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)	services__apiservice__http__0="http://localhost:5455" services__apiservice__https__0="https://localhost:7356"

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

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

• WithEndpoint
• WithHttpEndpoint
• WithHttpsEndpoint

然後呼叫 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)	services__myapp__endpoint__0=https://localhost:9043

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

服務端點環境變數格式

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

當某個資源相依於另一個資源時，應用程式主機會將環境變數插入相依資源。 這些環境變數設定相依資源以連接到其所依賴的資源。 環境變數的格式專屬於 .NET.NET Aspire，並以與 Service Discovery相容的方式表示服務端點。

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

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

services__apiservice__http__0

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

services__apiservice__myendpoint__0

在上述範例中，apiservice 服務具有名為 myendpoint的具名端點。 環境變數的值是服務端點的URL。

參考現有的資源

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

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

執行上下文

IDistributedApplicationBuilder 會揭露執行環境（DistributedApplicationExecutionContext），以提供應用程式主機目前執行的相關資訊。 此內容可用來評估應用程式主機是否以「執行」模式執行，或作為發佈作業的一部分。 請考慮下列屬性：

• 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();

在上述程式代碼中：

• 如果應用程式主機處於「執行」模式，則會 Redis 新增容器資源。
• 如果應用程式主機處於「發佈」模式，則會新增連接字串。

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

重要

.NET .NET Aspire 提供常見的 API 來控制資源產生器的形式，讓資源根據執行模式以不同的方式運作。 Fluent API 前面會加上 RunAs* 和 PublishAs*。 RunAs* API 會影響本機開發（或執行模式）行為，而 PublishAs* API 會影響資源的發佈。 如需 Azure 資源如何使用這些 API 的詳細資訊，請參閱 使用現有的 Azure 資源。

另請參閱

• 在.NET.NET Aspire內協調資源
• .NET .NET Aspire 整合概觀
• .NET .NET Aspire SDK
• .NET .NET Aspire中的事件
• 在中的服務發現
• .NET .NET Aspire 服務預設值
• 表示外部參數
• .NET .NET Aspire 內部循環網路概觀