Using EvoPdf Next for .NET in Google Cloud Run

EvoPdf Next for .NET is a library that can be integrated into applications running in Google Cloud Run to create and process PDF documents.

You can create PDF documents, convert HTML, Word, Excel, RTF and Markdown documents to PDF, extract text and images from existing PDF documents, perform text search operations on PDF documents and convert PDF pages to images.

EvoPdf Next for .NET runs in Cloud Run services deployed from a Linux container image built on the ASP.NET Core runtime images, in both execution environments of Cloud Run. The second generation execution environment converts faster and is the one we recommend.

The image contains the application, the library runtime and the system packages required by the HTML to PDF Converter, so the service needs no setup when it starts. The other components don't require any additional packages.

The library targets .NET Standard 2.0, making it usable in any .NET Core application that supports this standard.

Create a new ASP.NET Core project in Visual Studio and use the NuGet Package Manager to add a reference to the EvoPdf.Next.Linux NuGet metapackage which will install all the library components.

To install only specific components of the EvoPdf Next library you can add references to the corresponding NuGet packages. You can find more details about the available packages in the Getting Started on Linux documentation section.

After installing the package, add the using EvoPdf.Next; directive at the top of your source files to access the EvoPdf Next API.

Publish the application for Linux:

dotnet publish -c Release -r linux-x64 --self-contained false -o publish

Create the Dockerfile below next to the publish folder and replace MyApp.dll with the name of your application. It starts from the ASP.NET Core runtime image, installs the system packages required by the HTML to PDF Converter, copies the publish folder and gives execute permission to the runtime files, which a publish folder created on Windows does not keep. The application listens on port 8080, the port to which Cloud Run sends the requests by default.

FROM mcr.microsoft.com/dotnet/aspnet:10.0

# Install the packages required by the HTML to PDF Converter
RUN apt-get update && \
    apt-get install -y \
        libnss3 \
        libatk-bridge2.0-0 \
        libcairo2 \
        libpango-1.0-0 && \
    rm -rf /var/lib/apt/lists/*

# Set the working directory
WORKDIR /app

# Copy the published application
COPY publish/ .

# Ensure execute permissions for the HTML to PDF Converter runtime
RUN chmod +x /app/evopdf_runtimes/linux-x64/native/evopdf_loadhtml

# Ensure execute permissions for the PDF Processor runtime
RUN chmod +x /app/evopdf_runtimes/linux-x64/native/evopdf_pdfprocessor

# Listen on the default port of Cloud Run
ENV ASPNETCORE_URLS=http://+:8080
EXPOSE 8080

# Start the application
ENTRYPOINT ["dotnet", "MyApp.dll"]

For an application that targets .NET 8, start from the mcr.microsoft.com/dotnet/aspnet:8.0 image; the packages are the same. Cloud Run runs x86_64 images, so build the image for this architecture:

docker build --platform linux/amd64 -t pdf-app .

Cloud Run loads the image from a repository in Artifact Registry. In the Google Cloud console open Cloud Shell (it is already signed in to your project) and run the commands below to enable the services and to create a Docker repository in the region where the service will run. Replace PROJECT_ID with the ID of your project; the examples use the europe-west3 region.

gcloud config set project PROJECT_ID
gcloud services enable run.googleapis.com artifactregistry.googleapis.com
gcloud artifacts repositories create pdf-images --repository-format=docker --location=europe-west3

To push the image from the computer where it was built, sign Docker in to the registry. With the Google Cloud CLI installed on that computer, run gcloud auth configure-docker europe-west3-docker.pkg.dev. Without it, run gcloud auth print-access-token in Cloud Shell and use the token as the password, valid for one hour:

docker login -u oauth2accesstoken europe-west3-docker.pkg.dev
docker tag pdf-app europe-west3-docker.pkg.dev/PROJECT_ID/pdf-images/pdf-app:1
docker push europe-west3-docker.pkg.dev/PROJECT_ID/pdf-images/pdf-app:1

Deploy the service from Cloud Shell. The command creates the service, gives it a public address and starts it:

gcloud run deploy pdf-app --image europe-west3-docker.pkg.dev/PROJECT_ID/pdf-images/pdf-app:1 \
  --region europe-west3 --allow-unauthenticated \
  --memory 2Gi --cpu 2 --timeout 300 --execution-environment gen2

• --memory 2Gi --cpu 2: HTML to PDF conversion can be resource-intensive, depending on the complexity of the content. 2 vCPUs and 2 GiB of memory per instance are the minimum we recommend; choose more memory for large documents and for many parallel conversions.

• --timeout 300: the time a request may take, 5 minutes here, for long conversions.

• --execution-environment gen2: the second generation execution environment.

• --allow-unauthenticated: makes the service public. Leave it out for a service that only accepts authenticated requests.

By default Cloud Run gives processor time to an instance only while it handles requests, which suits conversions made during a request. An application that converts in background tasks after the response is sent needs processor time outside the requests, set with the --no-cpu-throttling option.

The deploy command ends with the Service URL of the application. The first request to a new instance takes longer, while Cloud Run starts the instance and the application starts the converter; the following requests convert at the usual speed. To deploy a new version, push a new image and run the deploy command again with its tag.

As a reference, in the Europe (Frankfurt) region an instance with 2 vCPUs and 2 GiB of memory converted a two-page HTML document 4.3 times per second with four parallel conversions in the second generation execution environment and 3.2 times per second in the first generation.

You can follow the same steps to publish the EvoPdf Next ASP.NET demo application, from the EvoPdf_Next_AspNetDemo_Linux_net10.0.csproj project, with EvoPdf_Next_AspNetDemo_Linux_net10.0.dll in the Dockerfile.

The output and the exceptions of the application are shown in the Logs tab of the service in the Cloud Run console, or with the command below in Cloud Shell:

gcloud run services logs read pdf-app --region europe-west3 --limit 100

If the deployment fails because the container does not listen on the expected port, check that the port in the ASPNETCORE_URLS variable of the Dockerfile matches the port of the service, 8080 by default, or set the port of the application with the --port option of the deploy command.

Reference

Other Resources