Sdílet prostřednictvím

Poznámky k prostředkům v Aspire

Poznámky jsou klíčový mechanismus rozšiřitelnosti v Aspire, který umožňuje připojit metadata a chování k prostředkům. Poskytují způsob, jak přizpůsobit, jak se prostředky konfigurují, nasazují a spravují v průběhu životního cyklu aplikace. Tento článek vysvětluje, jak fungují poznámky a jak je efektivně používat ve vašich Aspire aplikacích.

Co jsou poznámky

Anotace v Aspire jsou objekty, které implementují rozhraní IResourceAnnotation. Jsou připojené k prostředkům, aby poskytovaly další metadata, konfiguraci nebo chování. Různé části zásobníku Aspire využívají poznámky, mezi které patří:

  • Řídicí panel pro zobrazení vlastních adres URL a příkazů
  • Nástroje pro nasazení pro generování infrastruktury jako kódu
  • Vrstva hostování pro konfiguraci chování modulu runtime.
  • Testování infrastruktury pro kontrolu prostředků

Každá poznámka je přidružená k určitému prostředku a může obsahovat jakákoli data nebo chování potřebná k rozšíření funkčnosti daného prostředku.

Jak fungují poznámky

Když do modelu aplikace přidáte prostředek, můžete poznámky připojit pomocí různých rozšiřujících metod. Tyto poznámky jsou uloženy s prostředkem a lze je načíst a zpracovat různými součástmi systému.

Tady je jednoduchý příklad použití poznámek:

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

V tomto příkladu:

Předdefinované typy poznámek

Aspire obsahuje mnoho předdefinovaných typů poznámek pro běžné scénáře. Tato část popisuje některé běžně používané poznámky, ale pro konkrétní případy použití je k dispozici mnohem více .

EndpointAnnotation

EndpointAnnotation definuje koncové body sítě pro prostředky. Obsahuje informace o portech, protokolech a konfiguraci koncového bodu.

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

ResourceUrlAnnotation

Element ResourceUrlAnnotation definuje vlastní adresy URL, které se zobrazují na řídicím panelu a často míří na rozhraní pro správu nebo dokumentaci.

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

EnvironmentCallbackAnnotation

EnvironmentCallbackAnnotation vám umožňuje upravit proměnné prostředí při běhu programu na základě stavu jiných prostředků.

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

ContainerMountAnnotation

Prvek ContainerMountAnnotation definuje připojení svazků pro kontejnerizované prostředky.

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

PublishingCallbackAnnotation

PublishingCallbackAnnotation vám umožňuje registrovat zpětná volání, která se provádějí během procesu publikování. To je užitečné pro provádění vlastních operací, když jsou zdroje publikovány.

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

Další informace najdete v tématu WithPublishingCallback.

DeployingCallbackAnnotation

Tento nástroj DeployingCallbackAnnotation umožňuje registrovat zpětná volání, která se spouštějí během procesu nasazení. Tuto poznámku interně používají nástroje nasazení k přizpůsobení chování nasazení prostředků.

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

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

Další informace o publikování a nasazování Aspire aplikací najdete v tématu publikování a nasazení.

Vytváření vlastních poznámek

Vlastní poznámky Aspire jsou navržené tak, aby zaznamenávaly metadata a chování specifické pro prostředky, které je možné využít v průběhu životního cyklu aplikace. Běžně se používají v:

  • Metody rozšíření pro odvození záměru uživatele a nastavení chování zdrojů
  • Nástroje pro nasazení pro generování konfigurace specifické pro nasazení
  • Háčky životního cyklu pro dotazování modelu aplikace a pro rozhodování za běhu.
  • Vývojové nástroje , jako je řídicí panel, slouží k zobrazení informací o prostředcích.

Vlastní poznámky by se měly zaměřit na jeden problém a poskytnout uživatelům metadat prostředků jasnou hodnotu.

1. Definujte třídu poznámek.

Začněte vytvořením třídy, která implementuje IResourceAnnotation. Zaměřte se na zachycení konkrétních metadat, která ostatní komponenty potřebují k odůvodnění vašeho prostředku:

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. Vytvoření rozšiřujících metod

Vytvořte rozšiřující metody ve stylu fluent, které se řídí vzorem tvůrce Aspire. Tyto metody by měly autorům AppHost usnadnit konfiguraci poznámek:

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

Metody rozšíření slouží jako primární plocha rozhraní API pro vaši poznámku. Měly by:

  • Postupujte podle konvencí pojmenování (začněte s With pro operace sčítání).
  • Poskytovat rozumné výchozí hodnoty.
  • Vrátit objekt pro řetězení metod.
  • Zahrnout komplexní dokumentaci XML.

3. Použití vlastní poznámky

Po definování se poznámky bezproblémově integrují do modelu AppHost:

var builder = DistributedApplication.CreateBuilder(args);

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

Testování pomocí poznámek

Při psaní testů můžete zkontrolovat poznámky a ověřit konfiguraci prostředků:

[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);
}

Další informace naleznete v tématu Testování pomocí Aspire.

Osvědčené postupy

Při práci s poznámkami zvažte tyto osvědčené postupy:

Použití smysluplných názvů

Zvolte popisné názvy tříd a vlastností poznámek:

// Good
public sealed class DatabaseConnectionPoolAnnotation : IResourceAnnotation

// Avoid
public sealed class DbAnnotation : IResourceAnnotation

Postupujte podle návrhového vzoru Builder.

Vytvořte fluentní rozšiřující metody, které se řídí vzorem Builderu Aspire.

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

Zdokumentujte poznámky

Zadejte dokumentaci XML pro vlastní poznámky a rozšiřující metody:

/// <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 { /*...*/ }

Zachování jednoduchých poznámek

Poznámky by se měly zaměřit na jednu odpovědnost:

// 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; }
}

Další kroky

  • Last updated on