Add MailDev and MailKit custom integration sample

.github/workflows/ci.yml

@@ -64,7 +64,7 @@ jobs:
       shell: bash
       run: |
         install_path="$RUNNER_TEMP/aspire-cli"
-        curl -sSL https://aspire.dev/install.sh | bash -s -- --install-path "$install_path" --skip-path
+        curl -sSL https://aspire.dev/install.sh | bash -s -- --install-path "$install_path" --skip-path --quality staging
         echo "$install_path" >> "$GITHUB_PATH"
         echo "ASPIRE_CLI=$install_path/aspire" >> "$GITHUB_ENV"
         "$install_path/aspire" --version
@@ -78,7 +78,7 @@ jobs:
         $aspirePath = Join-Path $installPath 'aspire.exe'
 
         Invoke-RestMethod 'https://aspire.dev/install.ps1' -OutFile $installScript
-        & $installScript -InstallPath $installPath -SkipPath
+        & $installScript -InstallPath $installPath -SkipPath -Quality staging
 
         $installPath | Out-File -FilePath $env:GITHUB_PATH -Encoding utf8 -Append
         "ASPIRE_CLI=$aspirePath" | Out-File -FilePath $env:GITHUB_ENV -Encoding utf8 -Append

README.md

@@ -38,6 +38,7 @@ Samples for [Aspire](https://aspire.dev).
 | Sample | Workload languages | AppHost | Deploy | Description |
 | --- | --- | --- | --- | --- |
 | [Integrating a Go App](./samples/container-build) | Go | C# AppHost | Docker Compose | Builds and runs a Go Gin app from a Dockerfile with Aspire. |
+| [Custom MailDev and MailKit integrations](./samples/maildev-mailkit) | C#, TypeScript | TypeScript AppHost | Run only | Authors custom hosting and client integrations with ATS-generated TypeScript APIs. |
 | [Go API](./samples/golang-api) | Go | TypeScript AppHost | Docker Compose | Go + chi API with Aspire-managed run and publish flows. |
 | [Python FastAPI + PostgreSQL](./samples/python-fastapi-postgres) | Python | TypeScript AppHost | Docker Compose | FastAPI CRUD API wired to PostgreSQL and pgAdmin. |
 | [Python OpenAI Agent](./samples/python-openai-agent) | Python | TypeScript AppHost | Docker Compose | FastAPI AI agent sample with OpenAI integration. |

samples/maildev-mailkit/.gitignore

@@ -0,0 +1,3 @@
+.aspire/
+**/bin/
+**/obj/

samples/maildev-mailkit/CSharpAppHost/CSharpAppHost.csproj

@@ -0,0 +1,18 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFramework>net10.0</TargetFramework>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Aspire.Hosting" Version="13.5.0" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\MailDev.Hosting\MailDev.Hosting.csproj" />
+  </ItemGroup>
+
+</Project>

samples/maildev-mailkit/CSharpAppHost/Program.cs

@@ -0,0 +1,13 @@
+using Aspire.Hosting;
+
+var builder = DistributedApplication.CreateBuilder(args);
+
+var maildev = builder.AddMailDev("maildev");
+
+builder.AddProject("newsletterservice", "../NewsletterService/NewsletterService.csproj")
+    .WithHttpHealthCheck("/health")
+    .WithExternalHttpEndpoints()
+    .WithReference(maildev)
+    .WaitFor(maildev);
+
+builder.Build().Run();

samples/maildev-mailkit/MailDev.Hosting.Tests/MailDev.Hosting.Tests.csproj

@@ -0,0 +1,20 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <TargetFramework>net10.0</TargetFramework>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+    <IsPackable>false</IsPackable>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Microsoft.NET.Test.Sdk" Version="18.3.0" />
+    <PackageReference Include="xunit.v3" Version="3.2.2" />
+    <PackageReference Include="xunit.runner.visualstudio" Version="3.1.5" PrivateAssets="all" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\MailDev.Hosting\MailDev.Hosting.csproj" />
+  </ItemGroup>
+
+</Project>

samples/maildev-mailkit/MailDev.Hosting.Tests/MailDevResourceTests.cs

@@ -0,0 +1,84 @@
+using Aspire.Hosting;
+using Aspire.Hosting.ApplicationModel;
+using System.Reflection;
+using Xunit;
+
+namespace MailDev.Hosting.Tests;
+
+public sealed class MailDevResourceTests
+{
+    [Fact]
+    public void MailDevHostingSurfaceIsExportedForAts()
+    {
+        var method = typeof(MailDevResourceBuilderExtensions).GetMethod(
+            nameof(MailDevResourceBuilderExtensions.AddMailDev),
+            BindingFlags.Public | BindingFlags.Static);
+
+        Assert.NotNull(method);
+        Assert.Contains(
+            method.GetCustomAttributes(),
+            attribute => attribute.GetType().Name == "AspireExportAttribute");
+        Assert.Contains(
+            typeof(MailDevResource).GetCustomAttributes(),
+            attribute => attribute.GetType().Name == "AspireExportAttribute");
+
+        var nameParameter = Assert.Single(
+            method.GetParameters(),
+            parameter => parameter.Name == "name");
+        Assert.Contains(
+            nameParameter.GetCustomAttributes(),
+            attribute => attribute.GetType().Name == "ResourceNameAttribute");
+    }
+
+    [Fact]
+    public void AddMailDevConfiguresContainerAndEndpoints()
+    {
+        var builder = DistributedApplication.CreateBuilder();
+
+        var maildev = builder.AddMailDev("maildev");
+
+        var image = Assert.Single(maildev.Resource.Annotations.OfType<ContainerImageAnnotation>());
+        Assert.Equal("docker.io", image.Registry);
+        Assert.Equal("maildev/maildev", image.Image);
+        Assert.Equal("2.2.1", image.Tag);
+
+        var endpoints = maildev.Resource.Annotations.OfType<EndpointAnnotation>().ToArray();
+        var http = Assert.Single(endpoints, endpoint => endpoint.Name == "http");
+        var smtp = Assert.Single(endpoints, endpoint => endpoint.Name == "smtp");
+        Assert.Equal(1080, http.TargetPort);
+        Assert.Equal(1025, smtp.TargetPort);
+    }
+
+    [Fact]
+    public void AddMailDevCreatesSecretPasswordAndDeferredConnectionString()
+    {
+        var builder = DistributedApplication.CreateBuilder();
+
+        var maildev = builder.AddMailDev("maildev");
+
+        Assert.True(maildev.Resource.PasswordParameter.Secret);
+        Assert.Null(maildev.Resource.UsernameParameter);
+        Assert.Equal(
+            "Endpoint=smtp://{maildev.bindings.smtp.host}:{maildev.bindings.smtp.port};Username=mail-dev;Password={maildev-password.value}",
+            maildev.Resource.ConnectionStringExpression.ValueExpression);
+    }
+
+    [Fact]
+    public void AddMailDevUsesProvidedCredentialParameters()
+    {
+        var builder = DistributedApplication.CreateBuilder();
+        var username = builder.AddParameter("smtp-user");
+        var password = builder.AddParameter("smtp-password", secret: true);
+
+        var maildev = builder.AddMailDev(
+            "maildev",
+            username: username,
+            password: password);
+
+        Assert.Same(username.Resource, maildev.Resource.UsernameParameter);
+        Assert.Same(password.Resource, maildev.Resource.PasswordParameter);
+        Assert.Equal(
+            "Endpoint=smtp://{maildev.bindings.smtp.host}:{maildev.bindings.smtp.port};Username={smtp-user.value};Password={smtp-password.value}",
+            maildev.Resource.ConnectionStringExpression.ValueExpression);
+    }
+}

samples/maildev-mailkit/MailDev.Hosting/MailDev.Hosting.csproj

@@ -0,0 +1,14 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <TargetFramework>net10.0</TargetFramework>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+    <EnableAspireIntegrationAnalyzers>true</EnableAspireIntegrationAnalyzers>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Aspire.Hosting" Version="13.5.0" />
+  </ItemGroup>
+
+</Project>

samples/maildev-mailkit/MailDev.Hosting/MailDevResource.cs

@@ -0,0 +1,36 @@
+namespace Aspire.Hosting.ApplicationModel;
+
+/// <summary>Represents a MailDev container resource.</summary>
+[AspireExport]
+public sealed class MailDevResource(
+    [ResourceName] string name,
+    ParameterResource? username,
+    ParameterResource password)
+    : ContainerResource(name), IResourceWithConnectionString
+{
+    internal const string HttpEndpointName = "http";
+    internal const string SmtpEndpointName = "smtp";
+
+    private const string DefaultUsername = "mail-dev";
+    private EndpointReference? _smtpEndpoint;
+
+    /// <summary>Gets the optional MailDev SMTP username parameter.</summary>
+    public ParameterResource? UsernameParameter { get; } = username;
+
+    /// <summary>Gets the MailDev SMTP password parameter.</summary>
+    public ParameterResource PasswordParameter { get; } = password;
+
+    internal ReferenceExpression UsernameReference =>
+        UsernameParameter is not null
+            ? ReferenceExpression.Create($"{UsernameParameter}")
+            : ReferenceExpression.Create($"{DefaultUsername}");
+
+    /// <summary>Gets the MailDev SMTP endpoint.</summary>
+    public EndpointReference SmtpEndpoint =>
+        _smtpEndpoint ??= new(this, SmtpEndpointName);
+
+    /// <inheritdoc />
+    public ReferenceExpression ConnectionStringExpression =>
+        ReferenceExpression.Create(
+            $"Endpoint=smtp://{SmtpEndpoint.Property(EndpointProperty.HostAndPort)};Username={UsernameReference};Password={PasswordParameter}");
+}

samples/maildev-mailkit/MailDev.Hosting/MailDevResourceBuilderExtensions.cs

@@ -0,0 +1,56 @@
+using Aspire.Hosting.ApplicationModel;
+
+namespace Aspire.Hosting;
+
+/// <summary>Provides extension methods for adding MailDev resources.</summary>
+public static class MailDevResourceBuilderExtensions
+{
+    private const string Registry = "docker.io";
+    private const string Image = "maildev/maildev";
+    private const string Tag = "2.2.1";
+    private const string UsernameEnvironmentVariable = "MAILDEV_INCOMING_USER";
+    private const string PasswordEnvironmentVariable = "MAILDEV_INCOMING_PASS";
+
+    /// <summary>Adds a MailDev container resource.</summary>
+    /// <param name="builder">The distributed application builder.</param>
+    /// <param name="name">The resource name.</param>
+    /// <param name="httpPort">The optional host port for the MailDev web interface.</param>
+    /// <param name="smtpPort">The optional host port for SMTP.</param>
+    /// <param name="username">The optional SMTP username parameter.</param>
+    /// <param name="password">The optional SMTP password parameter.</param>
+    /// <returns>The MailDev resource builder.</returns>
+    [AspireExport]
+    public static IResourceBuilder<MailDevResource> AddMailDev(
+        this IDistributedApplicationBuilder builder,
+        [ResourceName] string name,
+        int? httpPort = null,
+        int? smtpPort = null,
+        IResourceBuilder<ParameterResource>? username = null,
+        IResourceBuilder<ParameterResource>? password = null)
+    {
+        ArgumentNullException.ThrowIfNull(builder);
+
+        var passwordParameter = password?.Resource ??
+            ParameterResourceBuilderExtensions.CreateDefaultPasswordParameter(
+                builder, $"{name}-password");
+        var resource = new MailDevResource(name, username?.Resource, passwordParameter);
+
+        return builder.AddResource(resource)
+            .WithImage(Image)
+            .WithImageRegistry(Registry)
+            .WithImageTag(Tag)
+            .WithHttpEndpoint(
+                targetPort: 1080,
+                port: httpPort,
+                name: MailDevResource.HttpEndpointName)
+            .WithEndpoint(
+                targetPort: 1025,
+                port: smtpPort,
+                name: MailDevResource.SmtpEndpointName)
+            .WithEnvironment(context =>
+            {
+                context.EnvironmentVariables[UsernameEnvironmentVariable] = resource.UsernameReference;
+                context.EnvironmentVariables[PasswordEnvironmentVariable] = resource.PasswordParameter;
+            });
+    }
+}

samples/maildev-mailkit/MailKit.Client.Tests/MailKit.Client.Tests.csproj

@@ -0,0 +1,21 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <TargetFramework>net10.0</TargetFramework>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+    <IsPackable>false</IsPackable>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Microsoft.Extensions.Hosting" Version="10.0.0" />
+    <PackageReference Include="Microsoft.NET.Test.Sdk" Version="18.3.0" />
+    <PackageReference Include="xunit.v3" Version="3.2.2" />
+    <PackageReference Include="xunit.runner.visualstudio" Version="3.1.5" PrivateAssets="all" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\MailKit.Client\MailKit.Client.csproj" />
+  </ItemGroup>
+
+</Project>

samples/maildev-mailkit/MailKit.Client.Tests/MailKitClientSettingsTests.cs

@@ -0,0 +1,43 @@
+using MailKit.Client;
+using Xunit;
+
+namespace MailKit.Client.Tests;
+
+public sealed class MailKitClientSettingsTests
+{
+    [Fact]
+    public void ParseConnectionStringAcceptsUri()
+    {
+        var settings = new MailKitClientSettings();
+
+        settings.ParseConnectionString("smtp://localhost:1025");
+
+        Assert.Equal(new Uri("smtp://localhost:1025"), settings.Endpoint);
+        Assert.Null(settings.Credentials);
+    }
+
+    [Fact]
+    public void ParseConnectionStringAcceptsEndpointAndCredentials()
+    {
+        var settings = new MailKitClientSettings();
+
+        settings.ParseConnectionString(
+            "Endpoint=smtp://localhost:1025;Username=mail-dev;Password=secret");
+
+        Assert.Equal(new Uri("smtp://localhost:1025"), settings.Endpoint);
+        Assert.Equal("mail-dev", settings.Credentials?.UserName);
+        Assert.Equal("secret", settings.Credentials?.Password);
+    }
+
+    [Theory]
+    [InlineData(null)]
+    [InlineData("")]
+    [InlineData("Host=localhost")]
+    public void ParseConnectionStringRejectsMissingEndpoint(string? connectionString)
+    {
+        var settings = new MailKitClientSettings();
+
+        Assert.Throws<InvalidOperationException>(
+            () => settings.ParseConnectionString(connectionString));
+    }
+}