PDF4me .NET SDK: C# PDF 図書館と API クライアント
Pdf4me.Client は .NET クライアントライブラリ PDF4me API 106個のドキュメントアクションを型付き非同期メソッドとして公開します。インストールはこちらから。 NuGet作成する Pdf4meClient あなたの API キー、変換、最適化、マージ、分割、 OCR または文書から抽出 C# レンダリングエンジンを同梱せずに。
パッケージ情報
| 分野 | 価値 |
|---|---|
| パッケージ名 | Pdf4me.Client |
| 現在のバージョン | 2.0.0 （最終更新日：2026年10月13日） |
| ライセンス | MIT |
| .NET サポート | .NET 8、9、10、さらに .NET 標準2.0 .NET Framework 4.6.2以降 |
| 総ダウンロード数 | 全バージョン合計で246.4K |
| パッケージサイズ | 1.34 MB |
| 行動 | 18セクションにわたる106 |
| 実行時依存関係 | Microsoft.Kiota.Bundle (>= 2.1.2) および Microsoft.Extensions.Logging.Abstractions (>= 8.0.3) |
| ベース URL | https://api.pdf4me.com |
| ソース | github.com/pdf4me/pdf4me-clientapi-dotnet |
| NuGet | nuget.org/packages/Pdf4me.Client |
前提条件
- .NET 8以降、または .NET Framework 4.6.2以降 .NET 標準2.0。
- A PDF4me アカウントと API 鍵。
インストール
- dotnet CLI
- Package Manager
- PackageReference
dotnet add package Pdf4me.Client
NuGet\Install-Package Pdf4me.Client -Version 2.0.0
<PackageReference Include="Pdf4me.Client" Version="2.0.0" />
認証する
設定する API 環境における鍵：
- Bash / Zsh
- PowerShell
- Windows CMD
export PDF4ME_API_KEY="your-api-key"
$env:PDF4ME_API_KEY = "your-api-key"
set PDF4ME_API_KEY=your-api-key
Windowsでは、 set 現在の期間のみ持続する CMD セッション。 setx PDF4ME_API_KEY "your-api-key" 再起動後も保持される値の場合は、新しいターミナルを開いて、プロセスがその値を認識するようにします。
クライアントはコンストラクタでキーを受け取ります。ログには何も記録されません。 API キーまたはドキュメントの内容、および空または空白のみのキーはエラーをスローします ArgumentException リクエストを送信する前に。
クイックスタート
このプログラムはアップロードします input.pdf 最適化のために、結果を次のように保存します optimized.pdf:
using Pdf4me.Client;
var apiKey = Environment.GetEnvironmentVariable("PDF4ME_API_KEY")
?? throw new InvalidOperationException("Set PDF4ME_API_KEY first.");
using var client = new Pdf4meClient(apiKey);
var result = await client.OptimizeAsync(
File.ReadAllBytes("input.pdf"), docName: "input.pdf", profile: OptimizeProfile.Max);
File.WriteAllBytes("optimized.pdf", result);
クライアントを1つ作成し、すべての呼び出しで再利用します。接続はプールされるため、呼び出しごとにクライアントがネゴシエートされます。 TLS 毎回です。使い終わったら捨ててください。
PDF4me .NET SDKとは何ですか？
それは単一です NuGet パッケージ、 Pdf4me.Client包む PDF4me API v2 は 1 つのクラスの背後にあります。すべてのアクションは非同期メソッドです Pdf4meClient 終点にちなんで名付けられているので、 /api/v2/ConvertOcrPdf は ConvertOcrPdfAsync最初のパラメータはアクションの対象となるもので、それ以外はすべてオプションなので、名前で渡してください。
var searchable = await client.ConvertOcrPdfAsync(
scan, language: "English", qualityType: QualityType.Draft);
var numbered = await client.AddPageNumberAsync(
pdf, pageNumberFormat: "Page # of {1}", alignX: AddPageNumberAlignX.Center);
の Generated パッケージ内のツリーは以下によって生成されます Microsoft Kiota から PDF4me OpenAPI 説明、そのためオプションモデルと結果モデルは、 REST API そして Python そして JavaScript クライアント：同じアクション、同じ名前、同じデフォルト設定。
C#で作成したPDFライブラリは、APIクライアントとどのように異なるのでしょうか？
「c# pdf 「ライブラリ」とは、自己ホスト型のレンダリングライブラリのことです。パッケージを追加すると、それがプロセス内で処理を実行し、レンダリングエンジンはユーザーが所有します。 Pdf4me.Client もう一方の形状は、ドキュメントを PDF4me そして、処理済みのバイト列を返します。この取引は双方向で実際に行われるため、明確にしておく価値があります。
| ローカルライブラリ vs ホスト型 API | 自己ホスト型ライブラリ | Pdf4me.Client |
|---|---|---|
| 仕事が行われる場所 | あなたのプロセスでは | オン PDF4me サービス |
| ネットワーク接続が必要です | いいえ | はい、すべての電話 |
| コスト形状 | パッケージライセンス（開発者ごと、またはデプロイメントごと） | MIT クライアント、 API 無料プランまたは有料プランのクレジット |
| オフラインまたはエアギャップ環境で動作します | はい | いいえ |
| ドキュメントがインフラストラクチャから流出します | いいえ | はい |
| OCR、 AI 抽出、 ZUGFeRD | 通常は別製品（入手可能な場合） | 同じ106のアクションに含まれる |
| あなたは維持します | エンジン、そのフォント、そしてその CVEs | 1 API 鍵 |
ドキュメントがネットワーク外に持ち出せない場合、オフラインで作業する必要がある場合、またはドキュメントあたりのコストが、そのボリュームでのサブスクリプションよりも有利な場合は、ローカルライブラリを選択してください。変換をカバーするために複数の製品を統合する必要がある場合は、このクライアントを選択してください。 OCRバーコード、電子請求書、 AI 抽出作業は不要で、レンダリングエンジンを出荷したりパッチを適用したりすること自体を望まない。
このカテゴリに関してオートコンプリートが最もよく尋ねる2つの質問に対する回答は、ここでは異なっています。クライアント自体は MIT ライセンス付きオープンソースそのため、リンク先のコードには「無料」と「オープンソース」のチェックボックスがオンになっています。ただし、その背後にある処理はホスト型サービスであり、無料プランを超えると料金が発生します。
書類の提出と結果の確認
文書 エリア DocumentSource: ファイルのバイト列、または文字列 API 自身を取得する、これは pdf4meblobid://<id> ブロブ参照または https URLどちらも暗黙的に変換されるため、どちらでもそのまま渡すことができます。文字列はローカルファイルパスとして読み込まれることはないので、ファイルを読み込んでそのバイト列を渡してください。
byte[] fromBytes = await client.OptimizeAsync(File.ReadAllBytes("report.pdf"));
byte[] fromUrl = await client.OptimizeAsync("https://example.com/report.pdf");
byte[] fromBlob = await client.OptimizeAsync("pdf4meblobid://<id>");
結果 2 つの方法のいずれかで戻ります。ドキュメントを生成するアクションは、そのドキュメントを返します。 byte[]、 それで File.WriteAllBytes 直接受け取ります。データで応答するアクションは、代わりに型付きモデルを返します。
DocMetadata metadata = await client.GetPdfMetadataAsync(pdf);
Console.WriteLine($"{metadata.PageCount} pages, PDF {metadata.PdfVersion}");
ReadBarcodesRes scan = await client.ReadBarcodesAsync(pdf);
foreach (var barcode in scan.Barcodes ?? [])
Console.WriteLine($"page {barcode.Page}: {barcode.Value}");
の AI ドキュメントパーサーは独自の応答形状を決定するため、返されるすべてのデータはモデルの AdditionalData:
var parsed = await client.AiDocumentParserAsync(File.ReadAllBytes("invoice.pdf"), "invoice parser");
foreach (var (field, value) in parsed.AdditionalData)
Console.WriteLine($"{field}: {value}");
複数の文書 指定された順序でマージし、入力がテキストまたは URL:
byte[] merged = await client.MergeAsync([File.ReadAllBytes("a.pdf"), File.ReadAllBytes("b.pdf")]);
byte[] qrCode = await client.CreateBarcodeAsync("https://pdf4me.com", barcodeType: CreateBarcodeBarcodeType.QRCode);
byte[] webPage = await client.ConvertUrlToPdfAsync("https://example.com");
オブジェクトであるオプション、 のような ConvertToPdfAction そして ImageAction、そしてすべての結果モデルは、 Pdf4me.Client.Generated.Modelsアクションが取る列挙型には短い名前があります Pdf4me.Client （QualityType、 AlignX、 SplitAction）、一方、生成された名前がすでに短い少数のDocType、 ImageTypeExtract）は生成された名前空間から直接使用されます。
using Pdf4me.Client;
using Pdf4me.Client.Generated.Models;
var pages = await client.CreateImagesAsync(
pdf, new ImageAction { ImageExtension = ImageExtension.Png }, pageNrs: "1");
すべての行動には 3つのオプション引数： extraオプションの追加リクエストフィールドの辞書 API 説明にはまだ記載されていませんが、アクション自体と一緒に送信されています。 maxWaitこれにより、その呼び出しのキューに入れられたジョブの待ち時間が制限されます。 cancellationTokenこれにより、リクエストとすべてのポーリングがキャンセルされます。
クライアント構成
using var client = new Pdf4meClient(apiKey, new Pdf4meClientOptions
{
BaseUrl = Pdf4meClient.DefaultBaseUrl, // https://api.pdf4me.com
Timeout = TimeSpan.FromSeconds(100), // each HTTP request
MaxWait = TimeSpan.FromMinutes(5), // waiting for one queued job
Logger = loggerFactory.CreateLogger<Pdf4meClient>(),
});
で ASP.NET Core、または依存性注入を使用する任意のアプリでは、アプリ全体に対して1つのクライアントを登録し、ロガーはアプリ独自のログ設定から取得します。
builder.Services.AddSingleton(services => new Pdf4meClient(
builder.Configuration["Pdf4me:ApiKey"]!,
new Pdf4meClientOptions { Logger = services.GetRequiredService<ILogger<Pdf4meClient>>() }));
クライアントに ILogger から Microsoft.Extensions.Logging すべてのリクエスト、レスポンス、キューイングされたジョブ、ポーリングを確認するには Debug レベル。
C#で長時間の処理やOCRを扱うにはどうすれば良いですか？
すべてのアクションは非同期ジョブとして送信されます。呼び出しは、サーバーがすぐに応答したか、サーバーが推奨する間隔でポーリングしながら作業をキューに入れたかに関わらず、完了した結果を返します。これは、次の 2 つの理由で重要です。 await 何分もブロックされる可能性があり、待ち時間を終わらせるものは MaxWait、 ない Timeout。
Timeout適用対象 それぞれ HTTP リクエスト。MaxWait適用対象 キューに入れられたジョブ全体、 そしてmaxWait:アクションを実行すると、その呼び出しに対しては設定が上書きされます。- の OCR 行動、
ConvertOcrPdfAsyncそしてImageExtractTextAsync少なくとも10分待ってください（DefaultOcrMaxWait）またはそれ以上MaxWaitより高い。
using var cancel = new CancellationTokenSource(TimeSpan.FromMinutes(20));
byte[] searchable = await client.ConvertOcrPdfAsync(
File.ReadAllBytes("scan.pdf"), language: "English",
maxWait: TimeSpan.FromMinutes(20), cancellationToken: cancel.Token);
エラー
拒否または失敗したリクエストは、 Pdf4meException、 から Pdf4me.Client.Generated.Models:
| 財産 | ホールド |
|---|---|
Message | の APIのメッセージ、そうでなければ応答本文は 500 文字に切り詰められ、そうでなければ HTTP 状態 |
ResponseStatusCode | の HTTP ステータスコード |
TraceId | の APIトレースID。問題を報告する際に引用してください。 |
ResponseBody | 送信された応答本文全体 |
ResponseHeaders | レスポンスヘッダー |
待機時間が経過してもジョブがまだ実行中の場合、 TimeoutException無効な引数（空のドキュメントなど）は、 ArgumentException リクエストを送信する前に。
try
{
byte[] result = await client.OptimizeAsync(pdf);
}
catch (Pdf4meException e)
{
Console.Error.WriteLine($"PDF4me returned {e.ResponseStatusCode}: {e.Message} (trace {e.TraceId})");
}
catch (TimeoutException e)
{
Console.Error.WriteLine(e.Message);
}
18のセクションと106のアクションすべて
アクションは、 PDF4me REST API 参照、そして各セクションのメソッドはソースコード内のそれぞれ別のファイルに記述されています。中には、名前からは想像もつかないようなセクションに配置されているものもあります。 OCR 検索に入っています。 PDF/A 作成は変換で行われ、 MergeV3Async は PDF マージ＆スプリットではなく。
| セクション | 行動 | 方法 Pdf4meClient |
|---|---|---|
| AI 文書抽出 | 14 | AiDocumentParserAsync、 ProcessBankChequeAsync、 ProcessBankStatementAsync、 ProcessContractAsync、 ProcessCreditCardAsync、 ProcessHealthCardAsync、 ProcessInvoiceAsync、 ProcessMarriageCertificateAsync、 ProcessMortgageDocumentAsync、 ProcessOrderAsync、 ProcessPayStubAsync、 ProcessReceiptAsync、 ProcessShippingLabelAsync、 ProcessTaxDocumentAsync |
| バーコード | 7 | AddBarcodeAsync、 CreateBarcodeAsync、 CreateSwissQrBillAsync、 ReadBarcodesAsync、 ReadSwissQrBillAsync、 CreateEpcQrCodeAsync、 ReadBarcodesFromImageAsync |
| 変換する | 13 | ConvertHtmlToPdfAsync、 ConvertJsonToExcelAsync、 ConvertMdToPdfAsync、 ConvertPdfToExcelAsync、 ConvertPdfToPowerpointAsync、 ConvertPdfToWordAsync、 ConvertToPdfAsync、 ConvertUrlToPdfAsync、 ConvertVisioAsync、 ConvertWordToPdfFormAsync、 CreatePdfAAsync、 FlattenPdfAsync、 LinearizePdfAsync |
| 編集 | 7 | AddAttachmentToPdfAsync、 AddHtmlHeaderFooterAsync、 ImageStampAsync、 AddMarginAsync、 AddPageNumberAsync、 StampAsync、 SignPdfAsync |
| Excel | 1 | FindAndReplaceTextInExcelAsync |
| 抽出する | 8 | ClassifyDocumentAsync、 ExtractAttachmentFromPdfAsync、 ExtractPdfFormDataAsync、 ExtractResourcesAsync、 ExtractTableFromPdfAsync、 ExtractTextByExpressionAsync、 ExtractTextFromWordAsync、 ParseDocumentAsync |
| 検索 | 2 | FindAndReplaceAsync、 ConvertOcrPdfAsync |
| フォーム | 2 | AddFormFieldAsync、 FillPdfFormAsync |
| 生成する | 6 | EnableTrackingChangesInWordAsync、 GenerateDocumentSingleAsync、 GenerateDocumentMultipleAsync、 GetTrackingChangesInWordAsync、 ReplaceTextWithImageInWordAsync、 GenerateDocumentSingleV2Async |
| 画像 | 13 | AddImageWatermarkToImageAsync、 AddTextWatermarkToImageAsync、 CompressImageAsync、 ConvertImageFormatAsync、 CreateImagesAsync、 CropImageAsync、 FlipImageAsync、 GetImageMetadataAsync、 ImageExtractTextAsync、 RemoveExifTagsFromImageAsync、 ResizeImageAsync、 RotateImageAsync、 RotateImageByExifDataAsync |
| 結合と分割 | 5 | MergeAsync、 MergeOverlayAsync、 SplitPdfAsync、 SplitPdfByBarcodeAsync、 SplitByTextAsync |
| 最適化する | 1 | OptimizeAsync |
| 整理する | 5 | DeleteBlankPagesAsync、 DeletePagesAsync、 ExtractPagesAsync、 RotateAsync、 RotatePageAsync |
| 16 | MergeV3Async、 GetPdfMetadataAsync、 RepairPdfAsync、 CreateHyperlinkAnnotationAsync、 DeleteHyperlinkAnnotationAsync、 DigitalSignPdfAsync、 ExtractHyperlinkAnnotationAsync、 GetDocumentByTextAsync、 GetTextAndCoordinatesAsync、 GetTextByPositionAsync、 HighlightTextAsync、 PrepareForPrintAsync、 ReplaceTextWithImageAsync、 ResizePdfAsync、 SetPdfMetadataAsync、 SignDocumentAsync | |
| PDF4me | 1 | UpdateHyperlinkAnnotationAsync |
| 安全 | 2 | ProtectAsync、 UnlockAsync |
| 言葉 | 2 | DisableTrackingChangesInWordAsync、 FindAndReplaceTextInWordAsync |
| ZUGFeRD | 1 | CreateZugferdInvoiceAsync |
各アクションのパラメータと応答形状については、以下を参照してください。 PDF4me REST API 参照または、エディタでメソッドにカーソルを合わせると、各メソッドにはドキュメントページと一致するドキュメントの概要が表示されます。
1.x からの移行
バージョン2.0は、 PDF4me API v2以降、1.xのものは何も動作しなくなります。見出しの変更点：
- それは話す API v2。 1.x は、v1 エンドポイントを次のように呼んでいました。
/Optimize/OptimizeByProfile; 2.0 コール/api/v2/...。 - 単独の顧客とエリアごとの顧客はなくなりました。
Pdf4me.Instance.Init(token)そしてPdf4me.Instance.OptimizeClient一つになるnew Pdf4meClient(apiKey)すべての行動が、その行動方法の一つとして捉えられている。 - 名前空間は
Pdf4me.Client、 ないPdf4meClient。 - Newtonsoft.Json もはや依存関係ではないそして、1.x が引き込んだ脆弱な 12.0.3 もそれに伴って登場します。
- エラーはエラーの一種です。
Pdf4meApiExceptionそしてPdf4meBackendExceptionなるPdf4meException。 - .NET Framework 4.5.2および4.6.1はサポート対象外となりました。 最低値は4.6.2で、 .NET 標準2.0。
| 1.x | 2.0 |
|---|---|
Pdf4me.Instance.Init(token) | using var client = new Pdf4meClient(apiKey); |
OptimizeClient.OptimizeByProfileAsync(file, profile) | client.OptimizeAsync(file, profile: ...) |
MergeClient.Merge2PdfsAsync(file1, file2) | client.MergeAsync([file1, file2]) |
SplitClient.SplitByPageNrAsync(file, pageNr) | client.SplitPdfAsync(file, splitActionNumber: pageNr) |
ExtractClient.ExtractPagesAsync(file, pageNrs) | client.ExtractPagesAsync(file, pageNumbers: pageNrs) |
ConvertClient.ConvertFileToPdfAsync(file, fileName) | client.ConvertToPdfAsync(file, docName: fileName) |
PdfAClient.CreatePdfAAsync(file, compliance) | client.CreatePdfAAsync(file, compliance: ...) |
PdfAClient.RotateDocumentAsync(file, rotate) | client.RotateAsync(file, rotationType: ...) |
PdfAClient.ProtectDocumentAsync(file, password, perms) | client.ProtectAsync(file, password: ..., pdfPermission: ...) |
PdfAClient.UnlockDocumentAsync(file, password) | client.UnlockAsync(file, password: ...) |
PdfAClient.RepairDocumentAsync(file) | client.RepairPdfAsync(file) |
ImageClient.CreateThumbnailAsync(file, width, pageNr, fmt) | client.CreateImagesAsync(file, new ImageAction { ... }, pageNrs: ...) |
あなたの API キーは変更されません。 using Pdf4meClient; と using Pdf4me.Client;、 追加 using Pdf4me.Client.Generated.Models; オプションや結果モデル、またはキャッチを使用する場所 Pdf4meException次に、上記の表を順に見ていきましょう。
トラブルシューティング
TimeoutException 大きな文書に。 その仕事は待ち時間よりも長く続き、 MaxWait デフォルトは5分で、 Timeout通話で提起する maxWait: TimeSpan.FromMinutes(20)または、クライアント側で通話ごとに。
1 OCR 通話が10分間も繋がらないようです。 それが記録に残っている床面積です。 ConvertOcrPdfAsync そして ImageExtractTextAsync 少なくとも待って DefaultOcrMaxWait10分なので、彼らに自分の時間を与えてください cancellationToken 発信者がもっと早く諦める必要がある場合。
401 Pdf4meException.ResponseStatusCode。 キーは存在しますが拒否されました。 PDF4me ダッシュボード そして、変数がプロセスから見えることを確認します。Windows では、 set セッション間で保持されないため、 setx そして新しいターミナルを開きます。
ArgumentException ネットワークに何かが流れ出す前に。 ローカルチェックが失敗しました。多くの場合、ファイルが空で、読み取ったファイルが0バイトだったことを意味します。ファイルのパスを確認し、ファイルが他のプロセスによってロックされていないことを確認してください。
ファイルパスを指定しましたが、そのファイルには何も変化が起こりませんでした。 文字列引数はブロブ参照または https URLローカルパスは決して使用しません。ファイルを読み込み、そのバイト列を渡します。
CreateThumbnailAsync 見つかりません。 1.x のメソッド名は 2.0 には存在しません。サムネイルは現在 CreateImagesAsync と共に ImageAction移行表を参照してください。
モデル型または列挙型に関するコンパイルエラー。 オプションオブジェクトと結果モデルは Pdf4me.Client.Generated.Modelsアクションが取る列挙型のほとんどは Pdf4me.Client両方をインポートします。
よくある質問
PDF4me .NET SDKは無料ですか？
の Pdf4me.Client パッケージは無料で、 MIT ライセンスされているため、インストールや再配布に費用はかかりません。このパッケージは、 PDF4me APIこれは無料プランと有料プランが用意されたホスト型サービスなので、ドキュメント処理には API アカウントにクレジットが付与されます。リンク先のコード自体は無料ですが、処理には料金が発生します。
PDF4meの.NETクライアントはオープンソースですか？
はい。クライアントは MIT ライセンスとそのソースは github.com/pdf4me/pdf4me-clientapi-dotnet貢献を検討されている方への注意点が1つあります。 src/Pdf4me.Client/Generated/ は Kiota から OpenAPI 説明は再生成のたびに完全に置き換えられるため、そのツリーに問題がある場合はパッチを適用するのではなく、イシューを作成してください。クライアントとその周辺のセクションファイルは手書きで作成されており、プルリクエストを送信するのに最適な場所です。
Pdf4me.Clientはどの.NETバージョンをサポートしていますか？
バージョン2.0.0の対象 .NET 8、 .NET 9と .NET 10、プラス .NET 標準2.0なので、 .NET Framework 4.6.2以降。 .NET Framework 4.5.2および4.6.1は1.xではサポートされていましたが、2.0ではサポートされていません。
C#でHTMLをPDFに変換するにはどうすればよいですか？
電話 ConvertHtmlToPdfAsync と共に HTML ファイルのバイト数、または ConvertUrlToPdfAsync と共に URL 文字列を書き、返された文字列を書き込む byte[] ディスクに保存:
byte[] fromHtml = await client.ConvertHtmlToPdfAsync(File.ReadAllBytes("page.html"));
byte[] fromUrl = await client.ConvertUrlToPdfAsync("https://example.com");
File.WriteAllBytes("page.pdf", fromUrl);
レンダリングはサービス上で行われるため、ブラウザエンジンをインストールしたり、コンテナ化したり、パッチを適用したりする必要はありません。これは、ローカルライブラリを使用する場合に通常必要となるコストです。
C#でPDFを読み込むにはどうすればよいですか？
「読む」という言葉の意味によりますね。 GetPdfMetadataAsync を返します DocMetadata ページ数と PDF バージョン。 ExtractTextByExpressionAsync、 GetTextByPositionAsync そして GetTextAndCoordinatesAsync テキストを抜き出す。最後のテキストには位置情報が含まれている。 ExtractTableFromPdfAsync 表形式のコンテンツを処理し、 ConvertOcrPdfAsync スキャンしたもの PDF 検索可能なものを優先します。これらのアクションは、型付きモデルではなく、 byte[]。
ライブラリを使わずにC#でPDFを作成することはできますか？
あなたは書くことができます PDF バイト形式を手作業で変換すれば、プレーンテキストの1ページであれば妥当な作業です。しかし、フォント、エンコーディング、圧縮、相互参照テーブルがすべて正しくなければならず、読者が許容する形式の違いも異なるため、すぐに妥当ではなくなります。実際には、ローカルレンダリングライブラリを配布してパッチを適用し続けるか、 API このようなクライアントでは、レンダリングはサーバー側で行われます。 PDF 仕様は以下のように公開されています ISO 32000-2 その規模を知りたいなら。