部署工具產生器的 .NET.NET Aspire 指令清單格式
在本文中,您將瞭解 .NET.NET Aspire 指令清單格式。 本文可作為部署工具產生器的參考指南,協助建立工具,以在特定主控平臺上部署 .NET.NET Aspire 專案,無論是內部部署還是雲端。
.NET .NET Aspire 藉由協助管理應用程式整合之間的相互依存關係,簡化本機開發體驗。 為了協助簡化應用程式的部署,.NET Aspire 專案可以產生定義為 JSON 格式化檔案之所有資源的指令清單。
產生指令清單
產生指令清單需要有效的 .NET.NET Aspire 專案。 若要開始使用,請使用 .NET.NET Aspire 範本建立 aspire-starter
.NET 專案:
dotnet new aspire-starter --use-redis-cache `
-o AspireApp && `
cd AspireApp
使用特殊目標執行 dotnet build
來達成指令清單產生:
dotnet run --project AspireApp.AppHost\AspireApp.AppHost.csproj `
--publisher manifest `
--output-path ../aspire-manifest.json
提示
--output-path
支援相對路徑。 上一個命令會使用 ../aspire-manifest.json
將指令清單檔放在專案目錄的根目錄中。
如需詳細資訊,請參閱 dotnet run。 上一個命令會產生下列輸出:
Building...
info: Aspire.Hosting.Publishing.ManifestPublisher[0]
Published manifest to: .\AspireApp.AppHost\aspire-manifest.json
產生的檔案是 .NET.NET Aspire 指令清單,由工具用來支援部署到目標雲端環境。
注意
您也可以在啟動設定檔中產生指令清單。 請考慮下列 launchSettings。json:
{
"$schema": "http://json.schemastore.org/launchsettings.json",
"profiles": {
"generate-manifest": {
"commandName": "Project",
"launchBrowser": false,
"dotnetRunMessages": true,
"commandLineArgs": "--publisher manifest --output-path aspire-manifest.json"
}
}
}
基本指令清單格式
從預設入門範本發行指令清單,.NET Aspire 會產生下列 JSON 輸出:
{
"resources": {
"cache": {
"type": "container.v0",
"connectionString": "{cache.bindings.tcp.host}:{cache.bindings.tcp.port}",
"image": "redis:7.2.4",
"bindings": {
"tcp": {
"scheme": "tcp",
"protocol": "tcp",
"transport": "tcp",
"containerPort": 6379
}
}
},
"apiservice": {
"type": "project.v0",
"path": "../AspireApp.ApiService/AspireApp.ApiService.csproj",
"env": {
"OTEL_DOTNET_EXPERIMENTAL_OTLP_EMIT_EXCEPTION_LOG_ATTRIBUTES": "true",
"OTEL_DOTNET_EXPERIMENTAL_OTLP_EMIT_EVENT_LOG_ATTRIBUTES": "true"
},
"bindings": {
"http": {
"scheme": "http",
"protocol": "tcp",
"transport": "http"
},
"https": {
"scheme": "https",
"protocol": "tcp",
"transport": "http"
}
}
},
"webfrontend": {
"type": "project.v0",
"path": "../AspireApp.Web/AspireApp.Web.csproj",
"env": {
"OTEL_DOTNET_EXPERIMENTAL_OTLP_EMIT_EXCEPTION_LOG_ATTRIBUTES": "true",
"OTEL_DOTNET_EXPERIMENTAL_OTLP_EMIT_EVENT_LOG_ATTRIBUTES": "true",
"ConnectionStrings__cache": "{cache.connectionString}",
"services__apiservice__0": "{apiservice.bindings.http.url}",
"services__apiservice__1": "{apiservice.bindings.https.url}"
},
"bindings": {
"http": {
"scheme": "http",
"protocol": "tcp",
"transport": "http"
},
"https": {
"scheme": "https",
"protocol": "tcp",
"transport": "http"
}
}
}
}
}
指令清單格式 JSON 是由稱為 resources
的單一對象所組成,其中包含 Program.cs 中所指定之每個資源的屬性(每個名稱的 name
自變數會作為 JSON中每個子資源物件的 屬性)。
連接字串和系結參考
在上一個範例中,有兩個項目資源和一個 Redis 快取資源。 webfrontend 取決於 apiservice (project) 和 快取 (Redis) 資源。
此相依性已知,因為 webfrontend 的環境變數 包含參考其他兩個資源的佔位元:
"env": {
// ... other environment variables omitted for clarity
"ConnectionStrings__cache": "{cache.connectionString}",
"services__apiservice__0": "{apiservice.bindings.http.url}",
"services__apiservice__1": "{apiservice.bindings.https.url}"
},
在應用程式主機 apiservice
檔案中使用呼叫 webfrontend
來 WithReference(apiservice)
參考 Program.cs 資源,並使用呼叫 redis
來參考 WithReference(cache)
:
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);
builder.Build().Run();
專案資源類型之間的參考會導致 服務探索 變數插入參考專案中。 已知參考型別的參考,例如 Redis 會導致插入連接字串。
如需應用程式模型中資源及其間參考運作方式的詳細資訊,請參閱 .NET.NET Aspire 協調流程概觀。
佔位元字串結構
佔位元字串會參考 .NET.NET Aspire 指令清單的結構:
處理指令清單的工具會產生佔位元字串的最後一個區段(在此案例中為url
)。 在佔位元字串上可以使用數個後綴:
-
connectionString
:適用於已知資源類型,例如 Redis。 部署工具會將資源轉譯成最適合目標雲端環境的基礎結構,然後產生 .NET.NET Aspire 相容的連接字串,以供取用的應用程式使用。 在container.v0
資源上,connectionString
欄位可能會存在並明確指定。 這是為了支援使用 WithReference 擴充功能參考容器資源類型的案例,但需要明確地裝載為容器。 -
url
:針對需要格式正確的 URL 的服務對服務參考。 部署工具會根據指令清單中定義的配置、通訊協定和傳輸,以及已部署的基礎計算/網路拓撲,產生url
。 -
host
:URL 的主機區段。 -
port
:URL 的埠區段。
資源類型
每個資源都有 type
欄位。 當部署工具讀取指令清單時,應該讀取類型,以確認是否可以正確處理指令清單。 在 .NET.NET Aspire 預覽期間,所有資源類型都有 v0
後綴,表示它們可能會變更。 隨著 .NET.NET Aspire 方法釋放 v1
後綴,將用來表示該資源類型的指令清單結構應該視為穩定(後續更新會據以遞增版本號碼)。
一般資源欄位
type
欄位是所有資源類型中通用的唯一欄位,不過,project.v0
、container.v0
和 executable.v0
資源類型也會共用 env
和 bindings
欄位。
注意
executable.v0
資源類型並未在指令清單中完全實作,因為它在部署案例中缺少公用程式。 如需容器化可執行檔的詳細資訊,請參閱 Dockerfile 資源類型。
env
欄位型態是基本索引鍵/值對應,其中值可能包含 佔位元符字串。
系結是在 bindings
欄位中指定,每個系結都包含在 bindings
JSON 物件下自己的欄位內。
.NET 節點中 .NET Aspirebindings
指令清單省略的欄位包括:
-
scheme
:下列其中一個值tcp
、udp
、http
或https
。 -
protocol
:下列其中一個值tcp
或udp
-
transport
:與scheme
相同,但用來釐清http
與http2
之間。 -
containerPort
:如果省略預設為埠 80,則為選擇性。
[inputs
] 欄位
某些資源會產生 inputs
欄位。 此欄位用來指定資源的輸入參數。
inputs
欄位是 JSON 物件,其中每個屬性都是佔位元結構解析中使用的輸入參數。 例如,具有 connectionString
的資源可能會使用 [inputs
] 字段來指定連接字串的 password
:
"connectionString": "Host={<resourceName>.bindings.tcp.host};Port={<resourceName>.bindings.tcp.port};Username=admin;Password={<resourceName>.inputs.password};"
連接字串佔位元元會從 [password
] 字段參考 inputs
輸入參數:
"inputs": {
"password": {
"type": "string",
"secret": true,
"default": {
"generate": {
"minLength": 10
}
}
}
}
上述 JSON 代碼段會顯示具有 inputs
欄位之資源的 connectionString
欄位。
password
輸入參數是字串類型,並標示為秘密。
default
欄位是用來指定輸入參數的預設值。 在此情況下,會使用 generate
字段產生預設值,而隨機字串長度下限。
內建資源
下表是 .NET Aspire 小組所開發 .NET Aspire 和延伸模塊明確產生的資源類型清單:
與雲端無關的資源類型
這些資源可在 📦Aspire中使用。裝載 NuGet 套件。
應用程式模型使用方式 | 指令清單資源類型 | 標題連結 |
---|---|---|
AddContainer | container.v0 |
容器資源類型 |
PublishAsDockerFile |
dockerfile.v0 |
|
AddDatabase | value.v0 |
MongoDB Server 資源類型 |
AddMongoDB | container.v0 |
|
AddDatabase | value.v0 |
|
AddMySql | container.v0 |
|
AddDatabase | value.v0 |
|
AddPostgres | container.v0 |
|
AddProject | project.v0 |
項目資源類型 |
AddRabbitMQ | container.v0 |
|
AddRedis | container.v0 |
Redis 資源類型 |
AddDatabase | value.v0 |
|
AddSqlServer | container.v0 |
|
專案資源類型
範例程式代碼:
var builder = DistributedApplication.CreateBuilder(args);
var apiservice = builder.AddProject<Projects.AspireApp_ApiService>("apiservice");
範例指令清單:
"apiservice": {
"type": "project.v0",
"path": "../AspireApp.ApiService/AspireApp.ApiService.csproj",
"env": {
"OTEL_DOTNET_EXPERIMENTAL_OTLP_EMIT_EXCEPTION_LOG_ATTRIBUTES": "true",
"OTEL_DOTNET_EXPERIMENTAL_OTLP_EMIT_EVENT_LOG_ATTRIBUTES": "true"
},
"bindings": {
"http": {
"scheme": "http",
"protocol": "tcp",
"transport": "http"
},
"https": {
"scheme": "https",
"protocol": "tcp",
"transport": "http"
}
}
}
容器資源類型
範例程式代碼:
var builder = DistributedApplication.CreateBuilder(args);
builder.AddContainer("mycontainer", "myimage")
.WithEnvironment("LOG_LEVEL", "WARN")
.WithHttpEndpoint(3000);
範例指令清單:
{
"resources": {
"mycontainer": {
"type": "container.v0",
"image": "myimage:latest",
"env": {
"LOG_LEVEL": "WARN"
},
"bindings": {
"http": {
"scheme": "http",
"protocol": "tcp",
"transport": "http",
"containerPort": 3000
}
}
}
}
}
Dockerfile 資源類型
範例程式代碼:
var builder = DistributedApplication.CreateBuilder(args);
builder.AddNodeApp("nodeapp", "../nodeapp/app.js")
.WithHttpEndpoint(hostPort: 5031, env: "PORT")
.PublishAsDockerFile();
提示
需要 PublishAsDockerFile
呼叫,才能在指令清單中產生 Dockerfile 資源類型,而且這個擴充方法只能在 ExecutableResource 類型上使用。
範例指令清單:
{
"resources": {
"nodeapp": {
"type": "dockerfile.v0",
"path": "../nodeapp/Dockerfile",
"context": "../nodeapp",
"env": {
"NODE_ENV": "development",
"PORT": "{nodeapp.bindings.http.port}"
},
"bindings": {
"http": {
"scheme": "http",
"protocol": "tcp",
"transport": "http",
"containerPort": 5031
}
}
}
}
}
Postgres 資源類型
範例程式代碼:
var builder = DistributedApplication.CreateBuilder(args);
builder.AddPostgres("postgres1")
.AddDatabase("shipping");
範例指令清單:
{
"resources": {
"postgres1": {
"type": "container.v0",
"connectionString": "Host={postgres1.bindings.tcp.host};Port={postgres1.bindings.tcp.port};Username=postgres;Password={postgres1.inputs.password}",
"image": "postgres:16.2",
"env": {
"POSTGRES_HOST_AUTH_METHOD": "scram-sha-256",
"POSTGRES_INITDB_ARGS": "--auth-host=scram-sha-256 --auth-local=scram-sha-256",
"POSTGRES_PASSWORD": "{postgres1.inputs.password}"
},
"bindings": {
"tcp": {
"scheme": "tcp",
"protocol": "tcp",
"transport": "tcp",
"containerPort": 5432
}
},
"inputs": {
"password": {
"type": "string",
"secret": true,
"default": {
"generate": {
"minLength": 10
}
}
}
}
},
"shipping": {
"type": "value.v0",
"connectionString": "{postgres1.connectionString};Database=shipping"
}
}
}
RabbitMQ 資源類型
RabbitMQ 會模型化為容器資源 container.v0
。 下列範例示範如何將它們新增至應用程式模型。
var builder = DistributedApplication.CreateBuilder(args);
builder.AddRabbitMQ("rabbitmq1");
上述程式代碼會產生下列指令清單:
{
"resources": {
"rabbitmq1": {
"type": "container.v0",
"connectionString": "amqp://guest:{rabbitmq1.inputs.password}@{rabbitmq1.bindings.tcp.host}:{rabbitmq1.bindings.tcp.port}",
"image": "rabbitmq:3",
"env": {
"RABBITMQ_DEFAULT_USER": "guest",
"RABBITMQ_DEFAULT_PASS": "{rabbitmq1.inputs.password}"
},
"bindings": {
"tcp": {
"scheme": "tcp",
"protocol": "tcp",
"transport": "tcp",
"containerPort": 5672
}
},
"inputs": {
"password": {
"type": "string",
"secret": true,
"default": {
"generate": {
"minLength": 10
}
}
}
}
}
}
}
Redis 資源類型
範例程式代碼:
var builder = DistributedApplication.CreateBuilder(args);
builder.AddRedis("redis1");
範例指令清單:
{
"resources": {
"redis1": {
"type": "container.v0",
"connectionString": "{redis1.bindings.tcp.host}:{redis1.bindings.tcp.port}",
"image": "redis:7.2.4",
"bindings": {
"tcp": {
"scheme": "tcp",
"protocol": "tcp",
"transport": "tcp",
"containerPort": 6379
}
}
}
}
}
SQL Server 資源類型
範例程式代碼:
var builder = DistributedApplication.CreateBuilder(args);
builder.AddSqlServer("sql1")
.AddDatabase("shipping");
範例指令清單:
{
"resources": {
"sql1": {
"type": "container.v0",
"connectionString": "Server={sql1.bindings.tcp.host},{sql1.bindings.tcp.port};User ID=sa;Password={sql1.inputs.password};TrustServerCertificate=true",
"image": "mcr.microsoft.com/mssql/server:2022-latest",
"env": {
"ACCEPT_EULA": "Y",
"MSSQL_SA_PASSWORD": "{sql1.inputs.password}"
},
"bindings": {
"tcp": {
"scheme": "tcp",
"protocol": "tcp",
"transport": "tcp",
"containerPort": 1433
}
},
"inputs": {
"password": {
"type": "string",
"secret": true,
"default": {
"generate": {
"minLength": 10
}
}
}
}
},
"shipping": {
"type": "value.v0",
"connectionString": "{sql1.connectionString};Database=shipping"
}
}
}
MongoDB 資源類型
範例程式代碼:
var builder = DistributedApplication.CreateBuilder(args);
builder.AddMongoDB("mongodb1")
.AddDatabase("shipping");
範例指令清單:
{
"resources": {
"mongodb1": {
"type": "container.v0",
"connectionString": "mongodb://{mongodb1.bindings.tcp.host}:{mongodb1.bindings.tcp.port}",
"image": "mongo:7.0.5",
"bindings": {
"tcp": {
"scheme": "tcp",
"protocol": "tcp",
"transport": "tcp",
"containerPort": 27017
}
}
},
"shipping": {
"type": "value.v0",
"connectionString": "{mongodb1.connectionString}/shipping"
}
}
}
MySQL 資源類型
範例程式代碼:
var builder = DistributedApplication.CreateBuilder(args);
builder.AddMySql("mysql1")
.AddDatabase("shipping");
範例指令清單:
{
"resources": {
"mysql1": {
"type": "container.v0",
"connectionString": "Server={mysql1.bindings.tcp.host};Port={mysql1.bindings.tcp.port};User ID=root;Password={mysql1.inputs.password}",
"image": "mysql:8.3.0",
"env": {
"MYSQL_ROOT_PASSWORD": "{mysql1.inputs.password}"
},
"bindings": {
"tcp": {
"scheme": "tcp",
"protocol": "tcp",
"transport": "tcp",
"containerPort": 3306
}
},
"inputs": {
"password": {
"type": "string",
"secret": true,
"default": {
"generate": {
"minLength": 10
}
}
}
}
},
"shipping": {
"type": "value.v0",
"connectionString": "{mysql1.connectionString};Database=shipping"
}
}
}
Azure特定資源類型
📦 Aspire中提供下列資源。好客。Azure NuGet 套件。
應用程式模型使用方式 | 指令清單資源類型 | 標題連結 |
---|---|---|
AddAzureAppConfiguration | azure.bicep.v0 |
Azure 應用程式設定資源類型 |
AddAzureKeyVault | azure.bicep.v0 |
Azure Key Vault 資源類型 |
AddAzureRedis |
azure.bicep.v0 |
Azure Redis 資源類型 |
AddAzureServiceBus | azure.bicep.v0 |
Azure Service Bus 資源類型 |
AddAzureSqlServer(...) |
azure.bicep.v0 |
Azure SQL 資源類型 |
AddAzureSqlServer(...).AddDatabase(...) |
value.v0 |
Azure SQL 資源類型 |
AddAzurePostgresFlexibleServer(...) |
azure.bicep.v0 |
Azure Postgres 資源類型 |
AddAzurePostgresFlexibleServer(...).AddDatabase(...) |
value.v0 |
Azure Postgres 資源類型 |
AddAzureStorage | azure.storage.v0 |
Azure 記憶體資源類型 |
AddBlobs | value.v0 |
Azure 記憶體資源類型 |
AddQueues | value.v0 |
Azure 記憶體資源類型 |
AddTables | value.v0 |
Azure 記憶體資源類型 |
Azure Key Vault 資源類型
範例程式代碼:
var builder = DistributedApplication.CreateBuilder(args);
builder.AddAzureKeyVault("keyvault1");
範例指令清單:
{
"resources": {
"keyvault1": {
"type": "azure.bicep.v0",
"connectionString": "{keyvault1.outputs.vaultUri}",
"path": "aspire.hosting.azure.bicep.keyvault.bicep",
"params": {
"principalId": "",
"principalType": "",
"vaultName": "keyvault1"
}
}
}
}
Azure Service Bus 資源類型
範例程式代碼:
var builder = DistributedApplication.CreateBuilder(args);
builder.AddAzureServiceBus("sb1")
.AddTopic("topic1", [])
.AddTopic("topic2", [])
.AddQueue("queue1")
.AddQueue("queue2");
範例指令清單:
{
"resources": {
"sb1": {
"type": "azure.bicep.v0",
"connectionString": "{sb1.outputs.serviceBusEndpoint}",
"path": "aspire.hosting.azure.bicep.servicebus.bicep",
"params": {
"serviceBusNamespaceName": "sb1",
"principalId": "",
"principalType": "",
"queues": [
"queue1",
"queue2"
],
"topics": [
{
"name": "topic1",
"subscriptions": []
},
{
"name": "topic2",
"subscriptions": []
}
]
}
}
}
}
Azure 記憶體資源類型
範例程式代碼:
var builder = DistributedApplication.CreateBuilder(args);
var storage = builder.AddAzureStorage("images");
storage.AddBlobs("blobs");
storage.AddQueues("queues");
storage.AddTables("tables");
範例指令清單:
{
"resources": {
"images": {
"type": "azure.bicep.v0",
"path": "aspire.hosting.azure.bicep.storage.bicep",
"params": {
"principalId": "",
"principalType": "",
"storageName": "images"
}
},
"blobs": {
"type": "value.v0",
"connectionString": "{images.outputs.blobEndpoint}"
},
"queues": {
"type": "value.v0",
"connectionString": "{images.outputs.queueEndpoint}"
},
"tables": {
"type": "value.v0",
"connectionString": "{images.outputs.tableEndpoint}"
}
}
}
Azure Redis 資源類型
範例程式代碼:
var builder = DistributedApplication.CreateBuilder(args);
builder.AddAzureRedis("azredis1");
範例指令清單:
{
"resources": {
"azredis": {
"type": "azure.bicep.v0",
"connectionString": "{azredis.outputs.connectionString}",
"path": "azredis.module.bicep",
"params": {
"principalId": "",
"principalName": ""
}
}
}
}
Azure 應用程式設定資源類型
範例程式代碼:
var builder = DistributedApplication.CreateBuilder(args);
builder.AddAzureAppConfiguration("appconfig1");
範例指令清單:
{
"resources": {
"appconfig1": {
"type": "azure.bicep.v0",
"connectionString": "{appconfig1.outputs.appConfigEndpoint}",
"path": "aspire.hosting.azure.bicep.appconfig.bicep",
"params": {
"configName": "appconfig1",
"principalId": "",
"principalType": ""
}
}
}
}
Azure SQL 資源類型
範例程式代碼:
var builder = DistributedApplication.CreateBuilder(args);
builder.AddAzureSqlServer("sql")
.AddDatabase("inventory");
範例指令清單:
{
"resources": {
"sql": {
"type": "azure.bicep.v0",
"connectionString": "Server=tcp:{sql.outputs.sqlServerFqdn},1433;Encrypt=True;Authentication=\u0022Active Directory Default\u0022",
"path": "sql.module.bicep",
"params": {
"principalId": "",
"principalName": ""
}
},
"inventory": {
"type": "value.v0",
"connectionString": "{sql.connectionString};Database=inventory"
}
}
}
Azure Postgres 資源類型
範例程式代碼:
var builder = DistributedApplication.CreateBuilder(args);
builder.AddAzurePostgresFlexibleServer("postgres")
.AddDatabase("db");
範例指令清單:
{
"resources": {
"postgres": {
"type": "azure.bicep.v0",
"connectionString": "{postgres.outputs.connectionString}",
"path": "postgres.module.bicep",
"params": {
"principalId": "",
"principalType": "",
"principalName": ""
}
},
"db": {
"type": "value.v0",
"connectionString": "{postgres.connectionString};Database=db"
}
}
}
Azure Developer CLI 中支援的資源類型
Azure Developer CLI (azd) 是一種工具,可用來將 .NET Aspire 專案部署至 Azure Container Apps。 使用 azure.bicep.v0
資源類型時,雲端無關的資源容器類型可以對應至 Azure特定資源。 下表列出 Azure Developer CLI中支援的資源類型:
名字 | 無從驗證的 API | Azure API |
---|---|---|
Redis | AddRedis | AddAzureRedis |
Postgres | AddPostgres | AddAzurePostgresFlexibleServer |
SQL Server | AddSqlServer | AddAzureSqlServer |
當資源設定為 Azure 資源時,就會在指令清單中產生 azure.bicep.v0
資源類型。 如需詳細資訊,請參閱 使用 .NET Aspire.NET Aspire 部署 Azure Developer CLI 專案以 。