Aspire översikt över publicering och distribution

Aspire separerar skapandet av distributionstillgångar från utförandet av en distribution. Aspire CLI (aspire) innehåller två startpunkter på hög nivå:

• aspire publish: Genererar mellanliggande, parametriserade tillgångar för en eller flera värdintegreringar som implementerar publiceringssemantik.
• aspire deploy: Kör en distribution (när en integrering implementerar distributionssemantik) genom att matcha parametrar och tillämpa ändringar i en målmiljö.

Dessa kommandon ger direkt åtkomst till publicerings- och distributionsfunktioner. Det faktiska beteendet (vad som genereras, hur distributionen sker) kommer från de hostningsintegrationer som du refererar till (till exempel: Docker, Kubernetes, Azure). Systemet är utökningsbart – du kan skapa egna publicerings- eller distributionsintegreringar som ansluts till samma modell.

Kommandot aspire publish genererar distributionsartefakter som innehåller olösta parametrar (platshållare). Kommandot aspire deploy använder dessa artefakter, löser parametrarna när de stöds av målintegreringen och kör sedan distributionen. Vissa integreringar stöder deploy inte kommandot.

Aspire CLI-kommandon (konceptuellt beteende)

Om en integrering inte implementerar distributionsfunktionalitet aspire deploy distribueras inte den målenheten (det kan varna eller köra en no-op för det).

När du kör aspire publish utan integreringar som stöder publicering ser du:

Step 1: Analyzing model.

       ✗ FAILED: Analyzing the distributed application model for publishing and deployment capabilities. 00:00:00
           No resources in the distributed application model support publishing.

❌ FAILED: Analyzing model. completed with errors

På samma sätt visas följande fel när du kör aspire deploy utan integreringar som stöder distribution:

Step 1: Analyzing model.

       ✗ FAILED: Analyzing the distributed application model for publishing and deployment capabilities. 00:00:00
           No resources in the distributed application model support deployment.

❌ FAILED: Analyzing model. completed with errors

De här meddelandena anger att du behöver lägga till värdintegreringar i ditt AppHost-projekt. Värdintegreringar är NuGet-paket (till exempel Aspire.Hosting.Docker, Aspire.Hosting.Kubernetes eller Aspire.Hosting.Azure) som tillhandahåller publicerings- och distributionsmöjligheter för specifika målplattformar.

Platshållare för parametrar

Publicerade tillgångar innehåller avsiktligt platshållare i stället för konkreta värden. För Docker Compose-baserade publiceringsutdata visas parameterisering som standardhänvisningar till miljövariabler. En publiceringsartefakt kan till exempel innehålla:

services:
  pg:
    image: "docker.io/library/postgres:17.6"
    environment:
      POSTGRES_HOST_AUTH_METHOD: "scram-sha-256"
      POSTGRES_INITDB_ARGS: "--auth-host=scram-sha-256 --auth-local=scram-sha-256"
      POSTGRES_USER: "postgres"
      POSTGRES_PASSWORD: "${PG_PASSWORD}"
    ports:
      - "8000:5432"
    networks:
      - "aspire"
  dbsetup:
    image: "${DBSETUP_IMAGE}"
    environment:
      OTEL_DOTNET_EXPERIMENTAL_OTLP_EMIT_EXCEPTION_LOG_ATTRIBUTES: "true"
      OTEL_DOTNET_EXPERIMENTAL_OTLP_EMIT_EVENT_LOG_ATTRIBUTES: "true"
      OTEL_DOTNET_EXPERIMENTAL_OTLP_RETRY: "in_memory"
      ASPNETCORE_FORWARDEDHEADERS_ENABLED: "true"
      HTTP_PORTS: "8001"
      ConnectionStrings__db: "Host=pg;Port=5432;Username=postgres;Password=${PG_PASSWORD};Database=db"
    ports:
      - "8002:8001"
      - "8004:8003"
    depends_on:
      pg:
        condition: "service_started"
    networks:
      - "aspire"

Viktiga punkter:

• ${PG_PASSWORD} och ${DBSETUP_IMAGE} (och liknande) är platshållare i den publicerade resursen.
• De löses inte under aspire publish.
• En distributionsmotor (som kan vara aspire deploy, docker compose plus ett skript som exporterar variabler, CI/CD-variabelinmatning osv.) tillhandahåller sina värden senare.
• Detta håller hemligheter och miljöspecifika värden frikopplade från den genererade strukturen.

Olika integreringar kan använda olika platshållarkonventioner (miljövariabler, token eller parametermetadata), men principen kvarstår: publicera bevarar form, distribuerar inmatade värden.

Utgivarmodell- och beräkningsmiljöer

Aspire använder en flexibel utgivarmodell som distribuerar publiceringsbeteendet i programdiagrammet. Resurser stöder publicering och distribution via anteckningar:

• aspire publish
• aspire deploy

Den här designen möjliggör hybriddistributioner och heterogena distributioner, där olika tjänster i samma app kan distribueras till olika mål (moln, gräns, lokal).

Beräkningsmiljöer

En beräkningsmiljö är ett grundläggande distributionskoncept i Aspire som representerar en målplattform där dina programresurser kommer att distribueras. Beräkningsmiljöer definierar hur resurser ska transformeras och vilka distributionsartefakter som ska genereras. Exempel på inbyggda beräkningsmiljöer är Azure Container Apps miljön och Docker Compose-miljön.

Beräkningsresurser är de körbara delarna i ditt program, till exempel .NET projekt, containrar och körbara filer som måste distribueras till en beräkningsmiljö.

När du lägger till en beräkningsmiljö som Docker Compose eller Kubernetes, Aspire tillämpas rätt publiceringsbeteende på alla kompatibla beräkningsresurser i din appmodell – ingen extra konfiguration krävs.

Flera miljöer kräver tvetydighet

Om du lägger till flera beräkningsmiljöer Aspire måste du veta vilken resurs som går dit. Beräkningsmiljöer tillämpar sina transformeringar på alla tillämpliga beräkningsresurser (projekt, containrar, körbara filer). Om fler än en miljö matchar en viss resurs utlöser Aspire en tvetydig miljöundantag vid publicering.

Du kan lösa detta med hjälp av WithComputeEnvironment.

var k8s = builder.AddKubernetesEnvironment("k8s-env");
var compose = builder.AddDockerComposeEnvironment("docker-env");

builder.AddProject<Projects.Frontend>("frontend")
    .WithComputeEnvironment(k8s);

builder.AddProject<Projects.Backend>("backend")
    .WithComputeEnvironment(compose);

Det här exemplet visar hur du uttryckligen kan mappa tjänster till olika beräkningsmiljöer. Till exempel en frontend i Kubernetes och en backend i Docker Compose.

Värdtjänst för integrationsmatris

Vanliga arbetsflöden

1. Generera artefakter (vilken som helst integrering)

aspire publish -o artifacts/

Granska innehållet i artefakter/ (till exempel: Docker Skriv filer, manifest, KubernetesAzure specifikationsdokument osv.).

2. Kör lokalt (Docker exempel)

# Provide or export required environment variables, then:
docker compose -f artifacts/docker-compose.yml up --build

Saknade variabler som PG_PASSWORD måste anges i shellen, en .env fil, eller matas in av din valda runner.

3. Använda aspire deploy

Om en integrering stöder distribution kan du köra:

aspire deploy

Detta löser parametrar och tillämpar distributionsändringar för integreringar som stöder distribution.

Extensibility

Kommandona aspire publish och aspire deploy stöder utökningsbara arbetsflöden via anteckningar som du kan lägga till i resurser. Den här funktionen är i förhandsversion och kan ändras i framtida versioner.

Callbacksfunktioner för specialanpassad publicering och distribution

Resurser stöder anpassade publicerings- och distributionsbeteenden via anteckningar:

• PublishingCallbackAnnotation: Kör anpassad logik under aspire publish åtgärder.
• DeployingCallbackAnnotation: Kör anpassad logik under aspire deploy åtgärder.

I följande exempel visas hur du använder DeployingCallbackAnnotation för att registrera beteende för anpassad distribution:

#pragma warning disable ASPIREPUBLISHERS001
#pragma warning disable ASPIREINTERACTION001

using Aspire.Hosting.Publishing;
using Microsoft.Extensions.DependencyInjection;

var builder = DistributedApplication.CreateBuilder(args);

// Custom deployment step defined below
builder.AddDataSeedJob("SeedInitialData", seedDataPath: "data/seeds");

builder.Build().Run();

internal class DataSeedJobResource([ResourceName] string name, string seedDataPath)
    : Resource(name)
{
    public string SeedDataPath { get; } = seedDataPath;
}

internal static class DataSeedJobResourceBuilderExtensions
{
    public static IResourceBuilder<DataSeedJobResource> AddDataSeedJob(
        this IDistributedApplicationBuilder builder,
        string name,
        string seedDataPath = "data/seeds")
    {
        var job = new DataSeedJobResource(name, seedDataPath);
        var resourceBuilder = builder.AddResource(job);

        // Attach a DeployingCallbackAnnotation that will be invoked on `aspire deploy`
        job.Annotations.Add(new DeployingCallbackAnnotation(async ctx =>
        {
            CancellationToken ct = ctx.CancellationToken;

            // Prompt the user for a confirmation using the interaction service
            var interactionService = ctx.Services.GetRequiredService<IInteractionService>();

            var envResult = await interactionService.PromptInputAsync(
                "Environment Configuration",
                "Please enter the target environment name:",
                new InteractionInput
                {
                    Label = "Environment Name",
                    InputType = InputType.Text,
                    Required = true,
                    Placeholder = "dev, staging, prod"
                },
                cancellationToken: ct);

            // Custom deployment logic here
            var reporter = ctx.ActivityReporter;
            await using (var deployStep = await reporter.CreateStepAsync(
                $"Deploying data seed job to {envResult.Value}", ct))
            {
                // Simulate deployment work
                await Task.Delay(2000, ct);
                await deployStep.SucceedAsync("Data seed job deployed successfully", ct);
            }
        }));

        return resourceBuilder;
    }
}

Den här anpassade distributionslogiken integreras sömlöst med aspire deploy kommandot och tillhandahåller interaktiva frågor och förloppsrapportering. Mer information finns i Resursanteckningar i Aspire.

Diagnostik och granskning

Publicering ger dig en oföränderlig ögonblicksbild av den avsedda strukturen innan hemligheter visas. Du kan:

• Diff publicerade utdata mellan incheckningar.
• Sök efter otillåtna avbildningar eller konfiguration.
• Bevara ett protokoll för efterlevnad och registrera sedan den angivna uppsättningen separat som tillämpades vid driftsättningstillfället.

Ytterligare verktyg

Azure Developer CLI (azd)

Azure Developer CLI (azd) har förstklassigt stöd för att Aspire distribuera projekt. Den kan etablera infrastruktur, hantera miljöer och samordna hemlighets-/värdeinmatning. Du kan införliva Aspire publiceringsartefakter i azd arbetsflöden eller använda integreringen Azure (förhandsversionen) direkt.

Driftsättningsmanifest

Från och med Aspire 9.2 fasas manifestformatet långsamt ut till förmån för CLI-publicering och distribution av Aspire kommandostöd och API:er för att definiera publicerings- och distributionsfunktioner. Tidigare arbetsflöden betonade ett enda "distributionsmanifest" som genererades från specialiserade AppHost-mål. Den moderna metoden fokuserar på aspire publish + utökningsbarhet för integrering. Det äldre manifestformatet utvecklas inte ytterligare, men du kan fortfarande generera det för inspektion eller felsökning:

aspire publish --publisher manifest -o diagnostics/

Denna:

• Skapar en ögonblicksbild av manifestet som är användbar för att förstå resursdiagram eller felsökning.
• Bör inte behandlas som det primära distributionskontraktet.
• Tillhandahålls enbart för bakåtkompatibilitet och felsökningssynlighet.

Viktiga lärdomar

Publiceringen kommer först, följt av distributionen, som separerar strukturen från värdena. Artefakterna som skapas under publiceringen parametriseras, med upplösning som inträffar senare i processen. Specifika integreringar bestämmer de faktiska beteendena för publicering och distribution, och systemet är utformat för att vara utökningsbart, så att du kan skapa anpassade integreringar som riktar sig mot nya plattformar eller interna verktyg. Även om det äldre manifestet fortfarande kan genereras förblir det statiskt och utvecklas inte längre.

Se även

• Översikt över värdintegreringar
• Azure distribution med Container Apps
• Aspire CLI-referens