OfficePDF.Sdk 1.0.0

dotnet add package OfficePDF.Sdk --version 1.0.0
                    
NuGet\Install-Package OfficePDF.Sdk -Version 1.0.0
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="OfficePDF.Sdk" Version="1.0.0" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="OfficePDF.Sdk" Version="1.0.0" />
                    
Directory.Packages.props
<PackageReference Include="OfficePDF.Sdk" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add OfficePDF.Sdk --version 1.0.0
                    
#r "nuget: OfficePDF.Sdk, 1.0.0"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package OfficePDF.Sdk@1.0.0
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=OfficePDF.Sdk&version=1.0.0
                    
Install as a Cake Addin
#tool nuget:?package=OfficePDF.Sdk&version=1.0.0
                    
Install as a Cake Tool

OfficePDF .NET SDK

High-fidelity Word to PDF conversion. Works against the OfficePDF cloud API and against an on-premise server with the same code.

dotnet add package OfficePDF.Sdk

Targets netstandard2.0 (so .NET Framework 4.6.1+ works) and net8.0.

Quick start

using OfficePDF.Sdk;

using var client = new OfficePdfClient("opk_...");

var result = await client.ConvertAsync("contract.docx");   // uploads, polls, returns
if (result.Succeeded)
{
    await result.SaveAsync("contract.pdf");
}

Cloud or on-premise

The same interface; only the base URL changes.

using var cloud = new OfficePdfClient("opk_...");
using var local = new OfficePdfClient(new OfficePdfClientOptions
{
    BaseUrl = "http://localhost:8080",
});

OFFICEPDF_API_KEY and OFFICEPDF_BASE_URL are read from the environment when not set explicitly.

Strict mode: rejection is a result, not an exception

In strict mode (the default) the engine refuses documents it cannot render correctly rather than producing a PDF that merely looks right. That is a normal outcome, so it does not throw:

var result = await client.ConvertAsync("contract.docx");

if (result.Rejected)
{
    Console.WriteLine($"Not converted: {result.Error?.Code} {result.Error?.Message}");
    foreach (var d in result.Diagnostics.Errors)
    {
        Console.WriteLine(d);          // p4 error unsupported_equation: ...
    }
}
else if (result.NeedsReview)           // succeeded, but something fell back
{
    await result.SaveAsync("contract.pdf");
    foreach (var d in result.Diagnostics.Warnings)
    {
        Console.WriteLine(d);          // p2 warning font_substituted: ...
    }
}
else
{
    await result.SaveAsync("contract.pdf");
}

Use ConversionMode.Preview to always get a PDF, with fallbacks recorded in the diagnostics and Degraded set to true:

await client.ConvertAsync("contract.docx", new ConvertOptions { Mode = ConversionMode.Preview });

Diagnostics

Every diagnostic carries the page it happened on.

result.Diagnostics                       // all of them (up to 50 on the job)
result.Diagnostics.Errors                // Severity == "error"
result.Diagnostics.Warnings              // Severity == "warning"
result.Diagnostics.OnPage(3)             // just page 3
result.Diagnostics.WithCode("font_substituted")

if (result.HasMoreDiagnostics)           // more than 50
{
    var everything = await result.GetAllDiagnosticsAsync();   // fetches the full report
}

The complete engine report — font manifest, hashes, every diagnostic — is available with await result.GetReportAsync().

Outcomes

Property Meaning
result.Succeeded A PDF was produced
result.Degraded Produced, but something fell back
result.NeedsReview Succeeded && Degraded — worth a human look
result.Rejected Strict mode refused it; result.Error says why
result.Failed The conversion failed (corrupt file, engine error)
result.Cancelled Cancelled by CancelAsync(id)

Saving

await result.SaveAsync("out.pdf");                     // atomic; creates directories
byte[] bytes = await result.DownloadAsync();
await client.ConvertToAsync("in.docx", "out.pdf");     // convert and save in one call

Input

await client.ConvertAsync("path/to/file.docx");            // a path
await client.ConvertAsync(bytes, "contract.docx");         // bytes

Without blocking

var job = await client.CreateConversionAsync("contract.docx");   // returns at once
var result = await client.WaitAsync(job.Id);

Pass OnProgress to observe each poll, and a CancellationToken to abort:

await client.ConvertAsync("big.docx",
    new ConvertOptions
    {
        Timeout = TimeSpan.FromMinutes(5),
        OnProgress = job => Console.WriteLine($"{job.Status} {job.Pages}"),
    },
    cancellationToken);

Listing

var page = await client.ListConversionsAsync(limit: 20, status: "succeeded");
foreach (var result in page.Data)
{
    Console.WriteLine($"{result.Id} {result.Pages}");
}

await foreach (var result in client.IterConversionsAsync())   // follows cursors
{
    // ...
}

Exceptions

Exception When
OfficePdfAuthenticationException 401/403
OfficePdfQuotaExhaustedException 402 — no pages left (cloud only)
OfficePdfNotFoundException 404
OfficePdfOutputNotReadyException 409 — not succeeded, so no PDF
OfficePdfOutputExpiredException 410 — past its retention window
OfficePdfFileTooLargeException 413
OfficePdfUnsupportedFormatException 415
OfficePdfRateLimitException 429
OfficePdfConnectionException the server was unreachable
OfficePdfTimeoutException the conversion did not finish in time

All API exceptions derive from OfficePdfApiException and carry .Status, .Code and .ApiMessage; branch on .Code. Transient failures (429, 5xx, network) are retried automatically with jittered backoff — MaxRetries = 3 by default.

Dependency injection

OfficePdfClient accepts an HttpClient, so it fits IHttpClientFactory:

services.AddHttpClient<OfficePdfClient>((http, _) =>
    new OfficePdfClient(new OfficePdfClientOptions { ApiKey = config["OfficePDF:ApiKey"] }, http));

Tests

dotnet test

The suite starts a real on-premise server with a stubbed engine, so multipart uploads, polling, error envelopes and file writes are genuinely exercised. It needs the engine's Python environment; override with OFFICEPDF_TEST_PYTHON.

Product Compatible and additional computed target framework versions.
.NET net5.0 was computed.  net5.0-windows was computed.  net6.0 was computed.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 was computed.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 is compatible.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed.  net9.0 was computed.  net9.0-android was computed.  net9.0-browser was computed.  net9.0-ios was computed.  net9.0-maccatalyst was computed.  net9.0-macos was computed.  net9.0-tvos was computed.  net9.0-windows was computed.  net10.0 was computed.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
.NET Core netcoreapp2.0 was computed.  netcoreapp2.1 was computed.  netcoreapp2.2 was computed.  netcoreapp3.0 was computed.  netcoreapp3.1 was computed. 
.NET Standard netstandard2.0 is compatible.  netstandard2.1 was computed. 
.NET Framework net461 was computed.  net462 was computed.  net463 was computed.  net47 was computed.  net471 was computed.  net472 was computed.  net48 was computed.  net481 was computed. 
MonoAndroid monoandroid was computed. 
MonoMac monomac was computed. 
MonoTouch monotouch was computed. 
Tizen tizen40 was computed.  tizen60 was computed. 
Xamarin.iOS xamarinios was computed. 
Xamarin.Mac xamarinmac was computed. 
Xamarin.TVOS xamarintvos was computed. 
Xamarin.WatchOS xamarinwatchos was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
1.0.0 109 10/20/2026