Vytvořte vlastní .NET.NET Aspire integrační hostingy.

Článek
12/13/2024

.NET .NET Aspire zlepšuje vývojové prostředí tím, že poskytuje opakovaně použitelné stavební bloky, které lze použít k rychlému uspořádání závislostí aplikací a jejich zveřejnění vlastnímu kódu. Jedním z klíčových stavebních bloků aplikace založené na Aspireje prostředek . Podívejte se na následující kód:

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

V předchozím kódu jsou zastoupeny čtyři prostředky:

cache: Kontejner Redis.
pgserver: Kontejner Postgres.
inventorydb: Databáze hostovaná v pgserver.
inventoryservice: Aplikace ASP.NET Core.

Většina .NET.NET Aspiresouvisejícího kódu, který průměrný vývojář píše, se zaměřuje na přidávání prostředků do modelu aplikace a vytváření odkazů mezi nimi.

Klíčové prvky uživatelského prostředku .NET.NET Aspire

Vytvoření vlastního prostředku v .NET.NET Aspire vyžaduje následující:

Vlastní typ zdroje, který implementuje IResource
Metoda rozšíření pro IDistributedApplicationBuilder s názvem Add{CustomResource}, kde {CustomResource} je název vlastního prostředku.

Pokud vlastní prostředek vyžaduje volitelnou konfiguraci, mohou vývojáři chtít implementovat metody rozšíření končící příponou With*, aby byly tyto konfigurační možnosti zjistitelné s využitím vzoru tvůrce .

Praktický příklad: MailDev

Abychom pochopili, jak vyvíjet vlastní prostředky, tento článek ukazuje příklad vytvoření vlastního prostředku pro MailDev. MailDev je open-source nástroj, který poskytuje lokální e-mail službu server navrženou tak, aby vývojářům umožnila testovat chování při odesílání e-mailů v jejich aplikaci. Další informace najdete v MailDevGitHub úložišti.

V tomto příkladu vytvoříte nový projekt .NET Aspire jako testovací prostředí pro MailDev prostředek, který vytvoříte. I když můžete vytvářet vlastní prostředky v existujících .NET Aspire projektech, je vhodné zvážit, jestli se vlastní prostředek může používat napříč několika řešeními založenými na .NET Aspirea měl by být vyvinut jako opakovaně použitelná integrace.

Nastavení počátečního projektu

Vytvořte nový projekt .NET.NET Aspire, který se používá k otestování nového prostředku, který vyvíjíme.

dotnet new aspire -o MailDevResource
cd MailDevResource
dir

Po vytvoření projektu by se měl zobrazit seznam obsahující následující položky:

MailDevResource.AppHost: Hostitel aplikace použitý k otestování vlastního prostředku.
MailDevResource.ServiceDefaults: Služba má výchozí nastavení projektu pro využití v projektech spojených se službami.
MailDevResource.sln: Soubor řešení odkazující na oba projekty.

Spuštěním následujícího příkazu ověřte, že se projekt může úspěšně sestavit a spustit:

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

Výstup konzoly by měl vypadat nějak takto:

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.

Výběrem odkazu na řídicí panel v prohlížeči zobrazíte řídicí panel .NET.NET Aspire:

Stisknutím kláves Ctrl+C aplikaci vypnete (kartu prohlížeče můžete zavřít).

Vytvoření knihovny pro rozšíření prostředků

.NET Aspire prostředky jsou pouze třídy a metody obsažené v knihovně tříd, která odkazuje na knihovnu .NET Aspire Hosting (Aspire.Hosting). Umístěním zdroje do samostatného projektu ho můžete snadněji sdílet mezi aplikacemi založenými na .NET.NET Aspirea potenciálně je zabalit a sdílet na NuGetu.

Vytvořte projekt knihovny tříd s názvem MailDev. Hosting.
```
dotnet new classlib -o MailDev.Hosting
```
Přidejte Aspire.Hosting do knihovny tříd jako odkaz na balíček.
```
dotnet add ./MailDev.Hosting/MailDev.Hosting.csproj package Aspire.Hosting --version 9.0.0
```
Důležitý

Verze, kterou zde zadáte, by se měla shodovat s nainstalovanou verzí .NET.NET Aspire úlohy.

Přidejte odkaz na knihovnu tříd do projektu MailDevResource.AppHost.

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

Přidejte do souboru řešení projekt knihovny tříd.

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

Po provedení následujících kroků můžete projekt spustit:

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

Výsledkem je zobrazení upozornění na konzolu:

.\.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]

Důvodem je to, že .NET.NET Aspire zpracovává odkazy na projekt v hostiteli aplikace, jako by se jedná o projekty služeb. Chcete-li sdělit .NET.NET Aspire, že odkaz na projekt by měl být považován za neslužební projekt, upravte odkaz souborů MailDevResource.AppHostMailDevResource.AppHost.csproj na projekt MailDev.Hosting tak, aby byl následující:

<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>

Když teď spustíte hostitele aplikace, v konzole se nezobrazí žádné upozornění.

Definování typů prostředků

MailDev.Hosting knihovna tříd obsahuje typ prostředku a metody rozšíření pro přidání prostředku do hostitele aplikace. Měli byste se nejprve zamyslet nad prostředím, které chcete vývojářům poskytnout při používání vlastního prostředku. V případě tohoto vlastního prostředku byste chtěli, aby vývojáři mohli psát kód takto:

var builder = DistributedApplication.CreateBuilder(args);

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

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

K dosažení tohoto cíle potřebujete vlastní prostředek s názvem MailDevResource, který implementuje IResourceWithConnectionString, aby ho uživatelé mohli použít s rozšířením WithReference k vložení podrobností o připojení pro MailDevserver jako připojovací řetězec.

MailDev je k dispozici jako prostředek kontejneru, takže budete chtít také odvodit ContainerResource, abychom mohli v .NET.NET Aspirevyužívat různá existující rozšíření zaměřená na kontejnery.

Nahraďte obsah souboru Class1.cs v projektu MailDev.Hosting a přejmenujte ho na MailDevResource.cs následujícím kódem:

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

V předchozím vlastním zdroji jsou EndpointReference a ReferenceExpression příklady několika typů, které implementují kolekci rozhraní, například IManifestExpressionProvider, IValueProvidera IValueWithReferences. Další informace o těchto typech a jejich roli v .NET.NET Aspirenajdete v technických podrobnostech.

Definujte rozšíření prostředků

Aby vývojáři mohli snadno používat vlastní prostředek, je potřeba do projektu MailDev.Hosting přidat metodu rozšíření s názvem AddMailDev. Metoda rozšíření AddMailDev zodpovídá za konfiguraci prostředku tak, aby se úspěšně spustil jako kontejner.

Do nového souboru s názvem MailDevResourceBuilderExtensions.cs v projektu MailDev.Hosting přidejte následující kód:

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

Ověření vlastní integrace v hostiteli aplikace

Teď, když je základní struktura vlastního prostředku hotová, je načase ji otestovat v reálném projektu AppHost. Otevřete soubor Program.cs v projektu MailDevResource.AppHost a aktualizujte ho následujícím kódem:

var builder = DistributedApplication.CreateBuilder(args);

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

builder.Build().Run();

Po aktualizaci souboru Program.cs spusťte projekt hostitele aplikace a otevřete řídicí panel:

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

Po chvíli řídicí panel ukazuje, že je spuštěný maildev prostředek a bude k dispozici hypertextový odkaz, který přejde do webové aplikace MailDev, která zobrazuje obsah každého e-mailu, který vaše aplikace odesílá.

řídicí panel .NET.NET Aspire by měl vypadat nějak takto:

webová aplikace MailDev by měla vypadat nějak takto:

Přidání projektu služby .NET do hostitele aplikace pro testování

Jakmile .NET Aspire úspěšně spustí integraci MailDev, je na čase využít informace o připojení pro MailDev v rámci projektu .NET. V .NET.NET Aspire je běžné, že existuje hostingový balíček a jeden nebo více balíčků komponent . Představte si například:

hostingový balíček: Používá se k reprezentaci prostředků v modelu aplikace.
- Aspire.Hosting.Redis
balíčky komponent : Slouží ke konfiguraci a využívání knihoven client.
- Aspire.StackExchange.Redis
- Aspire.StackExchange.Redis.DistributedCaching
- Aspire.StackExchange.Redis.OutputCaching

V případě prostředku MailDev již platforma .NET má protokol SMTP (client) ve formě SmtpClient. V tomto příkladu použijete toto stávající rozhraní API kvůli jednoduchosti, i když jiné typy prostředků můžou těžit z vlastních integračních knihoven, které vývojářům pomůžou.

K otestování kompletního scénáře potřebujete projekt .NET, do kterého můžeme vložit informace o připojení pro prostředek MailDev. Přidání projektu webového rozhraní API:

Vytvořte nový projekt .NET s názvem MailDevResource.NewsletterService.

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

Přidejte odkaz na projekt MailDev.Hosting.

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

Přidejte odkaz na projekt MailDevResource.AppHost.

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

Přidejte nový projekt do souboru řešení.

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

Po přidání projektu a aktualizaci odkazů otevřete Program.cs projektu MailDevResource.AppHost.csproj a aktualizujte zdrojový soubor tak, aby vypadal takto:

var builder = DistributedApplication.CreateBuilder(args);

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

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

builder.Build().Run();

Po aktualizaci souboru Program.cs spusťte hostitele aplikace znovu. Potom ověřte, že služba bulletinu byla spuštěna a zda byla do procesu přidána proměnná prostředí ConnectionStrings__maildev. Na stránce Zdroje najděte newsletterservice řádek a ve sloupci Podrobnosti vyberte odkaz Zobrazit:

Předchozí snímek obrazovky ukazuje proměnné prostředí pro newsletterservice projekt. Proměnná prostředí ConnectionStrings__maildev je připojovací řetězec, který do projektu byl vložen prostřednictvím prostředku maildev.

Odesílání zpráv pomocí připojovacího řetězce

Chcete-li použít podrobnosti o připojení SMTP, které byly vloženy do projektu služby newsletteru, vložíte instanci SmtpClient do kontejneru pro injekci závislostí jako singleton. Do souboru Program.cs v projektu MailDevResource.NewsletterService přidejte následující kód, který nastaví službu singleton. Do třídy Program bezprostředně za komentář // Add services to the container přidejte následující kód:

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

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

    return smtpClient;
});

Spropitné

Tento fragment kódu ale spoléhá na oficiální SmtpClient; tento typ je zastaralý na některých platformách a nedoporučuje se u jiných. Modernější přístup pomocí sady MailKitnajdete v tématu Vytváření vlastních integrací .NET Aspireclient.

Chcete-li otestovat client, přidejte do služby bulletinu dvě jednoduché subscribe a unsubscribe metody POST. Pro přidání následujícího kódu, který v souboru Program.cs projektu MailDevResource.NewsletterService nahradí volání "weatherforecast" MapGet a nastaví trasy ASP.NET Core, postupujte takto:

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

Spropitné

Nezapomeňte odkazovat na obory názvů System.Net.Mail a Microsoft.AspNetCore.Mvc v Program.cs, pokud je editor kódu nepřidá automaticky.

Po aktualizaci souboru Program.cs spusťte hostitele aplikace a použijte prohlížeč nebo curl, abyste dosáhli následujících adres URL (případně pokud používáte Visual Studio můžete použít .http soubory):

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

Pokud chcete toto rozhraní API použít, můžete k odeslání požadavku použít curl. Následující příkaz curl odešle požadavek HTTP POST na koncový bod subscribe a očekává hodnotu dotazovacího řetězce email pro přihlášení k odběru bulletinu. Hlavička Content-Type je nastavená na application/json označující, že text požadavku je ve formátu JSON.:

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

Dalším rozhraním API je koncový bod unsubscribe. Tento koncový bod slouží k odhlášení odběru bulletinu.

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

K odhlášení odběru bulletinu můžete použít následující příkaz curl a předat email parametr koncovému bodu unsubscribe jako řetězec dotazu:

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

Spropitné

Ujistěte se, že https://localhost:7251 nahradíte správným localhost portem (adresa URL hostitele aplikace, kterého používáte).

Pokud tato volání rozhraní API vrátí úspěšnou odpověď (HTTP 200, OK), měli byste být schopni vybrat na prostředku maildev řídicí panel, a pak MailDev UI zobrazí e-maily, které byly odeslány na koncový bod SMTP.

Technické podrobnosti

V následujících částech jsou popsány různé technické podrobnosti, které jsou důležité pochopit při vývoji vlastních prostředků pro .NET.NET Aspire.

Zabezpečení sítí

V tomto příkladu je MailDev kontejnerový prostředek, který je zpřístupněn hostitelskému počítači přes protokol HTTP a SMTP. Prostředek MailDev je vývojový nástroj a není určený pro produkční použití. Pokud chcete místo toho použít PROTOKOL HTTPS, přečtěte si MailDev: KonfiguraceHTTPS .

Při vývoji vlastních prostředků, které zpřístupňují síťová zakončení, je důležité zvážit bezpečnostní důsledky těchto prostředků. Pokud je například prostředek databází, je důležité zajistit, aby byla databáze zabezpečená a že připojovací řetězec není vystavený veřejnému internetu.

Typ `ReferenceExpression` a `EndpointReference`

V předchozím kódu měl MailDevResource dvě vlastnosti:

SmtpEndpoint: typ EndpointReference.
ConnectionStringExpression: typ ReferenceExpression.

Mezi tyto typy patří několik typů, které se používají v rámci .NET Aspire k reprezentaci konfiguračních dat, která nejsou dokončena, dokud se projekt .NET Aspire nespustí nebo nepublikuje do cloudu prostřednictvím nástroje, jako je Azure Developer CLI (azd).

Základním problémem, který tyto typy pomáhají vyřešit, je odložení řešení konkrétních informací o konfiguraci, dokud všechny informace jsou k dispozici.

Například MailDevResource zveřejňuje vlastnost s názvem ConnectionStringExpression podle požadavků rozhraní IResourceWithConnectionString. Typ vlastnosti je ReferenceExpression a je vytvořen předáním interpolovaného řetězce metodě Create.

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

Podpis metody Create je následující:

public static ReferenceExpression Create(
    in ExpressionInterpolatedStringHandler handler)

Toto není běžný argument String. Metoda používá interpolovaný vzor obslužné rutiny řetězcůpro zachycení interpolované řetězcové šablony a hodnot, na které se v ní odkazuje, aby bylo možné provádět vlastní zpracování. V případě .NET.NET Aspirejsou tyto podrobnosti zachyceny v ReferenceExpression, které lze vyhodnotit, jakmile bude k dispozici každá hodnota odkazovaná v interpolovaném řetězci.

Tok provádění funguje takto:

Prostředek, který implementuje IResourceWithConnectionString, se přidá do modelu (například AddMailDev(...)).
IResourceBuilder<MailDevResource> je předán WithReference, který má zvláštní přetížení pro zpracování implementátorů IResourceWithConnectionString.
WithReference zabalí prostředek do instance ConnectionStringReference a objekt se zachytí v EnvironmentCallbackAnnotation, který se vyhodnotí po sestavení a spuštění projektu .NET.NET Aspire.
Proces, který odkazuje na připojovací řetězec, začne .NET.NET Aspire vyhodnocovat výraz. Nejprve získá ConnectionStringReference a zavolá IValueProvider.GetValueAsync.
Metoda GetValueAsync získá hodnotu vlastnosti ConnectionStringExpression, aby získala instanci ReferenceExpression.
Metoda IValueProvider.GetValueAsync potom volá GetValueAsync ke zpracování dříve zachyceného interpolovaného řetězce.
Vzhledem k tomu, že interpolovaný řetězec obsahuje odkazy na jiné typy odkazů, jako je například EndpointReference jsou také vyhodnoceny a nahrazeny reálnou hodnotou (která je nyní k dispozici).

Publikování manifestu

Rozhraní IManifestExpressionProvider je navržené tak, aby vyřešilo problém sdílení informací o připojení mezi prostředky při nasazení. Řešení tohoto konkrétního problému je popsáno v .NET.NET Aspire přehledu vnitřního propojení. Podobně jako místní vývoj je mnoho hodnot nezbytných ke konfiguraci aplikace, ale není možné je určit, dokud se aplikace nenasadí prostřednictvím nástroje, jako je azd (Azure Developer CLI).

Chcete-li tento problém vyřešit, .NET.NET Aspire vytvoří soubor manifestu, který azd a další nástroje pro nasazení interpretují. Místo zadávání konkrétních hodnot pro informace o připojení mezi prostředky se používá syntaxe výrazu, které nástroje pro nasazení vyhodnocují. Obecně se soubor manifestu vývojářům nezobrazuje, ale pro ruční kontrolu je možné ho vygenerovat. Následující příkaz lze použít na hostiteli aplikace k vytvoření manifestu.

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

Tento příkaz vytvoří soubor manifestu jako následující:

{
  "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"
        }
      }
    }
  }
}

Protože MailDevResource implementuje IResourceWithConnectionString logiku publikování manifestu, .NET.NET Aspire chápe, že i když MailDevResource je kontejnerový zdroj, potřebuje také pole connectionString. Pole connectionString odkazuje na další části prostředku maildev v manifestu, aby vytvořilo konečný řetězec:

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

.NET .NET Aspire ví, jak vytvořit tento řetězec, protože se podívá na ConnectionStringExpression a sestaví konečný řetězec prostřednictvím rozhraní IManifestExpressionProvider (podobně jako rozhraní IValueProvider).

MailDevResource se automaticky zahrne do manifestu, protože je odvozen z ContainerResource. Autoři prostředků se mohou rozhodnout zabránit výstupu obsahu do manifestu pomocí metody rozšíření ExcludeFromManifest v sestavovači prostředků.

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
}

Pečlivě je potřeba vzít v úvahu, jestli se prostředek má v manifestu vyskytovat, nebo jestli má být potlačen. Pokud se prostředek přidává do manifestu, měl by být nakonfigurovaný tak, aby byl bezpečný a bezpečný pro použití.

Shrnutí

V kurzu vlastního prostředku jste se naučili, jak vytvořit vlastní prostředek .NET Aspire, který používá existující kontejnerovou aplikaci (MailDev). Pak jste ho použili ke zlepšení místního vývojového prostředí tím, že zjednodušíte testování možností e-mailu, které se můžou použít v aplikaci. Tyto poznatky se dají použít k vytváření dalších vlastních prostředků, které je možné použít v aplikacích založených na .NET.NET Aspire. Tento konkrétní příklad neobsahuje žádné vlastní integrace, ale je možné vytvořit vlastní integrace, aby vývojáři mohli prostředek snadněji používat. V tomto scénáři jste se mohli spolehnout na existující třídu SmtpClient na platformě .NET k odesílání e-mailů.

Další kroky

Vytvořte vlastní integrace .NET Aspireclient

Sdílet prostřednictvím

Vytvořte vlastní .NET.NET Aspire integrační hostingy.

Klíčové prvky uživatelského prostředku .NET.NET Aspire

Praktický příklad: MailDev

Nastavení počátečního projektu

Vytvoření knihovny pro rozšíření prostředků

Definování typů prostředků

Definujte rozšíření prostředků

Ověření vlastní integrace v hostiteli aplikace

Přidání projektu služby .NET do hostitele aplikace pro testování

Odesílání zpráv pomocí připojovacího řetězce

Technické podrobnosti

Zabezpečení sítí

Typ `ReferenceExpression` a `EndpointReference`

Publikování manifestu

Shrnutí

Další kroky

Další materiály

Sdílet prostřednictvím

Vytvořte vlastní .NET.NET Aspire integrační hostingy.

Klíčové prvky uživatelského prostředku .NET.NET Aspire

Praktický příklad: MailDev

Nastavení počátečního projektu

Vytvoření knihovny pro rozšíření prostředků

Definování typů prostředků

Definujte rozšíření prostředků

Ověření vlastní integrace v hostiteli aplikace

Přidání projektu služby .NET do hostitele aplikace pro testování

Odesílání zpráv pomocí připojovacího řetězce

Technické podrobnosti

Zabezpečení sítí

Typ ReferenceExpression a EndpointReference

Publikování manifestu

Shrnutí

Další kroky

Další materiály

Typ `ReferenceExpression` a `EndpointReference`