Skapa anpassade distributionspipelines (förhandsversion)

Aspire innehåller kraftfulla API:er för att skapa containeravbildningar från dina resurser under publicerings- och distributionsåtgärder. Den här artikeln beskriver viktiga komponenter som möjliggör programmatisk skapande av containeravbildningar och förloppsrapportering.

Översikt

Under publicering och distribution är containeravbildningsverktyget tillgängligt för att skapa avbildningar för resurser som behöver dem. Aspire använder den här byggaren när en resurs kräver en containeravbildning, till exempel vid publicering med Docker Compose. Processen omfattar två huvudkomponenter:

• IResourceContainerImageBuilder: Tjänsten som omvandlar resursdefinitioner till körbara containeravbildningar.
• IPublishingActivityReporter: API:et som tillhandahåller strukturerad förloppsrapportering under långvariga åtgärder.

Dessa API:er ger dig detaljerad kontroll över bildskapandeprocessen och ger feedback i realtid till användare under långa byggåtgärder.

När du ska använda dessa API:er

Överväg att använda API:erna för containeravbildningsuppbyggnad och förloppsrapportering i följande scenarier:

• Anpassade distributionsmål: När du behöver distribuera till plattformar som kräver specifika avbildningsformat eller byggkonfigurationer.
• Komplexa byggprocesser: När publiceringsprocessen omfattar flera steg som användarna bör se.
• Företagsscenarier: När du behöver anpassad förloppsrapportering för integrering med CI/CD-system eller instrumentpaneler.
• Anpassade resurstyper: När du implementerar anpassade resurser som behöver delta i publicerings- och distributionsprocessen.

API för resurscontaineravbildningsverktyget

IResourceContainerImageBuilder är kärntjänsten i lagret Aspire.Hosting.Publishing som konverterar resursdefinitioner till containeravbildningar. Den analyserar varje resurs i din distribuerade programmodell och avgör om du vill:

• Återanvänd en befintlig avbildning.
• Skapa från ett .NET-projekt med dotnet publish /t:PublishContainer.
• Skapa från en Dockerfile med den lokala containermiljön.

Alternativ för containerbygge

Klassen ContainerBuildOptions tillhandahåller starkt typad konfiguration för containerbyggen. Med den här klassen kan du ange:

• Bildformat: Docker eller OCI-format (Open Container Initiative).
• Målplattform: Linux x64, Windows, ARM64 osv.
• Utdatasökväg: Var du kan spara de skapade avbildningarna.

Hälsokontroller för containerkörning

Byggaren utför endast hälsokontroller för containerkörning (Docker/Podman) när minst en resurs kräver en Dockerfile version. Den här ändringen eliminerar falska positiva fel i projekt som publicerar direkt från .NET sammansättningar. Om containerplattformen krävs men inte är felfri kastar byggaren ett explicit InvalidOperationException för att identifiera problemet tidigt.

Publicera aktivitetsreporter-API

API:et PublishingActivityProgressReporter möjliggör strukturerad förloppsrapportering under aspire publish kommandona och aspire deploy . Detta minskar osäkerheten vid långvariga drifts- och ytfel tidigt.

API-översikt och beteende

Förloppsreportern använder en hierarkisk modell med säkerställande av ordning och trådsäkra operationer.

API-struktur och användning

Reporter-API:et ger strukturerad åtkomst till förloppsrapportering med följande egenskaper:

• Förvärv: Hämtad från PublishingContext.ActivityReporter eller DeployingContext.ActivityReporter.
• Stegskapande: CreateStepAsync(title, ct) returnerar en IPublishingActivityStep.
• Skapande av uppgift: IPublishingActivityStep.CreateTaskAsync(title, ct) returnerar en IPublishingActivityTask.
• Tillståndsövergångar: SucceedAsync, WarnAsync, FailAsync metoder accepterar ett sammanfattningsmeddelande.
• Slutförande: CompletePublishAsync(message, state, isDeploy, ct) markerar hela åtgärden.
• Beställning: Skapande- och slutförandehändelser bevarar anropsordning; uppdateringar serialiseras.
• Annullering: Alla API:er accepterar CancellationToken och sprider annullering till CLI.
• Avyttringskontrakt: Deponeringssteg slutförs automatiskt om de är oavslutade, vilket förhindrar överblivna faser.

Exempel: Skapa containerbilder och rapportera framsteg

Om du vill använda dessa API:er lägger du till PublishingCallbackAnnotation, DeployingCallbackAnnotation eller båda i en resurs i din appmodell. Du kan kommentera anpassade (eller inbyggda) resurser genom att lägga till anteckningar i IResource.Annotations samlingen.

Som utvecklare kan du välja att:

• Använd båda anteckningarna om resursen måste fungera i både publicering och distribution. Skapa till exempel avbildningar och generera manifest under publiceringen, skicka sedan avbildningar eller konfigurera distributionsmål under distributionen. Publicering sker alltid före distributionen, så du kan hålla logiken för varje fas separat.

• Använd endast PublishingCallbackAnnotation om din resurs bara behöver göra något under publiceringen. Detta är vanligt när du bara behöver skapa artefakter eller avbildningar, men inte behöver göra något under distributionen.

• Använd endast DeployingCallbackAnnotation om din resurs bara behöver göra något under distributionen. Detta passar fall där du använder fördefinierade avbildningar och bara behöver distribuera eller konfigurera dem.

Välj en eller flera anteckningar som matchar resursens ansvarsområden för att hålla programmodellen tydlig och underhållsbar. Med den här separationen kan du tydligt definiera logik för varje fas, men du kan använda både aktivitetsreportern och resurscontainerns avbildningsbyggare i endera återanropet efter behov.

Exempelresurs med anteckningar

Tänk till exempel på ComputeEnvironmentResource konstruktorn:

public ComputeEnvironmentResource(string name) : base(name)
{
    Annotations.Add(new PublishingCallbackAnnotation(PublishAsync));
    Annotations.Add(new DeployingCallbackAnnotation(DeployAsync));
}

När den instansieras definierar den både en publicerings- och distribuerande återanropsannotering.

Anta att du har en tilläggsmetod som du exponerar med exempeltypen ComputeEnvironmentResource (Resource) så att konsumenterna kan lägga till beräkningsmiljön:

using System.Diagnostics.CodeAnalysis;

[Experimental("ASPIRECOMPUTE001")]
public static class ComputeEnvironmentResourceExtensions
{
    public static IResourceBuilder<ComputeEnvironmentResource> AddComputeEnvironment(
        this IDistributedApplicationBuilder builder,
        [ResourceName] string name)
    {
        var resource = new ComputeEnvironmentResource(name);

        return builder.AddResource(resource);
    }
}

Föregående kod:

• Definierar en tilläggsmetod för IDistributedApplicationBuilder.
• Accepterar en name för beräkningsmiljöresursen, som skyddas av ResourceNameAttribute.
• Skapar en instans av ComputeEnvironmentResource baserat på name och lägger till den i builder.

Exempel på AppHost

I din AppHost kan du lägga till ComputeEnvironmentResource i programmodellen så här:

var builder = DistributedApplication.CreateBuilder(args);

var cache = builder.AddRedis("redis");

builder.AddProject<Projects.Api>("api")
       .WithReference(cache);

builder.AddComputeEnvironment("compute-env");

builder.Build().Run();

Koden ovan använder AddComputeEnvironment tilläggsmetoden för att lägga ComputeEnvironmentResource till i programmodellen.

Publicera återanropsanteckning

När du lägger till ComputeEnvironmentResourceregistreras en PublishingCallbackAnnotation. Återuppringningsfunktionen PublishAsync använder metoden:

private static async Task PublishAsync(PublishingContext context)
{
    var reporter = context.ActivityReporter;
    var imageBuilder = context.Services.GetRequiredService<IResourceContainerImageBuilder>();

    // Build container images for all project resources in the application
    await using (var buildStep = await reporter.CreateStepAsync(
        "Build container images", context.CancellationToken))
    {
        // Find all resources that need container images
        var projectResources = context.Model.Resources
            .OfType<ProjectResource>()
            .ToList();

        if (projectResources.Count > 0)
        {
            // Configure how images should be built
            var buildOptions = new ContainerBuildOptions
            {
                ImageFormat = ContainerImageFormat.Oci,
                TargetPlatform = ContainerTargetPlatform.LinuxAmd64,
                OutputPath = Path.Combine(context.OutputPath, "images")
            };

            var buildTask = await buildStep.CreateTaskAsync(
                $"Building {projectResources.Count} container image(s)", context.CancellationToken);

            // Build all the container images
            await imageBuilder.BuildImagesAsync(
                projectResources, buildOptions, context.CancellationToken);

            await buildTask.SucceedAsync(
                $"Built {projectResources.Count} image(s) successfully", context.CancellationToken);
        }
        else
        {
            var skipTask = await buildStep.CreateTaskAsync(
                "No container images to build", context.CancellationToken);
                
            await skipTask.SucceedAsync("Skipped - no project resources found", context.CancellationToken);
        }

        await buildStep.SucceedAsync("Container image build completed", context.CancellationToken);
    }

    // Generate deployment manifests
    await using (var manifestStep = await reporter.CreateStepAsync(
        "Generate deployment manifests", context.CancellationToken))
    {
        var bicepTask = await manifestStep.CreateTaskAsync(
            "Write main.bicep", context.CancellationToken);

        // Write file to context.OutputPath …
        await bicepTask.SucceedAsync(
            $"main.bicep at {context.OutputPath}", context.CancellationToken);

        await manifestStep.SucceedAsync("Manifests ready", context.CancellationToken);
    }

    // Complete the publishing operation
    await reporter.CompletePublishAsync(
        completionMessage: "Publishing pipeline completed successfully",
        completionState: CompletionState.Completed,
        cancellationToken: context.CancellationToken);
}

Föregående kod:

• Implementerar en publiceringspipeline som skapar containeravbildningar och genererar distributionsmanifest.
• Använder API:et IResourceContainerImageBuilder för att skapa containeravbildningar.
• Rapporterar status för förlopp och slutförande med hjälp av API:et PublishingActivityProgressReporter .

Återanropet för publicering kan använda IResourceContainerImageBuilder för att bygga containerbilder, medan distributionsåteranropet kan använda de skapade bilderna och skicka dem till ett register eller distributionsmål.

Distribuera återanropsanteckning

Precis som återanropet för publicering registreras återanropet för distribution med hjälp av DeployingCallbackAnnotation och anropar DeployAsync metoden:

private static async Task DeployAsync(DeployingContext context)
{
    var reporter = context.ActivityReporter;

    await using (var deployStep = await reporter.CreateStepAsync(
        "Deploy to target environment", context.CancellationToken))
    {
        var applyTask = await deployStep.CreateTaskAsync(
            "Apply Kubernetes manifests", context.CancellationToken);

        // Simulate deploying to Kubernetes cluster
        await Task.Delay(1_000, context.CancellationToken);

        await applyTask.SucceedAsync("All workloads deployed", context.CancellationToken);
        await deployStep.SucceedAsync("Deployment to cluster completed", context.CancellationToken);
    }

    // Complete the deployment operation
    await reporter.CompletePublishAsync(
        completionMessage: "Deployment completed successfully",
        completionState: CompletionState.Completed,
        isDeploy: true,
        cancellationToken: context.CancellationToken);
}

Föregående kod:

• Simulerar distribution av arbetsbelastningar till ett Kubernetes kluster.
• Använder API:et PublishingActivityProgressReporter för att skapa och hantera distributionssteg och -uppgifter.
• Rapporterar förlopp och markerar varje distributionsfas som slutförd.
• Slutför distributionsåtgärden med en slutlig statusuppdatering.
• Hanterar annullering via den angivna CancellationToken.

Metodtips

Följ dessa riktlinjer när du använder dessa API:er:

Bildskapande

• Ange alltid explicit ContainerBuildOptions för produktionsscenarier.
• Överväg krav på målplattform när du skapar för distribution.
• Använd OCI-format för maximal kompatibilitet med containerregister.
• Hantera InvalidOperationException när hälsokontroller för containermiljö misslyckas.

Förloppsrapportering

• Kapsla in långvariga logiska faser i steg i stället för att generera råa uppgifter.
• Behåll rubrikerna koncisa (under 60 tecken) eftersom CLI trunkerar längre strängar.
• Anropa CompletePublishAsync exakt en gång per publicerings- eller distributionsåtgärd.
• Behandla varningar som återställningsbara och gör att efterföljande steg kan fortsätta.
• Behandla fel som kritiska och avbryt snabbt med klar diagnostik.
• Använd asynkrona, annulleringsmedvetna åtgärder för att undvika blockering av händelsebearbetning.

Statushantering

• Varje steg och aktivitet startar i Körningstillstånd och övergår exakt en gång till Slutförd, Varning eller Fel.
• Utlöser ett undantag vid försök till flera tillståndsövergångar.
• Dra nytta av reportern för att garantera ordnade händelser och förhindra överlappning.
• Kassera IPublishingActivityStep för att automatiskt slutföra oavslutade steg.

Se även

• Översikt över publicering och distribution
• Containerkonfiguration
• Dockerfile integration