共用方式為


部署工具產生器的 .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 檔案中使用呼叫 webfrontendWithReference(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 指令清單的結構:

顯示指令清單 JSON 結構如何對應至佔位元字串的圖表。

處理指令清單的工具會產生佔位元字串的最後一個區段(在此案例中為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.v0container.v0executable.v0 資源類型也會共用 envbindings 欄位。

注意

executable.v0 資源類型並未在指令清單中完全實作,因為它在部署案例中缺少公用程式。 如需容器化可執行檔的詳細資訊,請參閱 Dockerfile 資源類型

env 欄位型態是基本索引鍵/值對應,其中值可能包含 佔位元符字串

系結是在 bindings 欄位中指定,每個系結都包含在 bindingsJSON 物件下自己的欄位內。 .NET 節點中 .NET Aspirebindings 指令清單省略的欄位包括:

  • scheme:下列其中一個值 tcpudphttphttps
  • protocol:下列其中一個值 tcpudp
  • transport:與 scheme相同,但用來釐清 httphttp2之間。
  • 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 專案以

另請參閱