Benutzerdefinierte HTTP-Befehle in .NET.NET Aspire

In .NET.NET Aspire, können Sie mithilfe der WithHttpCommand API benutzerdefinierte HTTP-Befehle zu Ressourcen hinzufügen. Diese API erweitert vorhandene Funktionen, in denen Sie benutzerdefinierte Befehle für Ressourcen bereitstellen. Dieses Feature ermöglicht einen Befehl für eine Ressource, die eine HTTP-Anforderung an einen angegebenen Endpunkt und Pfad sendet. Dies ist nützlich für Szenarien wie das Auslösen von Datenbankmigrationen, das Löschen von Caches oder das Ausführen benutzerdefinierter Aktionen für Ressourcen über HTTP-Anforderungen.

Um benutzerdefinierte HTTP-Befehle zu implementieren, definieren Sie einen Befehl für eine Ressource und einen entsprechenden HTTP-Endpunkt, der die Anforderung verarbeitet. Dieser Artikel enthält eine Übersicht über das Erstellen und Konfigurieren von benutzerdefinierten HTTP-Befehlen in .NET.NET Aspire.

HTTP-Befehls-APIs

Die verfügbaren APIs bieten umfangreiche Funktionen mit zahlreichen Parametern zum Anpassen des HTTP-Befehls. Verwenden Sie zum Hinzufügen eines HTTP-Befehls zu einer Ressource die WithHttpCommand Erweiterungsmethode für den Ressourcen-Generator. Es stehen zwei Überladungen zur Verfügung:

Die WithHttpCommand API bietet zwei Überladungen zum Hinzufügen von benutzerdefinierten HTTP-Befehlen zu Ressourcen in .NET.NET Aspire. Diese APIs sind darauf ausgelegt, Flexibilität zu bieten und bei der Definition von HTTP-Befehlen unterschiedliche Anwendungsfälle zu erfüllen.

1. Überladung mit endpointName:

   Diese Version ist ideal, wenn Sie über einen vordefinierten Endpunktnamen verfügen, auf den der HTTP-Befehl abzielen soll. Die Konfiguration wird vereinfacht, indem der Befehl direkt einem bestimmten Endpunkt zugeordnet wird. Dies ist in Szenarien hilfreich, in denen der Endpunkt während der Entwicklung statisch und bekannt ist.

2. Überladung mit endpointSelector:

   Diese Version bietet dynamischeres Verhalten, indem Sie einen Rückruf (endpointSelector) angeben können, um den Endpunkt zur Laufzeit zu ermitteln. Dies ist nützlich, wenn der Endpunkt je nach Status der Ressource oder anderen kontextbezogenen Faktoren variieren kann. Es bietet eine größere Flexibilität für erweiterte Szenarien, in denen der Endpunkt nicht hartcodiert werden kann.

Beide Überladungen ermöglichen es Ihnen, den HTTP-Befehl umfassend anzupassen, eine HttpCommandOptions Unterklasse des CommandOptions Typs bereitzustellen, einschließlich der Angabe der HTTP-Methode, der Konfiguration der Anforderung, der Behandlung der Antwort und definieren UI-bezogene Eigenschaften wie Anzeigename, Beschreibung und Symbole. Die Wahl zwischen den beiden hängt davon ab, ob der Endpunkt in Ihrem Anwendungsfall statisch oder dynamisch ist.

Diese APIs sind so konzipiert, dass sie nahtlos in das .NET.NET Aspire Ökosystem integriert werden, sodass Entwickler Ressourcenfunktionen mit minimalem Aufwand erweitern und gleichzeitig die Kontrolle über das Verhalten und die Darstellung der Befehle behalten können.

Überlegungen beim Registrieren von HTTP-Befehlen

Da HTTP-Befehle über HTTP-Endpunkte verfügbar gemacht werden, sollten Sie potenzielle Sicherheitsrisiken berücksichtigen. Beschränken Sie diese Endpunkte nach Möglichkeit auf Entwicklungs- oder Stagingumgebungen. Überprüfen Sie immer eingehende Anforderungen, um sicherzustellen, dass sie aus vertrauenswürdigen Quellen stammen. Weitere Informationen finden Sie unter ASP.NET Core Sicherheit.

Verwenden Sie die HttpCommandOptions.PrepareRequest Callback-Funktion, um die Sicherheit zu verbessern, indem Sie Authentifizierungsheader oder andere Maßnahmen hinzufügen. Ein allgemeiner Ansatz besteht darin, einen freigegebenen geheimen, externen Parameter oder Token zu verwenden, der nur dem App-Host und der App-Ressource bekannt ist. Dieser freigegebene Wert kann verwendet werden, um Anforderungen zu überprüfen und unbefugten Zugriff zu verhindern.

Hinzufügen eines benutzerdefinierten HTTP-Befehls

In der Datei Program.cs Ihres App-Hosts fügen Sie einen benutzerdefinierten HTTP-Befehl mithilfe der WithHttpCommand API in einem IResourceBuilder<T>, wo TIResourceWithEndpoints hin. Hier ist ein Beispiel für die vorgehensweise:

var builder = DistributedApplication.CreateBuilder(args);

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

var apiCacheInvalidationKey = builder.AddParameter("ApiCacheInvalidationKey", secret: true);

var api = builder.AddProject<Projects.AspireApp_Api>("api")
    .WithReference(cache)
    .WaitFor(cache)
    .WithEnvironment("ApiCacheInvalidationKey", apiCacheInvalidationKey)
    .WithHttpCommand(
        path: "/cache/invalidate",
        displayName: "Invalidate cache",
        commandOptions: new HttpCommandOptions()
        {
            Description = """            
                Invalidates the API cache. All cached values are cleared!            
                """,
            PrepareRequest = (context) =>
            {
                var key = apiCacheInvalidationKey.Resource.Value;

                context.Request.Headers.Add("X-CacheInvalidation-Key", $"Key: {key}");

                return Task.CompletedTask;
            },
            IconName = "DocumentLightning",
            IsHighlighted = true
        });

builder.Build().Run();

Der vorherige Code:

• Erstellt einen neuen verteilten Anwendungs-Generator.
• Fügt der Anwendung einen Redis Cache hinzu, der benannt ist cache .
• Fügt der Anwendung einen Parameter hinzu, der benannt ist ApiCacheInvalidationKey . Dieser Parameter ist als geheim gekennzeichnet, was bedeutet, dass sein Wert sicher behandelt wird.
• Fügt der Anwendung ein Projekt mit dem Namen AspireApp_Api hinzu.
• Fügt einen Verweis auf den Redis Cache hinzu und wartet, bis er bereit ist, bevor er fortgefahren wird.
• Konfiguriert einen HTTP-Befehl für das Projekt mit folgendem Code:
  • path: Gibt den URL-Pfad für den HTTP-Befehl (/cache/invalidate) an.
  • displayName: Legt den Namen des Befehls fest, wie er in der Benutzeroberfläche (Invalidate cache) angezeigt wird.
  • commandOptions: Eine optionale Instanz von HttpCommandOptions, die das Verhalten und die Darstellung des Befehls in der Benutzeroberfläche konfiguriert.
    • Description: Stellt eine Beschreibung des Befehls bereit, der in der Benutzeroberfläche angezeigt wird.
    • PrepareRequest: Eine Rückruffunktion, die die HTTP-Anforderung vor dem Senden konfiguriert. In diesem Fall wird eine benutzerdefinierte (X-CacheInvalidation-Key) Kopfzeile mit dem Wert des ApiCacheInvalidationKey Parameters hinzugefügt.
    • IconName: Gibt das Symbol an, das für den Befehl in der Benutzeroberfläche (DocumentLightningFilled) verwendet werden soll.
    • IsHighlighted: Gibt an, ob der Befehl in der Benutzeroberfläche hervorgehoben werden soll.
• Schließlich wird die Anwendung erstellt und ausgeführt.

Der HTTP-Endpunkt ist für die Ungültigung des Caches verantwortlich. Wenn der Befehl ausgeführt wird, sendet er eine HTTP-Anforderung mit den konfigurierten Parametern an den angegebenen Pfad (/cache/invalidate). Da es ein zusätzliches Sicherheitsmaß gibt, enthält die Anforderung den X-CacheInvalidation-Key Header mit dem Wert des ApiCacheInvalidationKey Parameters. Dadurch wird sichergestellt, dass nur autorisierte Anforderungen den Cache-Ungültigheitsprozess auslösen können.

Beispiel-HTTP-Endpunkt

Der vorangehende App-Hostcodeausschnitt hat einen benutzerdefinierten HTTP-Befehl definiert, der eine Anforderung an den /cache/invalidate Endpunkt sendet. Das ASP.NET Core minimale API-Projekt definiert einen HTTP-Endpunkt, der die Cache-Ungültigheitsanforderung verarbeitet. Betrachten Sie den folgenden Codeausschnitt aus der Program.cs Datei des Projekts:

app.MapPost("/cache/invalidate", static async (
    [FromHeader(Name = "X-CacheInvalidation-Key")] string? header,
    ICacheService registry,
    IConfiguration config) =>
{
    var hasValidHeader = config.GetValue<string>("ApiCacheInvalidationKey") is { } key
        && header == $"Key: {key}";

    if (hasValidHeader is false)
    {
        return Results.Unauthorized();
    }

    await registry.ClearAllAsync();

    return Results.Ok();
});

Der vorherige Code:

• Es wird davon ausgegangen, dass die app Variable eine Instanz von IApplicationBuilder ist und für die Verarbeitung von HTTP-Anforderungen eingerichtet wurde.
• Ordnet einen HTTP-POST-Endpunkt am Pfad /cache/invalidate zu.
• Der Endpunkt erwartet, dass ein Header mit dem Namen X-CacheInvalidation-Key in der Anforderung vorhanden ist.
• Er ruft den Wert des ApiCacheInvalidationKey Parameters aus der Konfiguration ab.
• Wenn der Headerwert nicht mit dem erwarteten Schlüssel übereinstimmt, wird eine nicht autorisierte Antwort zurückgegeben.
• Wenn der Header gültig ist, ruft sie die ClearAllAsync Methode auf ICacheService , um alle zwischengespeicherten Elemente zu löschen.
• Schließlich wird eine HTTP OK-Antwort zurückgegeben.

Beispiel für Dashboarderfahrungen

Der Beispiel-App-Host und die entsprechenden minimalen API-Projekte veranschaulichen ASP.NET Core beide Seiten der HTTP-Befehlsimplementierung. Wenn Sie den App-Host ausführen, zeigt die Ressourcenseite des Dashboards den benutzerdefinierten HTTP-Befehl als Schaltfläche an. Wenn Sie angeben, dass der Befehl hervorgehoben werden soll (isHighlighted: true), wird die Schaltfläche in der Spalte "Aktionen " der Seite " Ressourcen " angezeigt. Auf diese Weise können Benutzer den Befehl ganz einfach über das Dashboard auslösen, wie im folgenden Screenshot gezeigt:

Wenn Sie den isHighlighted Parameter weglassen oder auf false festlegen, wird der Befehl unter dem Menü mit den horizontalen Auslassungspunkten (drei Punkte) in der Spalte Aktionen der Seite Ressourcen geschachtelt angezeigt. Dadurch können Benutzer auf den Befehl zugreifen, ohne die Benutzeroberfläche mit zu vielen Schaltflächen zu überladen. Der folgende Screenshot zeigt denselben Befehl, der im Auslassungszeichenmenü angezeigt wird:

Wenn der Benutzer die Schaltfläche auswählt, wird der Befehl ausgeführt, und die HTTP-Anforderung wird an den angegebenen Endpunkt gesendet. Das Dashboard gibt Feedback zum Ausführungsstatus des Befehls, sodass Benutzer die Ergebnisse überwachen können. Beim Starten wird eine Toast-Benachrichtigung angezeigt:

Nach Abschluss des Befehls aktualisiert das Dashboard den Status und gibt Feedback darüber, ob er erfolgreich war oder fehlgeschlagen ist. Der folgende Screenshot zeigt eine erfolgreiche Ausführung des Befehls:

Siehe auch

• .NET .NET Aspire Übersicht über die Orchestrierung
• Benutzerdefinierte Ressourcenbefehle in .NET.NET Aspire
• .NET Aspire GitHub Repository: Beispiel für einen Playground