Aangepaste Aspire clientintegraties maken

Dit artikel is een vervolg van het artikel Aangepaste Aspire hostingintegraties maken . Het begeleidt u bij het maken van een Aspire clientintegratie die MailKit gebruikt om e-mailberichten te verzenden. Deze integratie wordt vervolgens toegevoegd aan de nieuwsbrief-app die u eerder hebt gemaakt. In het vorige voorbeeld is het maken van een clientintegratie weggelaten en is in plaats daarvan afhankelijk van de bestaande .NETSmtpClient. Het is het beste om de SmtpClient van MailKit te gebruiken via de officiële .NETSmtpClient voor het verzenden van e-mailberichten, omdat het moderner is en meer functies/protocollen ondersteunt. Zie voor meer informatie .NET SmtpClient: Opmerkingen.

Voorwaarden

Als u alles stap voor stap volgt, moet u een Nieuwsbrief-app hebben uit de stappen in het artikel Aangepaste Aspire hostingintegratie maken.

Bibliotheek maken voor integratie

Aspire integraties worden geleverd als NuGet-pakketten, maar in dit voorbeeld valt het buiten het bereik van dit artikel om een NuGet-pakket te publiceren. In plaats daarvan maakt u een klassebibliotheekproject met de integratie en verwijst u ernaar als een project. Aspire integratiepakketten zijn bedoeld voor het verpakken van een clientbibliotheek, zoals MailKit, en bieden productieklare telemetrie, statuscontroles, configureerbaarheid en testbaarheid. Laten we beginnen met het maken van een nieuw klassebibliotheekproject.

1. Maak een nieuw klassebibliotheekproject met de naam MailKit.Client in dezelfde map als de MailDevResource.sln uit het vorige artikel.

   dotnet new classlib -o MailKit.Client
   

2. Voeg het project toe aan de oplossing.

   dotnet sln ./MailDevResource.sln add MailKit.Client/MailKit.Client.csproj
   

De volgende stap bestaat uit het toevoegen van alle NuGet-pakketten waarvoor de integratie afhankelijk is. In plaats van dat u elk pakket een voor een toevoegt vanuit de .NET CLI, is het waarschijnlijk eenvoudiger om de volgende XML te kopiëren en in de MailKit te plakken.Client.csproj-bestand.

<ItemGroup>
  <PackageReference Include="MailKit" Version="4.14.1" />
  <PackageReference Include="Microsoft.Extensions.Configuration.Binder" Version="9.0.10" />
  <PackageReference Include="Microsoft.Extensions.Resilience" Version="9.10.0" />
  <PackageReference Include="Microsoft.Extensions.Hosting.Abstractions" Version="9.0.10" />
  <PackageReference Include="Microsoft.Extensions.Diagnostics.HealthChecks" Version="9.0.10" />
  <PackageReference Include="OpenTelemetry.Extensions.Hosting" Version="1.13.1" />
</ItemGroup>

Integratie-instellingen definiëren

Wanneer u een Aspire integratie maakt, is het raadzaam om inzicht te hebben in de clientbibliotheek waaraan u bent toegewezen. Met MailKit moet u de configuratie-instellingen begrijpen die nodig zijn om verbinding te maken met een SMTP-server (Simple Mail Transfer Protocol). Maar het is ook belangrijk om te begrijpen of de bibliotheek ondersteuning heeft voor statuscontroles, tracering en metrieken. MailKit ondersteunt tracering en metrische gegevens, via zijn Telemetry.SmtpClient class. Wanneer u gezondheidscontrolestoevoegt, moet u waar mogelijk bestaande gezondheidscontroles gebruiken. Anders kunt u overwegen uw eigen oplossing te implementeren in de integratie. Voeg de volgende code toe aan het MailKit.Client project in een bestand met de naam MailKitClientSettings.cs:

using System.Data.Common;

namespace MailKit.Client;

/// <summary>
/// Provides the client configuration settings for connecting MailKit to an SMTP server.
/// </summary>
public sealed class MailKitClientSettings
{
    internal const string DefaultConfigSectionName = "MailKit:Client";

    /// <summary>
    /// Gets or sets the SMTP server <see cref="Uri"/>.
    /// </summary>
    /// <value>
    /// The default value is <see langword="null"/>.
    /// </value>
    public Uri? Endpoint { get; set; }

    /// <summary>
    /// Gets or sets a boolean value that indicates whether the database health check is disabled or not.
    /// </summary>
    /// <value>
    /// The default value is <see langword="false"/>.
    /// </value>
    public bool DisableHealthChecks { get; set; }

    /// <summary>
    /// Gets or sets a boolean value that indicates whether the OpenTelemetry tracing is disabled or not.
    /// </summary>
    /// <value>
    /// The default value is <see langword="false"/>.
    /// </value>
    public bool DisableTracing { get; set; }

    /// <summary>
    /// Gets or sets a boolean value that indicates whether the OpenTelemetry metrics are disabled or not.
    /// </summary>
    /// <value>
    /// The default value is <see langword="false"/>.
    /// </value>
    public bool DisableMetrics { get; set; }

    internal void ParseConnectionString(string? connectionString)
    {
        if (string.IsNullOrWhiteSpace(connectionString))
        {
            throw new InvalidOperationException($"""
                    ConnectionString is missing.
                    It should be provided in 'ConnectionStrings:<connectionName>'
                    or '{DefaultConfigSectionName}:Endpoint' key.'
                    configuration section.
                    """);
        }

        if (Uri.TryCreate(connectionString, UriKind.Absolute, out var uri))
        {
            Endpoint = uri;
        }
        else
        {
            var builder = new DbConnectionStringBuilder
            {
                ConnectionString = connectionString
            };
            
            if (builder.TryGetValue("Endpoint", out var endpoint) is false)
            {
                throw new InvalidOperationException($"""
                        The 'ConnectionStrings:<connectionName>' (or 'Endpoint' key in
                        '{DefaultConfigSectionName}') is missing.
                        """);
            }

            if (Uri.TryCreate(endpoint.ToString(), UriKind.Absolute, out uri) is false)
            {
                throw new InvalidOperationException($"""
                        The 'ConnectionStrings:<connectionName>' (or 'Endpoint' key in
                        '{DefaultConfigSectionName}') isn't a valid URI.
                        """);
            }

            Endpoint = uri;
        }
    }
}

De voorgaande code definieert de MailKitClientSettings-klasse met:

• Endpoint eigenschap die de verbindingsreeks aangeeft aan de SMTP-server.
• DisableHealthChecks eigenschap die bepaalt of gezondheidscontroles zijn ingeschakeld.
• DisableTracing eigenschap die bepaalt of tracering is ingeschakeld.
• DisableMetrics eigenschap die bepaalt of metrische gegevens zijn ingeschakeld.

Het verwerken van verbindingsreekslogica

De instellingenklasse bevat ook een ParseConnectionString methode waarmee de verbindingsreeks wordt geparseerd in een geldige Uri. De configuratie wordt naar verwachting in de volgende indeling opgegeven:

• ConnectionStrings:<connectionName>: de verbindingsreeks met de SMTP-server.
• MailKit:Client:ConnectionString: de verbindingsreeks met de SMTP-server.

Als geen van deze waarden wordt opgegeven, wordt er een uitzondering gegenereerd.

Clientfunctionaliteit beschikbaar maken

Het doel van Aspire integraties is om de onderliggende clientbibliotheek beschikbaar te maken voor consumenten via afhankelijkheidsinjectie. Met MailKit en voor dit voorbeeld is de SmtpClient klasse wat u beschikbaar wilt maken. U verpakt geen functionaliteit, maar wijst configuratie-instellingen toe aan een SmtpClient-klasse. Het is gebruikelijk om zowel standaard- als keyed-serviceregistraties beschikbaar te maken voor integraties. Standaardregistraties worden gebruikt wanneer er slechts één exemplaar van een service is en sleutelserviceregistraties worden gebruikt wanneer er meerdere exemplaren van een service zijn. Soms gebruikt u een fabriekspatroon om meerdere registraties van hetzelfde type te bereiken. Voeg de volgende code toe aan het MailKit.Client project in een bestand met de naam MailKitClientFactory.cs:

using MailKit.Net.Smtp;

namespace MailKit.Client;

/// <summary>
/// A factory for creating <see cref="ISmtpClient"/> instances
/// given a <paramref name="smtpUri"/> (and optional <paramref name="credentials"/>).
/// </summary>
/// <param name="settings">
/// The <see cref="MailKitClientSettings"/> settings for the SMTP server
/// </param>
public sealed class MailKitClientFactory(MailKitClientSettings settings) : IDisposable
{

    /// <summary>
    /// Gets an <see cref="ISmtpClient"/> instance in the connected state
    /// (and that's been authenticated if configured).
    /// </summary>
    /// <param name="cancellationToken">Used to abort client creation and connection.</param>
    /// <returns>A connected (and authenticated) <see cref="ISmtpClient"/> instance.</returns>
    /// <remarks>
    /// Since both the connection and authentication are considered expensive operations,
    /// the <see cref="ISmtpClient"/> returned is intended to be used for the duration of a request
    /// (registered as 'Scoped') and is automatically disposed of.
    /// </remarks>
    public async Task<ISmtpClient> GetSmtpClientAsync(
        CancellationToken cancellationToken = default)
    {
        var client = new SmtpClient();
        try
        {
            if (settings.Endpoint is not null)
            {
                await client.ConnectAsync(settings.Endpoint, cancellationToken)
                             .ConfigureAwait(false);
            }
            return client;
        }
        catch
        {
            await client.DisconnectAsync(true, cancellationToken)
            client.Dispose();
            throw;
        }       
    }
}

De MailKitClientFactory-klasse is een fabriek die een ISmtpClient exemplaar maakt op basis van de configuratie-instellingen. Het is verantwoordelijk voor het retourneren van een ISmtpClient-implementatie die een actieve verbinding heeft met een geconfigureerde SMTP-server. Vervolgens moet u de functionaliteit voor gebruikers beschikbaar maken om deze fabriek te registreren in de container voor afhankelijkheidsinjectie. Voeg de volgende code toe aan het MailKit.Client project in een bestand met de naam MailKitExtensions.cs:

using MailKit;
using MailKit.Client;
using MailKit.Net.Smtp;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;

namespace Microsoft.Extensions.Hosting;

/// <summary>
/// Provides extension methods for registering a <see cref="SmtpClient"/> as a
/// scoped-lifetime service in the services provided by the <see cref="IHostApplicationBuilder"/>.
/// </summary>
public static class MailKitExtensions
{
    /// <summary>
    /// Registers 'Scoped' <see cref="MailKitClientFactory" /> for creating
    /// connected <see cref="SmtpClient"/> instance for sending emails.
    /// </summary>
    /// <param name="builder">
    /// The <see cref="IHostApplicationBuilder" /> to read config from and add services to.
    /// </param>
    /// <param name="connectionName">
    /// A name used to retrieve the connection string from the ConnectionStrings configuration section.
    /// </param>
    /// <param name="configureSettings">
    /// An optional delegate that can be used for customizing options.
    /// It's invoked after the settings are read from the configuration.
    /// </param>
    public static void AddMailKitClient(
        this IHostApplicationBuilder builder,
        string connectionName,
        Action<MailKitClientSettings>? configureSettings = null) =>
        AddMailKitClient(
            builder,
            MailKitClientSettings.DefaultConfigSectionName,
            configureSettings,
            connectionName,
            serviceKey: null);

    /// <summary>
    /// Registers 'Scoped' <see cref="MailKitClientFactory" /> for creating
    /// connected <see cref="SmtpClient"/> instance for sending emails.
    /// </summary>
    /// <param name="builder">
    /// The <see cref="IHostApplicationBuilder" /> to read config from and add services to.
    /// </param>
    /// <param name="name">
    /// The name of the component, which is used as the <see cref="ServiceDescriptor.ServiceKey"/> of the
    /// service and also to retrieve the connection string from the ConnectionStrings configuration section.
    /// </param>
    /// <param name="configureSettings">
    /// An optional method that can be used for customizing options. It's invoked after the settings are
    /// read from the configuration.
    /// </param>
    public static void AddKeyedMailKitClient(
        this IHostApplicationBuilder builder,
        string name,
        Action<MailKitClientSettings>? configureSettings = null)
    {
        ArgumentNullException.ThrowIfNull(name);

        AddMailKitClient(
            builder,
            $"{MailKitClientSettings.DefaultConfigSectionName}:{name}",
            configureSettings,
            connectionName: name,
            serviceKey: name);
    }

    private static void AddMailKitClient(
        this IHostApplicationBuilder builder,
        string configurationSectionName,
        Action<MailKitClientSettings>? configureSettings,
        string connectionName,
        object? serviceKey)
    {
        ArgumentNullException.ThrowIfNull(builder);

        var settings = new MailKitClientSettings();

        builder.Configuration
               .GetSection(configurationSectionName)
               .Bind(settings);

        if (builder.Configuration.GetConnectionString(connectionName) is string connectionString)
        {
            settings.ParseConnectionString(connectionString);
        }

        configureSettings?.Invoke(settings);

        if (serviceKey is null)
        {
            builder.Services.AddScoped(CreateMailKitClientFactory);
        }
        else
        {
            builder.Services.AddKeyedScoped(serviceKey, (sp, key) => CreateMailKitClientFactory(sp));
        }

        MailKitClientFactory CreateMailKitClientFactory(IServiceProvider _)
        {
            return new MailKitClientFactory(settings);
        }

        if (settings.DisableHealthChecks is false)
        {
            builder.Services.AddHealthChecks()
                .AddCheck<MailKitHealthCheck>(
                    name: serviceKey is null ? "MailKit" : $"MailKit_{connectionName}",
                    failureStatus: default,
                    tags: []);
        }

        if (settings.DisableTracing is false)
        {
            builder.Services.AddOpenTelemetry()
                .WithTracing(
                    traceBuilder => traceBuilder.AddSource(
                        Telemetry.SmtpClient.ActivitySourceName));
        }

        if (settings.DisableMetrics is false)
        {
            // Required by MailKit to enable metrics
            Telemetry.SmtpClient.Configure();

            builder.Services.AddOpenTelemetry()
                .WithMetrics(
                    metricsBuilder => metricsBuilder.AddMeter(
                        Telemetry.SmtpClient.MeterName));
        }
    }
}

Met de voorgaande code worden twee uitbreidingsmethoden toegevoegd aan het IHostApplicationBuilder type, één voor de standaardregistratie van MailKit en een andere voor sleutelregistratie van MailKit.

Beide extensies zijn uiteindelijk afhankelijk van de private methode AddMailKitClient om MailKitClientFactory te registreren bij de afhankelijkheidsinjectiecontainer als een gescoapte service. De reden voor het registreren van de MailKitClientFactory als een scoped service is dat de verbindingsbewerkingen als duur worden beschouwd en waar mogelijk opnieuw moeten worden gebruikt binnen hetzelfde bereik. Met andere woorden, voor één aanvraag moet dezelfde ISmtpClient instantie worden gebruikt. De fabriek bewaart het exemplaar van de SmtpClient dat het creëert en verwijdert het vervolgens.

Configuratie-koppeling

Een van de eerste dingen die de privé-implementatie van de AddMailKitClient methoden doet, is het verbinden van de configuratie-instellingen aan de MailKitClientSettings-klasse. De instellingenklasse wordt geïnstantieerd en vervolgens Bind wordt aangeroepen met de specifieke sectie van de configuratie. Vervolgens wordt de optionele configureSettings gemachtigde aangeroepen met de huidige instellingen. Hierdoor kan de consument de instellingen verder configureren, waarbij wordt gewaarborgd dat handmatige code-instellingen voorrang krijgen boven configuratie-instellingen. Afhankelijk van of de serviceKey waarde is opgegeven, moet de MailKitClientFactory worden geregistreerd bij de container voor afhankelijkheidsinjectie als een standaardservice of een gekeyede service.

De registratie van statuscontroles en telemetrie wordt in de volgende secties nader beschreven.

Statuscontroles toevoegen

Gezondheidscontroles zijn een manier om de gezondheid van een integratie te monitoren. Met MailKit kunt u controleren of de verbinding met de SMTP-server in orde is. Voeg de volgende code toe aan het MailKit.Client project in een bestand met de naam MailKitHealthCheck.cs:

using Microsoft.Extensions.Diagnostics.HealthChecks;

namespace MailKit.Client;

internal sealed class MailKitHealthCheck(MailKitClientFactory factory) : IHealthCheck
{
    public async Task<HealthCheckResult> CheckHealthAsync(
        HealthCheckContext context,
        CancellationToken cancellationToken = default)
    {
        try
        {
            // The factory connects (and authenticates).
            _ = await factory.GetSmtpClientAsync(cancellationToken);

            return HealthCheckResult.Healthy();
        }
        catch (Exception ex)
        {
            return HealthCheckResult.Unhealthy(exception: ex);
        }
    }
}

De voorgaande implementatie van de statuscontrole:

• Implementeert de IHealthCheck-interface.
• Accepteert de MailKitClientFactory als een primaire constructorparameter.
• Voldoet aan de CheckHealthAsync methode door:
  • Er wordt geprobeerd een exemplaar van ISmtpClient uit de factory op te halen. Als dit lukt, wordt HealthCheckResult.Healthy geretourneerd.
  • Als er een uitzondering optreedt, wordt HealthCheckResult.Unhealthygeretourneerd.

Zoals eerder gedeeld in de registratie van de MailKitClientFactory, wordt de MailKitHealthCheck voorwaardelijk geregistreerd bij de IHeathChecksBuilder:

if (settings.DisableHealthChecks is false)
{
    builder.Services.AddHealthChecks()
        .AddCheck<MailKitHealthCheck>(
            name: serviceKey is null ? "MailKit" : $"MailKit_{connectionName}",
            failureStatus: default,
            tags: []);
}

De consument kan ervoor kiezen om statuscontroles weg te laten door de eigenschap DisableHealthChecks in te stellen op true in de configuratie. Een gemeenschappelijk patroon voor integraties is om optionele functies en Aspire integraties te hebben die deze typen configuraties sterk aanmoedigt. Zie AspireASP.NET Core HealthChecksUI-voorbeeldvoor meer informatie over statuscontroles en een werkend voorbeeld met een gebruikersinterface.

Telemetrie aansluiten

Als best practice maakt de MailKit-clientbibliotheek telemetriegegevens beschikbaar. Aspire kan profiteren van deze telemetrie en deze weergeven in het Aspire dashboard. Afhankelijk van of tracering en metrische gegevens zijn ingeschakeld, wordt telemetrie bekabeld, zoals wordt weergegeven in het volgende codefragment:

if (settings.DisableTracing is false)
{
    builder.Services.AddOpenTelemetry()
        .WithTracing(
            traceBuilder => traceBuilder.AddSource(
                Telemetry.SmtpClient.ActivitySourceName));
}

if (settings.DisableMetrics is false)
{
    // Required by MailKit to enable metrics
    Telemetry.SmtpClient.Configure();

    builder.Services.AddOpenTelemetry()
        .WithMetrics(
            metricsBuilder => metricsBuilder.AddMeter(
                Telemetry.SmtpClient.MeterName));
}

De nieuwsbriefservice bijwerken

Nu de integratiebibliotheek is gemaakt, kunt u de nieuwsbriefservice bijwerken om de MailKit-client te gebruiken. De eerste stap is het toevoegen van een verwijzing naar het MailKit.Client project. Voeg de MailKitClient.csproj projectreferentie toe aan het MailDevResource.NewsletterService project.

dotnet add ./MailDevResource.NewsletterService/MailDevResource.NewsletterService.csproj reference MailKit.Client/MailKit.Client.csproj

Voeg vervolgens een verwijzing toe naar het ServiceDefaults project:

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

De laatste stap is het vervangen van het bestaande Program.cs-bestand in het MailDevResource.NewsletterService project door de volgende C#-code:

using System.Net.Mail;
using MailKit.Client;
using MailKit.Net.Smtp;
using MimeKit;

var builder = WebApplication.CreateBuilder(args);

builder.AddServiceDefaults();

builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

// Add services to the container.
builder.AddMailKitClient("maildev");

var app = builder.Build();

app.MapDefaultEndpoints();

// Configure the HTTP request pipeline.

app.UseSwagger();
app.UseSwaggerUI();
app.UseHttpsRedirection();

app.MapPost("/subscribe",
    async (MailKitClientFactory factory, string email) =>
{
    ISmtpClient client = await factory.GetSmtpClientAsync();

    using var message = new MailMessage("newsletter@yourcompany.com", email)
    {
        Subject = "Welcome to our newsletter!",
        Body = "Thank you for subscribing to our newsletter!"
    };

    await client.SendAsync(MimeMessage.CreateFromMailMessage(message));
});

app.MapPost("/unsubscribe",
    async (MailKitClientFactory factory, string email) =>
{
    ISmtpClient client = await factory.GetSmtpClientAsync();

    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 client.SendAsync(MimeMessage.CreateFromMailMessage(message));
});

app.Run();

De meest opvallende wijzigingen in de voorgaande code zijn:

• De bijgewerkte using-instructies die de MailKit.Client, MailKit.Net.Smtpen MimeKit naamruimten bevatten.
• De vervanging van de registratie voor de officiële .NETSmtpClient door de aanroep van de uitbreidingsmethode AddMailKitClient.
• De vervanging van zowel /subscribe als /unsubscribe map-postaanroepen om in plaats daarvan de MailKitClientFactory te injecteren en de ISmtpClient-instantie te gebruiken om de e-mail te verzenden.

Het voorbeeld uitvoeren

Nu u de MailKit-clientintegratie hebt gemaakt en de nieuwsbriefservice hebt bijgewerkt om deze te gebruiken, kunt u het voorbeeld uitvoeren. Selecteer in uw IDE F5 of voer deze uit dotnet run vanuit de hoofdmap van de oplossing om de toepassing te starten. U ziet het Aspire dashboard:

Zodra de toepassing wordt uitgevoerd, gaat u naar de Swagger-gebruikersinterface op https://localhost:7251/swagger en test u de /subscribe en /unsubscribe eindpunten. Selecteer de pijl-omlaag om het eindpunt uit te vouwen:

Selecteer vervolgens de knop Try it out. Voer een e-mailadres in en selecteer vervolgens de knop Execute.

Herhaal dit meerdere keren om meerdere e-mailadressen toe te voegen. U zou de e-mail moeten zien die naar de MailDev inbox is verzonden.

Stop de toepassing door Ctrl+C- te selecteren in het terminalvenster waarin de toepassing wordt uitgevoerd of door de stopknop in uw IDE te selecteren.

MailKit-telemetrie weergeven

De MailKit-clientbibliotheek toont telemetrie die kan worden weergegeven in het Aspire dashboard. Als u de telemetrie wilt weergeven, gaat u naar het Aspire dashboard op https://localhost:7251. Selecteer de newsletter resource om de telemetrie weer te geven op de pagina Metrische gegevens:

Open de Swagger-gebruikersinterface opnieuw en voer enkele aanvragen uit naar de /subscribe en /unsubscribe eindpunten. Ga vervolgens terug naar het Aspire dashboard en selecteer de newsletter resource. Selecteer een metrische waarde onder het knooppunt mailkit.net.smtp, zoals mailkit.net.smtp.client.operation.count. U ziet nu de telemetrie voor de MailKit-client:

Samenvatting

In dit artikel hebt u geleerd hoe u een Aspire integratie maakt die MailKit gebruikt om e-mailberichten te verzenden. U hebt ook geleerd hoe u deze integratie integreert in de nieuwsbrief-app die u eerder hebt gemaakt. U hebt geleerd over de belangrijkste principes van integraties, zoals het blootstellen van de onderliggende clientbibliotheek aan consumenten via afhankelijkheidsinjectie en het toevoegen van Aspire statuscontroles en telemetrie aan de integratie. U hebt ook geleerd hoe u de nieuwsbriefservice bijwerkt voor het gebruik van de MailKit-client.

Ga verder en bouw je eigen Aspire integraties. Als u denkt dat er voldoende communitywaarde is in de integratie die u bouwt, kunt u overwegen deze te publiceren als een NuGet-pakket dat anderen kunnen gebruiken. Overweeg bovendien om een pull request in te dienen bij de AspireGitHub opslagplaats voor opname in de officiële Aspire integraties.

Volgende stappen