Docker and serverless | Aspose.Page for .NET

Start here: use the right package

Choose the package that matches the operating system on which your application runs.

Package	Graphics backend	Linux containers
Aspose.Page	System.Drawing.Common	No — Windows only on .NET 7 and later
Aspose.Page.Drawing	Aspose.Drawing (managed)	Yes

System.Drawing.Common is supported only on Windows starting with .NET 7. Because the main Aspose.Page package depends on it, use Aspose.Page.Drawing in Linux containers and serverless Linux environments. Aspose.Page.Drawing provides the same API with a managed graphics backend and targets .NET Standard 2.0 and .NET 7.0, which also covers .NET 8 and later.

See Installation for the package setup used on each platform.

dotnet add package Aspose.Page.Drawing

Your using statements and conversion code remain unchanged. Install only one of the two packages.

Docker

Migrating from a native converter

The following starting image installs a native converter and its font package:

FROM mcr.microsoft.com/dotnet/aspnet:8.0-bookworm-slim

RUN apt-get update \
 && apt-get install -y --no-install-recommends \
      ghostscript \
      fonts-dejavu-core \
 && rm -rf /var/lib/apt/lists/*

WORKDIR /app
COPY --from=build /app/publish .
ENTRYPOINT ["dotnet", "MyApp.dll"]

When the application uses Aspose.Page.Drawing, the native converter binary is not required in the image.

Dockerfile

Install fontconfig and the font files required by your documents:

FROM mcr.microsoft.com/dotnet/aspnet:8.0-bookworm-slim

RUN apt-get update \
 && apt-get install -y --no-install-recommends \
      fontconfig \
      fonts-dejavu-core \
 && rm -rf /var/lib/apt/lists/*

WORKDIR /app
COPY --from=build /app/publish .
ENTRYPOINT ["dotnet", "MyApp.dll"]

Configure fonts

A working font configuration is always required. The managed Aspose.Drawing backend initializes font handling regardless of what is inside the document, so install fontconfig even when every font is embedded in the input file.

Font files are required only when a document references system fonts by name:

• Fonts embedded in the document: no additional font files are needed because the glyphs are in the document.
• Fonts referenced by name: the named font must be available in the container. If it is missing, a substitute is used and conversion can still succeed, but the typography can differ from the source.

Aspose.Page embeds Liberation Serif as a fallback. Consequently, a missing font normally changes the rendered typography instead of causing a missing-font exception. For arbitrary third-party documents, install a practical set of fonts:

RUN apt-get install -y --no-install-recommends fonts-dejavu-core fonts-liberation

Liberation Sans and Liberation Mono are metric-compatible substitutes for Arial and Courier New. If you supply specific font files with the application, configure PdfSaveOptions through AdditionalFontsFolders:

var options = new PdfSaveOptions(true)
{
    AdditionalFontsFolders = new[] { "/app/fonts" }
};

The operating system’s standard font folders are searched in addition to the folders you specify.

Diagnose font substitutions and conversion errors

Load the input with PsDocument and call SaveAsPdf with PdfSaveOptions to collect recoverable conversion errors. The API spells SupressErrors with one p. When it is true, suppressed conversion errors are available through Exceptions:

var document = new PsDocument("input.ps");
var options = new PdfSaveOptions(true);

document.SaveAsPdf("output.pdf", options);

foreach (Exception ex in options.Exceptions)
{
    Console.WriteLine($"Conversion notice: {ex.Message}");
}

During local diagnosis, enable Debug to write conversion diagnostics to standard output:

options.Debug = true;

The API reference documents the error collection and debug channels but does not identify a dedicated font-substitution event. When validating a deployment, enable both channels, convert a file that references an unavailable font, record the diagnostics produced by your library version, and compare the PDF with a known-good render. Do not use a successful conversion or a non-empty output file as proof that the intended fonts were used.

Compare container images

Save the two Dockerfiles shown above as Dockerfile.native and Dockerfile.managed, then build both with your own application and base image:

docker build -t myapp:native  -f Dockerfile.native .
docker build -t myapp:managed -f Dockerfile.managed .
docker images | grep myapp

To inspect the packages installed in each Debian-based image:

docker run --rm myapp:native  dpkg -l | wc -l
docker run --rm myapp:managed dpkg -l | wc -l

AWS Lambda

Aspose.Page.Drawing is deployed as part of the .NET Lambda package, so the function does not require a native converter layer. The following conversion method assumes that the handler has downloaded its input to Lambda’s writable /tmp directory. It creates an Aspose.Page license and calls SetLicense once when the function class is initialized, then converts with file paths:

using System;
using Amazon.Lambda.Core;
using Aspose.Page.EPS;
using Aspose.Page.EPS.Device;

public class Function
{
    static Function()
    {
        var license = new Aspose.Page.License();
        license.SetLicense("Aspose.Page.NET.lic");
    }

    private static string ConvertDocument(string inputPath, ILambdaLogger logger)
    {
        var outputPath = "/tmp/output.pdf";
        var document = new PsDocument(inputPath);

        // Suppress minor errors and collect them instead.
        var options = new PdfSaveOptions(true);
        document.SaveAsPdf(outputPath, options);

        foreach (Exception ex in options.Exceptions)
        {
            logger.LogWarning(ex.Message);
        }

        return outputPath;
    }
}

Ship any required font files in the deployment package and set AdditionalFontsFolders to their extracted path, or use a container image in which you control the font packages. Conversion is CPU-bound and memory use depends on page complexity. Because Lambda assigns CPU in proportion to memory, test several memory settings with representative documents.

Azure Functions

Native packages cannot be installed on the Azure Functions Consumption plan: there is no elevated package-installation step or persistent host to prepare. A managed NuGet package is deployed with the function and does not require a native converter installation.

The .NET API supports both the stream constructor for PsDocument and the stream overload of SaveAsPdf, so an HTTP-triggered function can convert the request body without an intermediate file:

using System;
using System.IO;
using System.Net;
using System.Threading.Tasks;
using Aspose.Page.EPS;
using Aspose.Page.EPS.Device;
using Microsoft.Azure.Functions.Worker;
using Microsoft.Azure.Functions.Worker.Http;
using Microsoft.Extensions.Logging;

public class ConvertFunction
{
    private readonly ILogger<ConvertFunction> _logger;

    public ConvertFunction(ILogger<ConvertFunction> logger) => _logger = logger;

    [Function("ConvertPostScript")]
    public async Task<HttpResponseData> Run(
        [HttpTrigger(AuthorizationLevel.Function, "post")] HttpRequestData req)
    {
        using var input = new MemoryStream();
        await req.Body.CopyToAsync(input);
        input.Position = 0;

        var document = new PsDocument(input);

        // Suppress minor errors and collect them instead.
        var options = new PdfSaveOptions(true);

        using var output = new MemoryStream();
        document.SaveAsPdf(output, options);

        foreach (Exception ex in options.Exceptions)
        {
            _logger.LogWarning("Conversion notice: {Message}", ex.Message);
        }

        var response = req.CreateResponse(HttpStatusCode.OK);
        response.Headers.Add("Content-Type", "application/pdf");
        output.Position = 0;
        await output.CopyToAsync(response.Body);
        return response;
    }
}

On the Consumption plan, ship required font files with the function and point AdditionalFontsFolders to them because operating-system font packages cannot be installed.

Licensing

Review the deployment and distribution terms in Licensing and Subscription.

Checklist for containerized conversion

• Use Aspose.Page.Drawing on Linux instead of Aspose.Page.
• Install fontconfig unconditionally in Linux images.
• Determine whether the input documents embed fonts or reference them by name, and install the required font files.
• Enable SupressErrors and log every entry in options.Exceptions.
• Test missing-font behavior with Debug enabled and preserve the diagnostic channel used by your library version.
• Use a writable temporary path such as /tmp on Lambda.
• Apply the license once at startup instead of once per request.
• Test the memory limit with the largest representative document.
• Visually compare output against a known-good render.

Font substitution can produce a valid PDF with typography that differs from the source, so visual validation is an essential deployment check.