Aspire manifestformat för distributionsverktygsbyggare

I den här artikeln får du lära dig mer om Aspire manifestformatet. Den här artikeln fungerar som en referensguide för distributionsverktygsbyggare som hjälper dig att skapa verktyg för att distribuera Aspire projekt på specifika värdplattformar, både lokalt eller i molnet.

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 Aspire projekt generera ett manifest över alla resurser som definierats som en JSON formaterad fil.

Generera ett manifest

Ett giltigt Aspire projekt krävs för att generera ett manifest. Kom igång genom att skapa ett 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

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 manifestet Aspire och används av verktyg som stöd för distribution till målmolnmiljöer.

{
  "$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 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}"
},

Resursen apiservice refereras med hjälp av anropet webfrontend i AppHost-filen WithReference(apiservice) och AppHost.cs refereras med hjälp av redis 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 Aspire finns i orkestreringsöversikt.

Platshållarsträngsstruktur

Platshållarsträngar refererar till manifestets Aspire struktur:

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 Aspire kompatibel anslutningssträng för det förbrukande programmet som ska användas. På container.v0 resurser kan fältet connectionString 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 skapar url 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. Aspire Under förhandsgranskningsperioden har alla resurstyper ett v0 suffix som anger att de kan komma att ändras. När Aspire metoden släpper används ett v1 suffix för att ange att manifestets struktur för den resurstypen ska betraktas som stabil (efterföljande uppdateringar ökar versionsnumret därefter).

Vanliga resursfält

Fältet type är det enda fält som är gemensamt för alla resurstyper, men project.v0, container.v0och executable.v0 resurstyper delar också fälten env och bindings.

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 bindingsJSON objektet. Fälten som utelämnas av manifestet Aspirebindings i noden är:

• scheme: Ett av följande värden tcp, udp, httpeller https.
• protocol: Ett av följande värden tcp eller udp
• transport: Samma som scheme, men används för att skilja mellan http och http2.
• 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 connectionStringkan 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 Aspire och tillägg som utvecklats av Aspire-teamet:

Molnagnostiska resurstyper

Dessa resurser är tillgängliga i 📦Aspire. Värd för NuGet-paket.

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

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.

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 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:

När resurser som har konfigurerats som Azure resurser genereras azure.bicep.v0 resurstyp i manifestet. Mer information finns i Distribuera ett Aspire projekt till Azure Container Apps med hjälp av Azure Developer CLI (djupgående guide).

Se även

• Aspire överblick
• Aspire översikt över orkestrering
• Aspire översikt över integreringar
• Tjänstidentifiering i Aspire