OfficePDF.Sdk
1.0.0
dotnet add package OfficePDF.Sdk --version 1.0.0
NuGet\Install-Package OfficePDF.Sdk -Version 1.0.0
<PackageReference Include="OfficePDF.Sdk" Version="1.0.0" />
<PackageVersion Include="OfficePDF.Sdk" Version="1.0.0" />
<PackageReference Include="OfficePDF.Sdk" />
paket add OfficePDF.Sdk --version 1.0.0
#r "nuget: OfficePDF.Sdk, 1.0.0"
#:package OfficePDF.Sdk@1.0.0
#addin nuget:?package=OfficePDF.Sdk&version=1.0.0
#tool nuget:?package=OfficePDF.Sdk&version=1.0.0
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 | Versions 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. |
-
.NETStandard 2.0
- Microsoft.Bcl.AsyncInterfaces (>= 8.0.0)
- System.Text.Json (>= 8.0.5)
-
net8.0
- No dependencies.
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 |