MVFC.Aspire.Helpers.Gotenberg 9.0.3

MVFC.Aspire.Helpers.Gotenberg

🇧🇷 Leia em Português

Helpers for integrating with Gotenberg (API for converting documents and PDFs) in .NET Aspire projects.

Motivation

Running Gotenberg locally usually means:

• Pulling the correct Docker image/tag.
• Mapping ports and exposing the HTTP endpoint to your applications.
• Hard‑coding the base URL of the PDF service in code or configuration.

With .NET Aspire you can model the container, but you still need to:

• Configure image, ports and health checks.
• Decide how to expose the base URL to each project.
• Keep host/port details in sync between the app host and your services.

MVFC.Aspire.Helpers.Gotenberg focuses exactly on this:

• AddGotenberg(...) starts the official gotenberg/gotenberg:8 image with an HTTP endpoint and health check.
• project.WithReference(gotenberg) injects GOTENBERG__BASE_URL so your API/worker can just read it from configuration.

Overview

This project allows you to easily add and integrate Gotenberg as a managed resource in distributed .NET Aspire applications. It simplifies provisioning the Gotenberg container and provides extension methods for configuring it in the AppHost.

Project Structure

• MVFC.Aspire.Helpers.Gotenberg: Helpers and extensions library for Gotenberg.

Features

• Adds the Gotenberg container to the Aspire application.
• Manages automatic health check at /health.
• Automatically injects the service's base URL into the consuming project.
• Extension methods for quick configuration of custom ports.

Compatible Images

• gotenberg/gotenberg (default tag 8)

Installation

Add the NuGet package to your AppHost project:

dotnet add package MVFC.Aspire.Helpers.Gotenberg

Quick Aspire usage (AppHost)

using Aspire.Hosting;
using MVFC.Aspire.Helpers.Gotenberg;

var builder = DistributedApplication.CreateBuilder(args);

// Adds the Gotenberg container on host port 3000
var gotenberg = builder.AddGotenberg("gotenberg", port: 3000);

builder.AddProject<Projects.MVFC_Aspire_Helpers_Playground_Api>("api-example")
       .WithReference(gotenberg)
       .WaitFor(gotenberg);

await builder.Build().RunAsync();

Reference in backend project (API, Web, etc.)

When using .WithReference(gotenberg), the AppHost will automatically inject an environment variable containing the accessible Gotenberg address so the consuming application can connect:

• GOTENBERG__BASE_URL = http://localhost:<port>

Use that value to configure your HTTP client pointing to Gotenberg.

Provisioning diagram

sequenceDiagram
    participant Aspire as .NET Aspire
    participant Container as Gotenberg Container
    
    Aspire->>Container: Start container (gotenberg/gotenberg)
    Container-->>Aspire: Ready (port 3000 available)
    Aspire->>App: Start App with GOTENBERG__BASE_URL

Fluent methods

AddGotenberg parameters

Port details and visualization

• Default mapped port: 3000 (internally also 3000).
• Health check: http://localhost:<port>/health.

Requirements

• .NET 9+
• Aspire.Hosting >= 9.5.0

License

Apache-2.0