формат манифеста .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. веб-интерфейс
Эта зависимость известна, так как переменные среды для веб-интерфейсной содержат заполнители, ссылающиеся на два других ресурса:
"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 Aspire в узле bindings
, включают:
-
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 |
Dockerfile типов ресурсов |
AddDatabase | value.v0 |
типов ресурсов |
AddMongoDB | container.v0 |
MongoDB типов ресурсов |
AddDatabase | value.v0 |
MySQL Server типов ресурсов |
AddMySql | container.v0 |
MySQL типов ресурсов |
AddDatabase | value.v0 |
Postgres типов ресурсов |
AddPostgres | container.v0 |
Postgres типов ресурсов |
AddProject | project.v0 |
типа ресурса project |
AddRabbitMQ | container.v0 |
RabbitMQ типов ресурсов |
AddRedis | container.v0 |
типа ресурса |
AddDatabase | value.v0 |
SQL Server типов ресурсов |
AddSqlServer | container.v0 |
SQL Server типов ресурсов |
Тип ресурса Project
Пример кода:
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 |
типа ресурса |
AddAzureRedis |
azure.bicep.v0 |
типов ресурсов |
AddAzureServiceBus | azure.bicep.v0 |
типа ресурса |
AddAzureSqlServer(...) |
azure.bicep.v0 |
Azure типы ресурсов SQL |
AddAzureSqlServer(...).AddDatabase(...) |
value.v0 |
Azure типы ресурсов SQL |
AddAzurePostgresFlexibleServer(...) |
azure.bicep.v0 |
типов ресурсов |
AddAzurePostgresFlexibleServer(...).AddDatabase(...) |
value.v0 |
типов ресурсов |
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}"
}
}
}
тип ресурса AzureRedis
Пример кода:
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"
}
}
}
Типы ресурсов AzurePostgres
Пример кода:
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, не зависящий от облака | API Azure |
---|---|---|
Redis | AddRedis | AddAzureRedis |
Postgres | AddPostgres | AddAzurePostgresFlexibleServer |
SQL Server | AddSqlServer | AddAzureSqlServer |
Если ресурсы настроены как Azure ресурсы, в манифесте создается тип ресурса azure.bicep.v0
. Дополнительные сведения см. в статье Развертывание проекта .NET Aspire для Azure Container Apps с помощью Azure Developer CLI (подробного руководства).
См. также
- Обзор
- Общие сведения о оркестрации .NET.NET Aspire
- Обзор интеграции
- Обнаружение служб в .NET.NET Aspire
.NET Aspire