Dela via

Resursanteckningar i Aspire

Anteckningar är en viktig utökningsmekanism i Aspire som gör att du kan bifoga metadata och beteende till resurser. De ger ett sätt att anpassa hur resurser konfigureras, distribueras och hanteras under hela programmets livscykel. Den här artikeln förklarar hur anteckningar fungerar och hur du använder dem effektivt i dina Aspire program.

Vad är anteckningar

Anteckningar i Aspire är objekt som implementerar IResourceAnnotation gränssnittet. De är kopplade till resurser för att tillhandahålla ytterligare metadata, konfiguration eller beteende. Anteckningar används av olika delar av Aspire-stacken, inklusive:

  • Instrumentpanelen för att visa anpassade URL:er och kommandon.
  • Distributionsverktyg för att generera infrastruktur som kod.
  • Lagringslagret för att konfigurera körningsegenskaper.
  • Testa infrastrukturen för resursgranskning.

Varje anteckning är associerad med en specifik resurs och kan innehålla data eller beteenden som behövs för att utöka resursens funktioner.

Så här fungerar anteckningar

När du lägger till en resurs i appmodellen kan du bifoga anteckningar med hjälp av olika tilläggsmetoder. Dessa anteckningar lagras med resursen och kan hämtas och bearbetas av olika komponenter i systemet.

Här är ett enkelt exempel på hur anteckningar används:

var builder = DistributedApplication.CreateBuilder(args);

var redis = builder.AddRedis("cache")
    .WithCommand("clear-cache", "Clear Cache", 
        async context => new ExecuteCommandResult { Success = true })
    .WithUrl("admin", "http://localhost:8080/admin");

builder.Build().Run();

I det här exemplet:

Inbyggda anteckningstyper

Aspire innehåller många inbyggda anteckningstyper för vanliga scenarier. Det här avsnittet beskriver några av de vanligaste anteckningarna, men det finns många fler tillgängliga för specifika användningsfall.

EndpointAnnotation

Definierar EndpointAnnotation nätverksslutpunkter för resurser. Den innehåller information om portar, protokoll och slutpunktskonfiguration.

var api = builder.AddProject<Projects.Api>("api")
    .WithEndpoint(callback: endpoint =>
    {
        endpoint.Port = 5000;
        endpoint.IsExternal = true;
        endpoint.Protocol = Protocol.Tcp;
        endpoint.Transport = "http";
    });

ResourceUrlAnnotation

Det ResourceUrlAnnotation definierar anpassade URL:er som visas på kontrollpanelen och som ofta pekar på hanteringsgränssnitt eller dokumentation.

var database = builder.AddPostgres("postgres")
    .WithUrl("admin", "https://localhost:5050");

EnvironmentCallbackAnnotation

Med EnvironmentCallbackAnnotation kan du ändra miljövariabler under körning baserat på tillståndet för andra resurser.

// This is typically used internally by WithReference
var app = builder.AddProject<Projects.MyApp>("app")
    .WithReference(database);

ContainerMountAnnotation

ContainerMountAnnotation Definierar volymmonteringar för containerbaserade resurser.

var postgres = builder.AddPostgres("postgres")
    .WithDataVolume(); // Adds a ContainerMountAnnotation

PublishingCallbackAnnotation

Med PublishingCallbackAnnotation kan du registrera callback-funktioner som körs under publiceringsprocessen. Detta är användbart för att utföra anpassade åtgärder när resurser publiceras.

var api = builder.AddProject<Projects.Api>("api")
    .WithPublishingCallback(async context =>
    {
        // Custom logic during publishing
        await CustomPublishLogicAsync(context);
    });

Mer information finns i WithPublishingCallback.

DeployingCallbackAnnotation

Med DeployingCallbackAnnotation kan du registrera återanrop som körs under distributionsprocessen. Den här kommentaren används internt av distributionsverktyg för att anpassa beteendet för resursdistribution.

var api = builder.AddProject<Projects.Api>("api");

api.Resource.Annotations.Add(
    new DeployingCallbackAnnotation(async context =>
    {
        // Custom deployment logic
        await ConfigureDeploymentAsync(context);
    });
);

Mer information om hur du publicerar och distribuerar Aspire appar finns i publicera och distribuera.

Skapa anpassade anteckningar

Anpassade anteckningar i Aspire är utformade för att samla in resursspecifika metadata och beteenden som kan användas under hela programmets livscykel. De används ofta av:

  • Tilläggsmetoder för att härleda användaravsikt och konfigurera resursbeteende.
  • Distributionsverktyg för att generera distributionsspecifik konfiguration.
  • Livscykelhakar för att fråga appmodellen och göra beslut under körning.
  • Utvecklingsverktyg som instrumentpanelen för att visa resursinformation.

Anpassade anteckningar bör fokusera på ett enda problem och ge ett tydligt värde för användare av resursmetadata.

1. Definiera anteckningsklassen

Börja med att skapa en klass som implementerar IResourceAnnotation. Fokusera på att samla in specifika metadata som andra komponenter behöver resonera kring din resurs:

public sealed class ServiceMetricsAnnotation : IResourceAnnotation
{
    public string MetricsPath { get; set; } = "/metrics";
    public int Port { get; set; } = 9090;
    public bool Enabled { get; set; } = true;
    public string[] AdditionalLabels { get; set; } = [];
}

2. Skapa tilläggsmetoder

Skapa fluent-tilläggsmetoder som följer Aspirebyggmönstret. Dessa metoder bör göra det enkelt för AppHost-författare att konfigurera din anteckning:

public static class ServiceMetricsExtensions
{
    public static IResourceBuilder<T> WithMetrics<T>(
        this IResourceBuilder<T> builder,
        string path = "/metrics",
        int port = 9090,
        params string[] labels)
        where T : class, IResource
    {
        var annotation = new ServiceMetricsAnnotation
        {
            MetricsPath = path,
            Port = port,
            Enabled = true,
            AdditionalLabels = labels
        };

        return builder.WithAnnotation(annotation);
    }

    public static IResourceBuilder<T> WithoutMetrics<T>(
        this IResourceBuilder<T> builder)
        where T : class, IResource
    {
        return builder.WithAnnotation(new ServiceMetricsAnnotation { Enabled = false });
    }
}

Tilläggsmetoderna fungerar som den primära API-ytan för din anteckning. De bör:

  • Följ namngivningskonventionerna (börja med With för additiva åtgärder).
  • Ange lämpliga standardvärden.
  • Returnera byggaren för metodkedjning.
  • Inkludera omfattande XML-dokumentation.

3. Använd den anpassade kommentaren

När de har definierats integreras anteckningar sömlöst i AppHost-modellen:

var builder = DistributedApplication.CreateBuilder(args);

var api = builder.AddProject<Projects.Api>("api")
    .WithMetrics("/api/metrics", 9090, "environment:production", "service:api");

Testa med anteckningar

När du skriver tester kan du granska anteckningar för att verifiera resurskonfigurationen:

[Fact]
public async Task Resource_Should_Have_Expected_Annotations()
{
    var appHost = await DistributedApplicationTestingBuilder
        .CreateAsync<Projects.MyApp_AppHost>();

    await using var app = await appHost.BuildAsync();

    var resource = app.Resources.GetResource("my-resource");

    // Assert that specific annotations exist
    Assert.NotEmpty(resource.Annotations.OfType<ServiceMetricsAnnotation>());

    // Assert annotation properties
    var metricsConfig = resource.Annotations
        .OfType<ServiceMetricsAnnotation>()
        .First();
    
    Assert.True(metricsConfig.Enabled);
    Assert.Equal("/metrics", metricsConfig.MetricsPath);
}

Mer information finns i Testa med Aspire.

Metodtips

När du arbetar med anteckningar bör du överväga följande metodtips:

Använda meningsfulla namn

Välj beskrivande namn för dina anteckningsklasser och egenskaper:

// Good
public sealed class DatabaseConnectionPoolAnnotation : IResourceAnnotation

// Avoid
public sealed class DbAnnotation : IResourceAnnotation

Följ builder-mönstret

Skapa flytande tilläggsmetoder som följer Aspire byggarmönstret.

var resource = builder.AddMyResource("name")
    .WithCustomBehavior()
    .WithAnotherFeature();

Dokumentera dina anteckningar

Ange XML-dokumentation för anpassade anteckningar och tilläggsmetoder:

/// <summary>
/// Configures custom caching behavior for the resource.
/// </summary>
/// <param name="builder">The resource builder.</param>
/// <param name="ttl">The time-to-live for cached items.</param>
/// <returns>The resource builder for chaining.</returns>
public static IResourceBuilder<T> WithCaching<T>(
    this IResourceBuilder<T> builder,
    TimeSpan ttl)
    where T : class, IResource { /*...*/ }

Behåll anteckningar enkelt

Anteckningar bör fokusera på ett enda ansvar:

// Good - single responsibility
public sealed class RetryPolicyAnnotation : IResourceAnnotation
{
    public int MaxRetries { get; set; }
    public TimeSpan Delay { get; set; }
}

// Avoid - multiple responsibilities
public sealed class ConfigAnnotation : IResourceAnnotation
{
    public RetryPolicy RetryPolicy { get; set; }
    public LoggingSettings Logging { get; set; }
    public SecuritySettings Security { get; set; }
}

Nästa steg