Aangepaste .NET.NET Aspire hostingintegraties maken

Artikel
12/14/2024

.NET .NET Aspire verbetert de ontwikkelervaring door herbruikbare bouwstenen te bieden die kunnen worden gebruikt om toepassingsafhankelijkheden snel te rangschikken en beschikbaar te maken voor uw eigen code. Een van de belangrijkste bouwstenen van een Aspire-gebaseerde toepassing is de resource. Bekijk de onderstaande code:

var builder = DistributedApplication.CreateBuilder(args);

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

var db = builder.AddPostgres("pgserver")
                .AddDatabase("inventorydb");

builder.AddProject<Projects.InventoryService>("inventoryservice")
       .WithReference(redis)
       .WithReference(db);

In de voorgaande code worden vier resources weergegeven:

cache: een Redis container.
pgserver: een Postgres container.
inventorydb: een database die wordt gehost op pgserver.
inventoryservice: een ASP.NET Core-toepassing.

De meeste .NET.NET Aspire-gerelateerde code die door de gemiddelde ontwikkelaar wordt geschreven, gaat over het toevoegen van resources aan het app-model en het maken van verwijzingen ertussen.

Belangrijke elementen van een .NET.NET Aspire aangepaste resource

Voor het bouwen van een aangepaste resource in .NET.NET Aspire is het volgende vereist:

Een aangepast resourcetype dat IResource implementeert
Een extensiemethode voor IDistributedApplicationBuilder met de naam Add{CustomResource} waarbij {CustomResource} de naam van de aangepaste resource is.

Wanneer voor aangepaste resources optionele configuratie is vereist, willen ontwikkelaars mogelijk With* extensiemethoden implementeren om deze configuratieopties detecteerbaar te maken met behulp van het builder-patroon.

Een praktisch voorbeeld: MailDev

Voor meer informatie over het ontwikkelen van aangepaste resources laat dit artikel een voorbeeld zien van het bouwen van een aangepaste resource voor MailDev. MailDev is een opensource-hulpprogramma dat een lokale e-mailserver biedt die is ontworpen om ontwikkelaars in staat te stellen e-mailverzendingsgedrag in hun app te testen. Zie de MailDevGitHub opslagplaatsvoor meer informatie.

In dit voorbeeld maakt u een nieuw .NET Aspire-project als testomgeving voor de MailDev resource die u maakt. Hoewel u aangepaste resources in bestaande .NET Aspire projecten kunt maken, is het een goed idee om te overwegen of de aangepaste resource kan worden gebruikt in meerdere .NET Aspire-gebaseerde oplossingen en moet worden ontwikkeld als herbruikbare integratie.

Het startersproject instellen

Maak een nieuw .NET.NET Aspire project dat wordt gebruikt om de nieuwe resource te testen die we ontwikkelen.

dotnet new aspire -o MailDevResource
cd MailDevResource
dir

Zodra het project is gemaakt, ziet u een lijst met het volgende:

MailDevResource.AppHost: de app-host gebruikt om de aangepaste bron te testen.
MailDevResource.ServiceDefaults: de -service is standaard project voor gebruik in servicegerelateerde projecten.
MailDevResource.sln: het oplossingsbestand waarnaar beide projecten verwijzen.

Controleer of het project kan worden gebouwd en uitgevoerd door de volgende opdracht uit te voeren:

dotnet run --project MailDevResource.AppHost/MailDevResource.AppHost.csproj

De console-uitvoer moet er ongeveer als volgt uitzien:

Building...
info: Aspire.Hosting.DistributedApplication[0]
      Aspire version: 9.0.0
info: Aspire.Hosting.DistributedApplication[0]
      Distributed application starting.
info: Aspire.Hosting.DistributedApplication[0]
      Application host directory is:
      ..\docs-aspire\docs\extensibility\snippets\MailDevResource\MailDevResource.AppHost
info: Aspire.Hosting.DistributedApplication[0]
      Now listening on: https://localhost:17251
info: Aspire.Hosting.DistributedApplication[0]
      Login to the dashboard at https://localhost:17251/login?t=928db244c720c5022a7a9bf5cf3a3526
info: Aspire.Hosting.DistributedApplication[0]
      Distributed application started. Press Ctrl+C to shut down.

Selecteer de koppeling dashboard in de browser om het .NET.NET Aspire dashboard weer te geven:

Druk op Ctrl+C om de app af te sluiten (u kunt het browsertabblad sluiten).

Bibliotheek maken voor middelenextensie

.NET Aspire resources zijn simpelweg klassen en methoden in een klassebibliotheek die verwijst naar de .NET Aspire Hosting bibliotheek (Aspire.Hosting). Door de resource in een afzonderlijk project te plaatsen, kunt u deze eenvoudiger delen tussen .NET.NET Aspireapps en mogelijk verpakken en delen op NuGet.

Maak het klassebibliotheekproject met de naam MailDev. Hosting.
```
dotnet new classlib -o MailDev.Hosting
```
Voeg Aspire.Hosting als pakketreferentie toe aan de klassebibliotheek.
```
dotnet add ./MailDev.Hosting/MailDev.Hosting.csproj package Aspire.Hosting --version 9.0.0
```
Belangrijk

De versie die u hier opgeeft, moet overeenkomen met de versie van de .NET.NET Aspire workload die is geïnstalleerd.

Voeg klassebibliotheekreferentie toe aan het project MailDevResource.AppHost.

dotnet add ./MailDevResource.AppHost/MailDevResource.AppHost.csproj reference ./MailDev.Hosting/MailDev.Hosting.csproj

Voeg het klassebibliotheekproject toe aan het oplossingsbestand.

dotnet sln ./MailDevResource.sln add ./MailDev.Hosting/MailDev.Hosting.csproj

Zodra de volgende stappen zijn uitgevoerd, kunt u het project starten:

dotnet run --project ./MailDevResource.AppHost/MailDevResource.AppHost.csproj

Dit resulteert in een waarschuwing die wordt weergegeven in de console:

.\.nuget\packages\aspire.hosting.apphost\9.0.0\build\Aspire.Hosting.AppHost.targets(174,5): warning ASPIRE004: '..\MailDev.Hosting\MailDev.Hosting.csproj' is referenced by an A
spire Host project, but it is not an executable. Did you mean to set IsAspireProjectResource="false"? [D:\source\repos\docs-aspire\docs\extensibility\snippets\MailDevResource\MailDevResource.AppHost\MailDevRe
source.AppHost.csproj]

Dit komt doordat .NET.NET Aspire projectverwijzingen in de app-host behandelt alsof het serviceprojecten zijn. Om .NET.NET Aspire te laten weten dat de projectreferentie moet worden behandeld als een niet-serviceproject, wijzigt u de MailDevResource.AppHostMailDevResource.AppHost.csproj bestanden die verwijzen naar het MailDev.Hosting project als volgt:

<ItemGroup>
  <!-- The IsAspireProjectResource attribute tells .NET Aspire to treat this 
       reference as a standard project reference and not attempt to generate
       a metadata file -->
  <ProjectReference Include="..\MailDev.Hosting\MailDev.Hosting.csproj"
                    IsAspireProjectResource="false" />
</ItemGroup>

Wanneer u de app-host start, wordt er geen waarschuwing weergegeven voor de console.

De resourcetypen definiëren

De MailDev.Hosting klassebibliotheek bevat het resourcetype en de extensiemethoden om de resource aan de app-host toe te voegen. Denk eerst na over de ervaring die u ontwikkelaars wilt bieden bij het gebruik van uw aangepaste resource. In het geval van deze aangepaste resource wilt u dat ontwikkelaars code kunnen schrijven zoals de volgende:

var builder = DistributedApplication.CreateBuilder(args);

var maildev = builder.AddMailDev("maildev");

builder.AddProject<Projects.NewsletterService>("newsletterservice")
       .WithReference(maildev);

Hiervoor hebt u een aangepaste resource nodig met de naam MailDevResource die IResourceWithConnectionString implementeert, zodat gebruikers deze kunnen gebruiken met WithReference extensie om de verbindingsgegevens voor de MailDev-server als verbindingsreeks in te voeren.

MailDev is beschikbaar als een containerresource, dus u wilt ook afleiden uit ContainerResource, zodat we gebruik kunnen maken van verschillende bestaande containeruitbreidingen in .NET.NET Aspire.

Vervang de inhoud van het Class1.cs-bestand in het MailDev.Hosting project en wijzig de naam van het bestand in MailDevResource.cs door de volgende code:

// For ease of discovery, resource types should be placed in
// the Aspire.Hosting.ApplicationModel namespace. If there is
// likelihood of a conflict on the resource name consider using
// an alternative namespace.
namespace Aspire.Hosting.ApplicationModel;

public sealed class MailDevResource(string name) : ContainerResource(name), IResourceWithConnectionString
{
    // Constants used to refer to well known-endpoint names, this is specific
    // for each resource type. MailDev exposes an SMTP endpoint and a HTTP
    // endpoint.
    internal const string SmtpEndpointName = "smtp";
    internal const string HttpEndpointName = "http";

    // An EndpointReference is a core .NET Aspire type used for keeping
    // track of endpoint details in expressions. Simple literal values cannot
    // be used because endpoints are not known until containers are launched.
    private EndpointReference? _smtpReference;

    public EndpointReference SmtpEndpoint =>
        _smtpReference ??= new(this, SmtpEndpointName);

    // Required property on IResourceWithConnectionString. Represents a connection
    // string that applications can use to access the MailDev server. In this case
    // the connection string is composed of the SmtpEndpoint endpoint reference.
    public ReferenceExpression ConnectionStringExpression =>
        ReferenceExpression.Create(
            $"smtp://{SmtpEndpoint.Property(EndpointProperty.Host)}:{SmtpEndpoint.Property(EndpointProperty.Port)}"
        );
}

In de voorgaande aangepaste resource zijn de EndpointReference en ReferenceExpression voorbeelden van verschillende typen die een verzameling interfaces implementeren, zoals IManifestExpressionProvider, IValueProvideren IValueWithReferences. Zie .NETvoor meer informatie over deze typen en hun rol in .NET Aspire.

De resource-extensies definiëren

Om het voor ontwikkelaars eenvoudiger te maken de aangepaste resource te gebruiken, moet een uitbreidingsmethode met de naam AddMailDev aan het MailDev.Hosting-project worden toegevoegd. De AddMailDev-extensiemethode is verantwoordelijk voor het configureren van de resource, zodat deze kan worden gestart als een container.

Voeg de volgende code toe aan een nieuw bestand met de naam MailDevResourceBuilderExtensions.cs in de MailDev. Hosting project:

using Aspire.Hosting.ApplicationModel;

// Put extensions in the Aspire.Hosting namespace to ease discovery as referencing
// the .NET Aspire hosting package automatically adds this namespace.
namespace Aspire.Hosting;

public static class MailDevResourceBuilderExtensions
{
    /// <summary>
    /// Adds the <see cref="MailDevResource"/> to the given
    /// <paramref name="builder"/> instance. Uses the "2.1.0" tag.
    /// </summary>
    /// <param name="builder">The <see cref="IDistributedApplicationBuilder"/>.</param>
    /// <param name="name">The name of the resource.</param>
    /// <param name="httpPort">The HTTP port.</param>
    /// <param name="smtpPort">The SMTP port.</param>
    /// <returns>
    /// An <see cref="IResourceBuilder{MailDevResource}"/> instance that
    /// represents the added MailDev resource.
    /// </returns>
    public static IResourceBuilder<MailDevResource> AddMailDev(
        this IDistributedApplicationBuilder builder,
        string name,
        int? httpPort = null,
        int? smtpPort = null)
    {
        // The AddResource method is a core API within .NET Aspire and is
        // used by resource developers to wrap a custom resource in an
        // IResourceBuilder<T> instance. Extension methods to customize
        // the resource (if any exist) target the builder interface.
        var resource = new MailDevResource(name);

        return builder.AddResource(resource)
                      .WithImage(MailDevContainerImageTags.Image)
                      .WithImageRegistry(MailDevContainerImageTags.Registry)
                      .WithImageTag(MailDevContainerImageTags.Tag)
                      .WithHttpEndpoint(
                          targetPort: 1080,
                          port: httpPort,
                          name: MailDevResource.HttpEndpointName)
                      .WithEndpoint(
                          targetPort: 1025,
                          port: smtpPort,
                          name: MailDevResource.SmtpEndpointName);
    }
}

// This class just contains constant strings that can be updated periodically
// when new versions of the underlying container are released.
internal static class MailDevContainerImageTags
{
    internal const string Registry = "docker.io";

    internal const string Image = "maildev/maildev";

    internal const string Tag = "2.1.0";
}

Aangepaste integratie valideren in de app-host

Nu de basisstructuur voor de aangepaste resource is voltooid, is het tijd om deze te testen in een echt AppHost-project. Open het bestand Program.cs in het MailDevResource.AppHost project en werk het bij met de volgende code:

var builder = DistributedApplication.CreateBuilder(args);

var maildev = builder.AddMailDev("maildev");

builder.Build().Run();

Nadat u het Program.cs-bestand hebt bijgewerkt, start u het app-hostproject en opent u het dashboard:

dotnet run --project ./MailDevResource.AppHost/MailDevResource.AppHost.csproj

Na enkele ogenblikken toont het dashboard dat de maildev resource wordt uitgevoerd en is er een hyperlink beschikbaar die naar de MailDev web-app navigeert, waarin de inhoud wordt weergegeven van elke e-mail die uw app verzendt.

Het .NET.NET Aspire-dashboard moet er ongeveer als volgt uitzien:

De MailDev-web-app moet er ongeveer als volgt uitzien:

Een .NET-serviceproject toevoegen aan de app-host voor testen

Zodra .NET Aspire de MailDev-integratie kan starten, is het tijd om de verbindingsgegevens voor MailDev binnen een .NET project te gebruiken. In .NET.NET Aspire is het gebruikelijk dat er een hostingpakket is en een of meer onderdelenpakketten. Denk bijvoorbeeld aan:

hostingpakket: wordt gebruikt om resources binnen het app-model weer te geven.
- Aspire.Hosting.Redis
componentpakketten: wordt gebruikt voor het configureren en gebruiken van clientbibliotheken.
- Aspire.StackExchange.Redis
- Aspire.StackExchange.Redis.DistributedCaching
- Aspire.StackExchange.Redis.OutputCaching

In het geval van de MailDev-resource heeft het .NET platform al een SMTP-client (Simple Mail Transfer Protocol) in de vorm van SmtpClient. In dit voorbeeld gebruikt u deze bestaande API omwille van de eenvoud, hoewel andere resourcetypen kunnen profiteren van aangepaste integratiebibliotheken om ontwikkelaars te helpen.

Als u het end-to-end-scenario wilt testen, hebt u een .NET project nodig waarin we de verbindingsgegevens voor de MailDev resource kunnen invoeren. Een web-API-project toevoegen:

Maak een nieuw .NET project met de naam MailDevResource.NewsletterService.

dotnet new webapi --use-minimal-apis -o MailDevResource.NewsletterService

Voeg een verwijzing toe naar het MailDev.Hosting project.

dotnet add ./MailDevResource.NewsletterService/MailDevResource.NewsletterService.csproj reference ./MailDev.Hosting/MailDev.Hosting.csproj

Voeg een verwijzing toe naar het MailDevResource.AppHost project.

dotnet add ./MailDevResource.AppHost/MailDevResource.AppHost.csproj reference ./MailDevResource.NewsletterService/MailDevResource.NewsletterService.csproj

Voeg het nieuwe project toe aan het oplossingsbestand.

dotnet sln ./MailDevResource.sln add ./MailDevResource.NewsletterService/MailDevResource.NewsletterService.csproj

Nadat het project is toegevoegd en verwijzingen zijn bijgewerkt, opent u het Program.cs van het MailDevResource.AppHost.csproj project en werkt u het bronbestand bij zodat het er als volgt uitziet:

var builder = DistributedApplication.CreateBuilder(args);

var maildev = builder.AddMailDev("maildev");

builder.AddProject<Projects.MailDevResource_NewsletterService>("newsletterservice")
       .WithReference(maildev);

builder.Build().Run();

Nadat u het Program.cs-bestand hebt bijgewerkt, start u de app-host opnieuw. Controleer vervolgens of de nieuwsbriefservice is gestart en of de omgevingsvariabele ConnectionStrings__maildev is toegevoegd aan het proces. Ga op de pagina Resources naar de rij newsletterservice en selecteer de koppeling weergeven in de kolom Details:

In de voorgaande schermopname ziet u de omgevingsvariabelen voor het newsletterservice project. De ConnectionStrings__maildev omgevingsvariabele is de verbindingsreeks die door de maildev resource in het project is geïnjecteerd.

Verbindingsreeks gebruiken om berichten te verzenden

Als u de SMTP-verbindingsgegevens wilt gebruiken die zijn geïnjecteerd in het nieuwsbriefserviceproject, injecteert u een exemplaar van SmtpClient in de container voor afhankelijkheidsinjectie als een singleton. Voeg de volgende code toe aan het Program.cs-bestand in het MailDevResource.NewsletterService project om de singleton-service in te stellen. Voeg in de klasse Program direct na de opmerking // Add services to the container de volgende code toe:

builder.Services.AddSingleton<SmtpClient>(sp =>
{
    var smtpUri = new Uri(builder.Configuration.GetConnectionString("maildev")!);

    var smtpClient = new SmtpClient(smtpUri.Host, smtpUri.Port);

    return smtpClient;
});

Tip

Dit codefragment is echter afhankelijk van de officiële SmtpClient; dit type is verouderd op sommige platforms en wordt niet aanbevolen op andere platforms. Voor een modernere aanpak met gebruik van MailKit, zie "Aangepaste .NET.NET Aspire clientintegraties maken".

Als u de client wilt testen, voegt u twee eenvoudige subscribe en unsubscribe POST-methoden toe aan de nieuwsbriefservice. Voeg de volgende code toe ter vervanging van de MapGet-aanroep in het bestand Program.cs van het project MailDevResource.NewsletterService om de ASP.NET Core routes in te stellen.

app.MapPost("/subscribe", async (SmtpClient smtpClient, string email) =>
{
    using var message = new MailMessage("newsletter@yourcompany.com", email)
    {
        Subject = "Welcome to our newsletter!",
        Body = "Thank you for subscribing to our newsletter!"
    };

    await smtpClient.SendMailAsync(message);
});

app.MapPost("/unsubscribe", async (SmtpClient smtpClient, string email) =>
{
    using var message = new MailMessage("newsletter@yourcompany.com", email)
    {
        Subject = "You are unsubscribed from our newsletter!",
        Body = "Sorry to see you go. We hope you will come back soon!"
    };

    await smtpClient.SendMailAsync(message);
});

Tip

Vergeet niet om te verwijzen naar de System.Net.Mail en Microsoft.AspNetCore.Mvc naamruimten in Program.cs als uw code-editor deze niet automatisch toevoegt.

Nadat het Program.cs-bestand is bijgewerkt, start u de app-host en gebruikt u uw browser of curl om de volgende URL's te bereiken (als u Visual Studio gebruikt, kunt u .http bestanden gebruiken):

POST /subscribe?email=test@test.com HTTP/1.1
Host: localhost:7251
Content-Type: application/json

Als u deze API wilt gebruiken, kunt u curl gebruiken om de aanvraag te verzenden. Met de volgende curl opdracht wordt een HTTP-POST-aanvraag naar het subscribe-eindpunt verzonden. Er wordt een email querytekenreekswaarde verwacht om u te abonneren op de nieuwsbrief. De Content-Type header is ingesteld op application/json om aan te geven dat de hoofdtekst van de aanvraag zich in JSON indeling bevindt.:

Unix
Windows

curl -H "Content-Type: application/json" --request POST https://localhost:7251/subscribe?email=test@test.com

curl -H @{ ContentType = "application/json" } -Method POST https://localhost:7251/subscribe?email=test@test.com

De volgende API is het unsubscribe-eindpunt. Dit eindpunt wordt gebruikt om u af te melden voor de nieuwsbrief.

POST /unsubscribe?email=test@test.com HTTP/1.1
Host: localhost:7251
Content-Type: application/json

Als u zich wilt afmelden voor de nieuwsbrief, kunt u de volgende curl opdracht gebruiken om een email parameter door te geven aan het unsubscribe-eindpunt als een querytekenreeks:

Unix
Windows

curl -H "Content-Type: application/json" --request POST https://localhost:7251/unsubscribe?email=test@test.com

curl -H @{ ContentType = "application/json" } -Method POST https://localhost:7251/unsubscribe?email=test@test.com

Tip

Zorg ervoor dat u https://localhost:7251 vervangt door de juiste poort localhost (de URL van de server waarop u de toepassing uitvoert).

Als deze API-aanroepen een geslaagd antwoord retourneren (HTTP 200, OK), moet u op de maildev resource het dashboard kunnen selecteren en de MailDev UI de e-mailberichten weergeven die naar het SMTP-eindpunt zijn verzonden.

Technische details

In de volgende secties worden verschillende technische details besproken die belangrijk zijn om te begrijpen bij het ontwikkelen van aangepaste resources voor .NET.NET Aspire.

Beveiligde netwerken

In dit voorbeeld is de MailDev-resource een containerresource die via HTTP en SMTP beschikbaar wordt gemaakt voor de hostcomputer. De MailDev resource is een ontwikkelhulpprogramma en is niet bedoeld voor productiegebruik. Als u in plaats daarvan HTTPS wilt gebruiken, raadpleegt u MailDev: HTTPS-configureren.

Bij het ontwikkelen van aangepaste resources die netwerkeindpunten beschikbaar maken, is het belangrijk om rekening te houden met de beveiligingsproblemen van de resource. Als de resource bijvoorbeeld een database is, is het belangrijk om ervoor te zorgen dat de database veilig is en dat de verbindingsreeks niet zichtbaar is voor het openbare internet.

Het type `ReferenceExpression` en `EndpointReference`

In de voorgaande code had de MailDevResource twee eigenschappen:

SmtpEndpoint: EndpointReference type.
ConnectionStringExpression: ReferenceExpression type.

Deze typen zijn een van de verschillende typen die in .NET Aspire worden gebruikt om configuratiegegevens weer te geven, die pas zijn voltooid als het .NET Aspire project wordt uitgevoerd of gepubliceerd naar de cloud via een hulpprogramma zoals Azure Developer CLI (azd).

Het fundamentele probleem dat deze typen helpen om op te lossen, is het uitstellen van de oplossing van concrete configuratiegegevens totdat alle de informatie beschikbaar is.

Met de MailDevResource wordt bijvoorbeeld een eigenschap met de naam ConnectionStringExpression weergegeven, zoals vereist door de IResourceWithConnectionString-interface. Het type van de eigenschap is ReferenceExpression en wordt gemaakt door een geïnterpoleerde tekenreeks door te geven aan de Create-methode.

public ReferenceExpression ConnectionStringExpression =>
    ReferenceExpression.Create(
        $"smtp://{SmtpEndpoint.Property(EndpointProperty.Host)}:{SmtpEndpoint.Property(EndpointProperty.Port)}"
    );

De handtekening voor de methode Create is als volgt:

public static ReferenceExpression Create(
    in ExpressionInterpolatedStringHandler handler)

Dit is geen gewoon String argument. De methode maakt gebruik van het geïnterpoleerde tekenreekshandlerpatroon, om de geïnterpoleerde tekenreekssjabloon en de waarden waarnaar erin wordt verwezen vast te leggen om aangepaste verwerking mogelijk te maken. In het geval van .NET.NET Aspireworden deze details vastgelegd in een ReferenceExpression die kan worden geëvalueerd als elke waarde waarnaar in de geïnterpoleerde tekenreeks wordt verwezen, beschikbaar wordt.

Hier ziet u hoe de uitvoeringsstroom werkt:

Een resource die IResourceWithConnectionString implementeert, wordt toegevoegd aan het model (bijvoorbeeld AddMailDev(...)).
De IResourceBuilder<MailDevResource> wordt doorgegeven aan de WithReference die een speciale overload heeft voor het afhandelen van IResourceWithConnectionString implementaties.
De WithReference verpakt de hulpbron in een ConnectionStringReference instantie en het object wordt opgevangen in een EnvironmentCallbackAnnotation, die wordt geëvalueerd nadat het .NET.NET Aspire project is gebouwd en gestart.
Wanneer het proces dat verwijst naar de verbindingsreeks begint .NET.NET Aspire begint met het evalueren van de expressie. Het krijgt eerst de ConnectionStringReference en roept IValueProvider.GetValueAsync.
Met de methode GetValueAsync wordt de waarde van de eigenschap ConnectionStringExpression opgehaald om het ReferenceExpression exemplaar op te halen.
De methode IValueProvider.GetValueAsync roept vervolgens GetValueAsync aan om de eerder vastgelegde geïnterpoleerde tekenreeks te verwerken.
Omdat de geïnterpoleerde tekenreeks verwijzingen bevat naar andere referentietypen, zoals EndpointReference, worden deze ook geëvalueerd en vervangen door de echte waarden (die op dit moment beschikbaar zijn).

Publicatie van manifest

De IManifestExpressionProvider-interface is ontworpen om het probleem van het delen van verbindingsgegevens tussen resources bij de implementatie op te lossen. De oplossing voor dit specifieke probleem wordt beschreven in het .NET.NET Aspire overzicht van interne-lusnetwerken. Net als bij lokale ontwikkeling zijn veel van de waarden nodig om de app te configureren, maar ze kunnen pas worden bepaald wanneer de app wordt geïmplementeerd via een hulpprogramma, zoals azd (Azure Developer CLI).

Om dit probleem op te lossen, produceert .NET.NET Aspire een manifestbestand dat azd en andere implementatiehulpprogramma's interpreteren. In plaats van concrete waarden op te geven voor verbindingsgegevens tussen resources wordt een expressiesyntaxis gebruikt die implementatiehulpprogramma's evalueren. Over het algemeen is het manifestbestand niet zichtbaar voor ontwikkelaars, maar het is mogelijk om er een te genereren voor handmatige inspectie. De onderstaande opdracht kan worden gebruikt op de app-host om een manifest te produceren.

dotnet run --project MailDevResource.AppHost/MailDevResource.AppHost.csproj -- --publisher manifest --output-path aspire-manifest.json

Met deze opdracht wordt een manifestbestand geproduceerd dat er als volgt uitziet:

{
  "resources": {
    "maildev": {
      "type": "container.v0",
      "connectionString": "smtp://{maildev.bindings.smtp.host}:{maildev.bindings.smtp.port}",
      "image": "docker.io/maildev/maildev:2.1.0",
      "bindings": {
        "http": {
          "scheme": "http",
          "protocol": "tcp",
          "transport": "http",
          "targetPort": 1080
        },
        "smtp": {
          "scheme": "tcp",
          "protocol": "tcp",
          "transport": "tcp",
          "targetPort": 1025
        }
      }
    },
    "newsletterservice": {
      "type": "project.v0",
      "path": "../MailDevResource.NewsletterService/MailDevResource.NewsletterService.csproj",
      "env": {
        "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",
        "ConnectionStrings__maildev": "{maildev.connectionString}"
      },
      "bindings": {
        "http": {
          "scheme": "http",
          "protocol": "tcp",
          "transport": "http"
        },
        "https": {
          "scheme": "https",
          "protocol": "tcp",
          "transport": "http"
        }
      }
    }
  }
}

Omdat de MailDevResource implementeert IResourceWithConnectionString de manifestpublicatielogica in .NET.NET Aspire weet dat MailDevResource een containerresource is, maar ook een connectionString veld nodig heeft. Het connectionString veld verwijst naar andere onderdelen van de maildev-resource in het manifest om de uiteindelijke tekenreeks te produceren:

{
    // ... other content omitted.
    "connectionString": "smtp://{maildev.bindings.smtp.host}:{maildev.bindings.smtp.port}"
}

.NET .NET Aspire weet hoe deze tekenreeks moet worden gemaakt, omdat deze naar ConnectionStringExpression kijkt en de uiteindelijke tekenreeks samenbouwt via de IManifestExpressionProvider interface (op ongeveer dezelfde manier als de IValueProvider interface wordt gebruikt).

De MailDevResource wordt automatisch opgenomen in het manifest omdat deze is afgeleid van ContainerResource. Resourceauteurs kunnen ervoor kiezen om het genereren van inhoud naar het manifest te onderdrukken met behulp van de ExcludeFromManifest-extensiemethode op de resourcebouwer.

public static IResourceBuilder<MailDevResource> AddMailDev(
    this IDistributedApplicationBuilder builder, 
    string name,
    int? httpPort = null,
    int? smtpPort = null)
{
    var resource = new MailDevResource(name);

    return builder.AddResource(resource)
                  .WithImage(MailDevContainerImageTags.Image)
                  .WithImageRegistry(MailDevContainerImageTags.Registry)
                  .WithImageTag(MailDevContainerImageTags.Tag)
                  .WithHttpEndpoint(
                      targetPort: 1080,
                      port: httpPort,
                      name: MailDevResource.HttpEndpointName)
                  .WithEndpoint(
                      targetPort: 1025,
                      port: smtpPort,
                      name: MailDevResource.SmtpEndpointName)
                  .ExcludeFromManifest(); // This line was added
}

Er moet zorgvuldig worden overwogen of de resource aanwezig moet zijn in het manifest of dat deze moet worden onderdrukt. Als de resource wordt toegevoegd aan het manifest, moet deze zodanig worden geconfigureerd dat deze veilig en veilig is voor gebruik.

Samenvatting

In de zelfstudie over aangepaste resources hebt u geleerd hoe u een aangepaste .NET Aspire resource maakt die gebruikmaakt van een bestaande containertoepassing (MailDev). Vervolgens hebt u dit gebruikt om de lokale ontwikkelervaring te verbeteren door het eenvoudig te maken om e-mailmogelijkheden te testen die in een app kunnen worden gebruikt. Deze lessen kunnen worden toegepast op het bouwen van andere aangepaste resources die kunnen worden gebruikt in op .NET.NET Aspiregebaseerde toepassingen. In dit specifieke voorbeeld zijn geen aangepaste integraties opgenomen, maar het is mogelijk om aangepaste integraties uit te bouwen, zodat ontwikkelaars de resource gemakkelijker kunnen gebruiken. In dit scenario kon u vertrouwen op de bestaande SmtpClient-klasse in het .NET-platform om e-mailberichten te verzenden.

Volgende stappen

Aangepaste .NET.NET Aspire klant-integraties maken

Delen via

Aangepaste .NET.NET Aspire hostingintegraties maken

Belangrijke elementen van een .NET.NET Aspire aangepaste resource

Een praktisch voorbeeld: MailDev

Het startersproject instellen

Bibliotheek maken voor middelenextensie

De resourcetypen definiëren

De resource-extensies definiëren

Aangepaste integratie valideren in de app-host

Een .NET-serviceproject toevoegen aan de app-host voor testen

Verbindingsreeks gebruiken om berichten te verzenden

Technische details

Beveiligde netwerken

Het type `ReferenceExpression` en `EndpointReference`

Publicatie van manifest

Samenvatting

Volgende stappen

Aanvullende resources

Delen via

Aangepaste .NET.NET Aspire hostingintegraties maken

Belangrijke elementen van een .NET.NET Aspire aangepaste resource

Een praktisch voorbeeld: MailDev

Het startersproject instellen

Bibliotheek maken voor middelenextensie

De resourcetypen definiëren

De resource-extensies definiëren

Aangepaste integratie valideren in de app-host

Een .NET-serviceproject toevoegen aan de app-host voor testen

Verbindingsreeks gebruiken om berichten te verzenden

Technische details

Beveiligde netwerken

Het type ReferenceExpression en EndpointReference

Publicatie van manifest

Samenvatting

Volgende stappen

Aanvullende resources

Het type `ReferenceExpression` en `EndpointReference`