Image to PDF in C# and .NET

Overview

Convert images to PDF documents with the PDFCrowd .NET client. The client handles communication with the API, while conversions run on PDFCrowd's servers.

Installation

Install the .NET client with NuGet or see other installation options.

dotnet add package Pdfcrowd.Official

Quick Start

Update the input URLs and filenames as needed.

using System;

class Example
{
    static void Main()
    {
        var client = new pdfcrowd.ImageToPdfClient("demo", "demo");

        client.convertUrlToFile("https://your-server.com/logo.png", "logo.pdf");
    }
}

using System;

class Example
{
    static void Main()
    {
        var client = new pdfcrowd.ImageToPdfClient("demo", "demo");

        client.convertFileToFile("logo.png", "logo.pdf");
    }
}

Configure a Conversion

Authentication

Pass your PDFCrowd username and API key to ImageToPdfClient. Find your credentials on the API Keys page.

Choose an Input

The source image format is detected automatically. Each conversion accepts one image.

For a local image or a URL on localhost, upload the file, bytes, or an open binary stream. Remote URLs must be reachable from PDFCrowd's servers.

Send Image Bytes

Read logo.png as bytes, convert it to PDF, and save logo.pdf:

using System;
using System.IO;

class Example
{
    static void Main()
    {
        var client = new pdfcrowd.ImageToPdfClient("demo", "demo");

        byte[] image = File.ReadAllBytes("logo.png");
        client.convertRawDataToFile(image, "logo.pdf");
    }
}

Add Conversion Settings

Set conversion options on the client before calling a conversion method. For example, client.setPageSize("A4"); selects A4 paper.

Common settings are listed below. See the method reference for all available options or browse .NET examples.

Image operations change the source image; page settings control the output area and image placement.

With an explicit page size, use setPrintPageMode() with "fit" to preserve the aspect ratio and fit the image inside the margins. The "stretch" mode fills the area and can distort the image. The default mode does not scale the image to fit and can crop it. Without an explicit size, margins add a border around the image.

Handle the Result

Choose an Output

The PDF contains the source image. Making text in a scan searchable requires a separate OCR step.

The methods below use URL input; local files, bytes, and input streams have corresponding methods.

File-output methods create a new file and throw IOException if the destination already exists.

This example converts an image, receives the result as a byte[] and saves it as logo.pdf:

using System;
using System.IO;

class Example
{
    static void Main()
    {
        var client = new pdfcrowd.ImageToPdfClient("demo", "demo");

        byte[] result = client.convertUrl(
            "https://your-server.com/logo.png"
        );
        File.WriteAllBytes("logo.pdf", result);
    }
}

When serving the result from a web application, use Content-Type: application/pdf.

Handle Errors

The client throws a pdfcrowd.Error exception on conversion or validation errors. This example converts an image and writes any PDFCrowd error to standard error, including its HTTP status and reason code:

using System;

class Example
{
    static void Main()
    {
        var client = new pdfcrowd.ImageToPdfClient("demo", "demo");

        try
        {
            client.convertUrlToFile(
                "https://your-server.com/logo.png", "logo.pdf"
            );
        }
        catch (pdfcrowd.Error error)
        {
            Console.Error.WriteLine("PDFCrowd: {0}", error);
            Console.Error.WriteLine("Status: {0}; reason: {1}",
                error.getStatusCode(), error.getReasonCode());
            throw;
        }
    }
}

Local .NET errors, such as a failure to read an input file or write the output, may need separate handling.

pdfcrowd.Error provides these methods:

error.ToString() returns the complete error, including available status and reason codes.

Common Status Codes

See all status and reason codes for specific explanations and Limits and Retries for retry behavior.

Read Conversion Information

This information is available after a conversion and describes the client's last conversion.

Limits and Retries

Request rate and concurrency limits depend on your license. Control how quickly your application submits conversions and how many it runs at once. A 429 response concerns request rate; a 430 response concerns requests already in progress. The maximum upload size is 300 MB.

The .NET client automatically retries a request once when it receives HTTP 502 or 503. Use setRetryCount() to change that count, or set it to 0 to disable automatic retries. Account for these retries when adding an application-level retry policy.

Troubleshooting

Inspect a Conversion

This example converts an image with debug logging enabled and writes the debug log URL to standard error when available. Use the input and settings from the conversion you are investigating.

using System;

class Example
{
    static void Main()
    {
        var client = new pdfcrowd.ImageToPdfClient("demo", "demo");

        try
        {
            client.setDebugLog(true);
            client.convertUrlToFile(
                "https://your-server.com/logo.png", "logo.pdf"
            );
        }
        catch (pdfcrowd.Error error)
        {
            Console.Error.WriteLine("PDFCrowd: {0}", error);
            Console.Error.WriteLine("Status: {0}; reason: {1}",
                error.getStatusCode(), error.getReasonCode());
            throw;
        }
        finally
        {
            string debugLogUrl = client.getDebugLogUrl();
            if (!string.IsNullOrEmpty(debugLogUrl))
            {
                Console.Error.WriteLine("Debug log: {0}", debugLogUrl);
            }
        }
    }
}

The debug log contains conversion settings and processing details. You can also find logs in your conversion history. A local or connection failure may occur before a conversion log is available.

Common Problems

For help, contact support and include any available diagnostics, the client version, and enough detail to reproduce the problem.