.NET .NET Aspire manifestformat för distributionsverktygsbyggare
I den här artikeln får du lära dig mer om .NET.NET Aspire manifestformat. Den här artikeln fungerar som en referensguide för distributionsverktygsbyggare som hjälper dig att skapa verktyg för att distribuera .NET.NET Aspire projekt på specifika värdplattformar, både lokalt eller i molnet.
.NET .NET Aspire förenklar den lokala utvecklingsupplevelsen genom att hjälpa till att hantera beroenden mellan programintegreringar. För att förenkla distributionen av program kan .NET Aspire projekt generera ett manifest över alla resurser som definierats som en JSON formaterad fil.
Generera ett manifest
Ett giltigt .NET.NET Aspire projekt krävs för att generera ett manifest. Kom igång genom att skapa ett .NET.NET Aspire projekt med hjälp av mallen aspire-starter
.NET:
dotnet new aspire-starter --use-redis-cache `
-o AspireApp && `
cd AspireApp
Manifestgenerering uppnås genom att köra dotnet build
med ett särskilt mål:
dotnet run --project AspireApp.AppHost\AspireApp.AppHost.csproj `
--publisher manifest `
--output-path ../aspire-manifest.json
Dricks
--output-path
stöder relativa sökvägar. Föregående kommando använder ../aspire-manifest.json
för att placera manifestfilen i roten i projektkatalogen.
Mer information finns i dotnet run. Föregående kommando genererar följande utdata:
Building...
info: Aspire.Hosting.Publishing.ManifestPublisher[0]
Published manifest to: .\AspireApp.AppHost\aspire-manifest.json
Filen som genereras är det .NET.NET Aspire manifestet och används av verktyg för att distribuera till målmolnmiljöer.
Not
Du kan också generera ett manifest som en del av startprofilen. Överväg följande 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"
}
}
}
Grundläggande manifestformat
När du publicerar manifestet från standardstartmallen för .NET Aspire genereras följande JSON utdata:
{
"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"
}
}
}
}
}
Manifestformatet JSON består av ett enda objekt som heter resources
, som innehåller en egenskap för varje resurs som anges i Program.cs (argumentet name
för varje namn används som egenskap för vart och ett av de underordnade resursobjekten i JSON).
Anslutningssträng och bindningsreferenser
I föregående exempel finns det två projektresurser och en Redis cacheresurs. webfrontend- beror på både apiservice- (projekt) och cachelagring (Redis) resurser.
Det här beroendet är känt eftersom miljövariablerna för webfrontend innehålla platshållare som refererar till de två andra resurserna:
"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}"
},
Den apiservice
resursen refereras av webfrontend
med hjälp av anropet WithReference(apiservice)
i appvärden Program.cs fil och redis
refereras med hjälp av anropet 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();
Referenser mellan projektresurstyper resulterar i tjänstidentifiering variabler som matas in i referensprojektet. Referenser till välkända referenstyper som Redis resulterar i att anslutningssträngar matas in.
Mer information om hur resurser i appmodellen och referenser mellan dem fungerar finns i .NET.NET Aspire orkestreringsöversikt.
Platshållarsträngsstruktur
Platshållarsträngar refererar till strukturen för .NET.NET Aspire-manifestet:
Det sista segmentet av platshållarsträngen (url
i det här fallet) genereras av verktyget som bearbetar manifestet. Det finns flera suffix som kan användas på platshållarsträngen:
-
connectionString
: För välkända resurstyper som Redis. Distributionsverktyg översätter resursen i den lämpligaste infrastrukturen för målmolnmiljön och skapar sedan en .NET.NET Aspire kompatibel anslutningssträng som det förbrukande programmet ska använda. Påcontainer.v0
resurser kan fältetconnectionString
finnas och anges uttryckligen. Detta är till stöd för scenarier där en containerresurstyp refereras med hjälp av WithReference-tillägget, men som uttryckligen ska vara värd för en container. -
url
: För tjänst-till-tjänst-referenser där en välformulerad URL krävs. Distributionsverktyget skaparurl
baserat på schemat, protokollet och transporten som definierats i manifestet och den underliggande beräknings-/nätverkstopologin som distribuerades. -
host
: Värdsegmentet för URL:en. -
port
: Portsegmentet för URL:en.
Resurstyper
Varje resurs har ett type
fält. När ett distributionsverktyg läser manifestet bör det läsa typen för att kontrollera om manifestet kan bearbetas korrekt. Under den .NET.NET Aspire förhandsversionen har alla resurstyper ett v0
suffix som anger att de kan komma att ändras. När .NET.NET Aspire metoder släpper ett v1
suffix används för att ange att manifestets struktur för den resurstypen ska betraktas som stabil (efterföljande uppdateringar ökar versionsnumret i enlighet med detta).
Vanliga resursfält
Fältet type
är det enda fält som är gemensamt för alla resurstyper, men project.v0
, container.v0
och executable.v0
resurstyper delar också fälten env
och bindings
.
Not
Den executable.v0
resurstypen är inte helt implementerad i manifestet på grund av att den saknar verktyg i distributionsscenarier. Mer information om hur du använder körbara containrar finns i Dockerfile resurstyper.
Fälttypen env
är en grundläggande nyckel/värdemappning där värdena kan innehålla platshållarsträngar.
Bindningar anges i fältet bindings
med varje bindning som finns i det egna fältet under det bindings
JSON objektet. Fälten som utelämnas av .NET.NET Aspire-manifestet i den bindings
noden är:
-
scheme
: Ett av följande värdentcp
,udp
,http
ellerhttps
. -
protocol
: Ett av följande värdentcp
ellerudp
-
transport
: Samma somscheme
, men används för att skilja mellanhttp
ochhttp2
. -
containerPort
: Valfritt om det utelämnas som standard till port 80.
Fältet inputs
Vissa resurser genererar ett inputs
fält. Det här fältet används för att ange indataparametrar för resursen. Fältet inputs
är ett JSON objekt där varje egenskap är en indataparameter som används i platshållarstrukturmatchning. Resurser som har en connectionString
kan till exempel använda fältet inputs
för att ange en password
för anslutningssträngen:
"connectionString": "Host={<resourceName>.bindings.tcp.host};Port={<resourceName>.bindings.tcp.port};Username=admin;Password={<resourceName>.inputs.password};"
Platshållaren för anslutningssträngen refererar till parametern password
indata från fältet inputs
:
"inputs": {
"password": {
"type": "string",
"secret": true,
"default": {
"generate": {
"minLength": 10
}
}
}
}
Föregående JSON-kodfragmentet visar fältet inputs
för en resurs som har ett connectionString
fält. Indataparametern password
är en strängtyp och markeras som en hemlighet. Fältet default
används för att ange ett standardvärde för indataparametern. I det här fallet genereras standardvärdet med hjälp av fältet generate
, med en slumpmässig sträng med en minsta längd.
Inbyggda resurser
Följande tabell är en lista över resurstyper som uttryckligen genereras av .NET Aspire och tillägg som utvecklats av .NET Aspire-teamet:
Molnagnostiska resurstyper
Dessa resurser är tillgängliga i 📦Aspire. Värd för NuGet-paket.
Användning av appmodell | Manifestresurstyp | Rubriklänk |
---|---|---|
AddContainer | container.v0 |
containerresurstyp |
PublishAsDockerFile |
dockerfile.v0 |
Dockerfile resurstyper |
AddDatabase | value.v0 |
MongoDB Server resurstyper |
AddMongoDB | container.v0 |
MongoDB resurstyper |
AddDatabase | value.v0 |
MySQL Server resurstyper |
AddMySql | container.v0 |
MySQL resurstyper |
AddDatabase | value.v0 |
Postgres resurstyper |
AddPostgres | container.v0 |
Postgres resurstyper |
AddProject | project.v0 |
Projektresurstyp |
AddRabbitMQ | container.v0 |
RabbitMQ resurstyper |
AddRedis | container.v0 |
Redis resurstyp |
AddDatabase | value.v0 |
SQL Server resurstyper |
AddSqlServer | container.v0 |
SQL Server resurstyper |
Projektresurstyp
Exempelkod:
var builder = DistributedApplication.CreateBuilder(args);
var apiservice = builder.AddProject<Projects.AspireApp_ApiService>("apiservice");
Exempelmanifest:
"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"
}
}
}
Containerresurstyp
Exempelkod:
var builder = DistributedApplication.CreateBuilder(args);
builder.AddContainer("mycontainer", "myimage")
.WithEnvironment("LOG_LEVEL", "WARN")
.WithHttpEndpoint(3000);
Exempelmanifest:
{
"resources": {
"mycontainer": {
"type": "container.v0",
"image": "myimage:latest",
"env": {
"LOG_LEVEL": "WARN"
},
"bindings": {
"http": {
"scheme": "http",
"protocol": "tcp",
"transport": "http",
"containerPort": 3000
}
}
}
}
}
Dockerfile resurstyper
Exempelkod:
var builder = DistributedApplication.CreateBuilder(args);
builder.AddNodeApp("nodeapp", "../nodeapp/app.js")
.WithHttpEndpoint(hostPort: 5031, env: "PORT")
.PublishAsDockerFile();
Dricks
Anropet PublishAsDockerFile
krävs för att generera resurstypen Dockerfile i manifestet, och den här tilläggsmetoden är endast tillgänglig för ExecutableResource typ.
Exempelmanifest:
{
"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 resurstyper
Exempelkod:
var builder = DistributedApplication.CreateBuilder(args);
builder.AddPostgres("postgres1")
.AddDatabase("shipping");
Exempelmanifest:
{
"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 resurstyper
RabbitMQ modelleras som en containerresurs container.v0
. Följande exempel visar hur de läggs till i appmodellen.
var builder = DistributedApplication.CreateBuilder(args);
builder.AddRabbitMQ("rabbitmq1");
Föregående kod genererar följande manifest:
{
"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 resurstyp
Exempelkod:
var builder = DistributedApplication.CreateBuilder(args);
builder.AddRedis("redis1");
Exempelmanifest:
{
"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 resurstyper
Exempelkod:
var builder = DistributedApplication.CreateBuilder(args);
builder.AddSqlServer("sql1")
.AddDatabase("shipping");
Exempelmanifest:
{
"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 resurstyper
Exempelkod:
var builder = DistributedApplication.CreateBuilder(args);
builder.AddMongoDB("mongodb1")
.AddDatabase("shipping");
Exempelmanifest:
{
"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 resurstyper
Exempelkod:
var builder = DistributedApplication.CreateBuilder(args);
builder.AddMySql("mysql1")
.AddDatabase("shipping");
Exempelmanifest:
{
"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-specifika resurstyper
Följande resurser är tillgängliga i 📦Aspire. Gästfrihet.Azure NuGet-paket.
Användning av appmodell | Manifestresurstyp | Rubriklänk |
---|---|---|
AddAzureAppConfiguration | azure.bicep.v0 |
resurstyper för Azure appkonfiguration |
AddAzureKeyVault | azure.bicep.v0 |
Azure Key Vault resurstyp |
AddAzureRedis |
azure.bicep.v0 |
Azure Redis resurstyper |
AddAzureServiceBus | azure.bicep.v0 |
Azure Service Bus resurstyp |
AddAzureSqlServer(...) |
azure.bicep.v0 |
Azure SQL-resurstyper |
AddAzureSqlServer(...).AddDatabase(...) |
value.v0 |
Azure SQL-resurstyper |
AddAzurePostgresFlexibleServer(...) |
azure.bicep.v0 |
Azure Postgres resurstyper |
AddAzurePostgresFlexibleServer(...).AddDatabase(...) |
value.v0 |
Azure Postgres resurstyper |
AddAzureStorage | azure.storage.v0 |
Azure Lagringsresurstyper |
AddBlobs | value.v0 |
Azure Lagringsresurstyper |
AddQueues | value.v0 |
Azure Lagringsresurstyper |
AddTables | value.v0 |
Azure Lagringsresurstyper |
Azure Key Vault resurstyp
Exempelkod:
var builder = DistributedApplication.CreateBuilder(args);
builder.AddAzureKeyVault("keyvault1");
Exempelmanifest:
{
"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 resurstyp
Exempelkod:
var builder = DistributedApplication.CreateBuilder(args);
builder.AddAzureServiceBus("sb1")
.AddTopic("topic1", [])
.AddTopic("topic2", [])
.AddQueue("queue1")
.AddQueue("queue2");
Exempelmanifest:
{
"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 Resurstyper för lagring
Exempelkod:
var builder = DistributedApplication.CreateBuilder(args);
var storage = builder.AddAzureStorage("images");
storage.AddBlobs("blobs");
storage.AddQueues("queues");
storage.AddTables("tables");
Exempelmanifest:
{
"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 resurstyp
Exempelkod:
var builder = DistributedApplication.CreateBuilder(args);
builder.AddAzureRedis("azredis1");
Exempelmanifest:
{
"resources": {
"azredis": {
"type": "azure.bicep.v0",
"connectionString": "{azredis.outputs.connectionString}",
"path": "azredis.module.bicep",
"params": {
"principalId": "",
"principalName": ""
}
}
}
}
resurstyp för Azure appkonfiguration
Exempelkod:
var builder = DistributedApplication.CreateBuilder(args);
builder.AddAzureAppConfiguration("appconfig1");
Exempelmanifest:
{
"resources": {
"appconfig1": {
"type": "azure.bicep.v0",
"connectionString": "{appconfig1.outputs.appConfigEndpoint}",
"path": "aspire.hosting.azure.bicep.appconfig.bicep",
"params": {
"configName": "appconfig1",
"principalId": "",
"principalType": ""
}
}
}
}
Azure SQL-resurstyper
Exempelkod:
var builder = DistributedApplication.CreateBuilder(args);
builder.AddAzureSqlServer("sql")
.AddDatabase("inventory");
Exempelmanifest:
{
"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 resurstyper
Exempelkod:
var builder = DistributedApplication.CreateBuilder(args);
builder.AddAzurePostgresFlexibleServer("postgres")
.AddDatabase("db");
Exempelmanifest:
{
"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"
}
}
}
Resurstyper som stöds i Azure Developer CLI
Azure Developer CLI (azd) är ett verktyg som kan användas för att distribuera .NET Aspire projekt till Azure Container Apps. Med azure.bicep.v0
resurstyp kan molnagnostiska resurscontainertyper mappas till Azure-specifika resurser. I följande tabell visas de resurstyper som stöds i Azure Developer CLI:
Namn | Molnagnostisk API | Azure API |
---|---|---|
Redis | AddRedis | AddAzureRedis |
Postgres | AddPostgres | AddAzurePostgresFlexibleServer |
SQL Server | AddSqlServer | AddAzureSqlServer |
När resurser som har konfigurerats som Azure resurser genereras azure.bicep.v0
resurstyp i manifestet. Mer information finns i Deploy a .NET Aspire project to Azure Container Apps using the Azure Developer CLI (in-depth guide).
Se även
- .NET .NET Aspire översikt
- översikt över .NET.NET Aspire orkestrering
- översikt över .NET.NET Aspire integreringar
- Tjänstidentifiering i .NET.NET Aspire
.NET Aspire