Passa al contenuto principale

PDF4me .NET SDK: C# PDF Biblioteca e API Cliente

Pdf4me.Client è un .NET libreria client per il PDF4me API che espone 106 azioni del documento come metodi asincroni tipizzati. Installalo da NuGet, creane uno Pdf4meClient con il tuo API chiave e convertire, ottimizzare, unire, dividere, OCR o estrarre da documenti in C# senza includere un motore di rendering.

Informazioni sulla confezione​

CampoValore
Nome del pacchettoPdf4me.Client
Versione attuale2.0.0 (ultimo aggiornamento 13/10/2026)
LicenzaMIT
.NET supporto.NET 8, 9 e 10, più .NET Standard 2.0 per .NET Framework 4.6.2 e versioni successive
Download totali246.4K in totale su tutte le versioni
Dimensioni della confezione1,34 MB
Azioni106 suddivisi in 18 sezioni
Dipendenze di runtimeMicrosoft.Kiota.Bundle (>= 2.1.2) e Microsoft.Extensions.Logging.Abstractions (>= 8.0.3)
Base URLhttps://api.pdf4me.com
Fontegithub.com/pdf4me/pdf4me-clientapi-dotnet
NuGetnuget.org/packages/Pdf4me.Client

Prerequisiti​

  • .NET 8 o versioni successive, oppure .NET Framework 4.6.2 o versioni successive fino a .NET Standard 2.0.
  • UN PDF4me conto e API chiave.

Installare​

dotnet add package Pdf4me.Client

Autenticare​

Imposta il tuo API chiave nell'ambiente:

export PDF4ME_API_KEY="your-api-key"

Su Windows, set dura solo per la corrente CMD sessione. Utilizzare setx PDF4ME_API_KEY "your-api-key" Se il valore persiste dopo un riavvio, apri un nuovo terminale in modo che il processo lo rilevi.

Il client prende la chiave nel suo costruttore. Nulla di ciò che registra porta il API chiave o contenuto di un documento e una chiave vuota o composta solo da spazi bianchi genera ArgumentException prima che venga inviata qualsiasi richiesta.

Avvio rapido​

Questo programma carica input.pdf per l'ottimizzazione e salva il risultato come 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);

Crea un client e riutilizzalo per ogni chiamata. Mantiene una connessione condivisa, quindi un client per ogni chiamata negozierà TLS Ogni volta. Smaltiscilo quando hai finito.

Che cos'è l'SDK .NET di PDF4me?​

È un singolo NuGet pacchetto, Pdf4me.Client, che avvolge il PDF4me API v2 dietro una classe. Ogni azione è un metodo asincrono su Pdf4meClient chiamato così in base al suo punto finale, quindi /api/v2/ConvertOcrPdf È ConvertOcrPdfAsyncI primi parametri indicano su cosa opera l'azione, mentre tutto il resto è opzionale, quindi va passato per nome:

var searchable = await client.ConvertOcrPdfAsync(
scan, language: "English", qualityType: QualityType.Draft);

var numbered = await client.AddPageNumberAsync(
pdf, pageNumberFormat: "Page # of {1}", alignX: AddPageNumberAlignX.Center);

IL Generated l'albero all'interno della confezione è prodotto da Microsoft Kiota dal PDF4me OpenAPI descrizione, motivo per cui i modelli di opzione e di risultato sono coerenti con la REST API e con il Python E JavaScript Clienti: le stesse azioni, con gli stessi nomi e impostazioni predefinite.

In che modo una libreria PDF in C# si differenzia da un client API?​

Risultati più significativi per "c# pdf Le "librerie" sono librerie di rendering auto-ospitate: si aggiunge il pacchetto, questo svolge il lavoro nel proprio processo e si ha il controllo del motore di rendering. Pdf4me.Client è l'altra forma. Invia il documento a PDF4me e restituisce i byte finali. Lo scambio è reale in entrambe le direzioni, quindi vale la pena essere chiari al riguardo:

Biblioteca locale vs. ospitata APIBiblioteca self-hostedPdf4me.Client
Dove si lavoraNel tuo processoSul PDF4me servizio
È necessaria la reteNOSì, ogni chiamata
forma dei costiLicenza del pacchetto, a volte per sviluppatore o per implementazioneMIT cliente, API crediti su un piano gratuito o a pagamento
Funziona offline o isolato dalla reteSÌNO
I documenti escono dalla tua infrastrutturaNOSÌ
OCR, AI estrazione, ZUGFeRDSolitamente si tratta di un prodotto separato, se disponibile.Incluse nelle stesse 106 azioni
Tu affermiIl motore, i suoi caratteri e il suo CVESUN API chiave

Scegli una biblioteca locale quando i documenti non possono lasciare la tua rete, quando devi lavorare offline o quando il costo per documento al tuo volume è inferiore a un abbonamento. Scegli questo client quando altrimenti dovresti integrare diversi prodotti per coprire la conversione, OCR, codici a barre, fatturazione elettronica e AI estrazione, e preferiresti non distribuire o applicare patch a un motore di rendering.

Si noti che le due domande che il completamento automatico pone più spesso su questa categoria qui hanno una risposta diversa. Il client stesso è MIT con licenza e open sourcePertanto, le caselle "gratuito" e "open source" sono selezionate per il codice a cui fai riferimento. L'elaborazione sottostante è un servizio ospitato, che non è gratuito oltre il suo livello gratuito.

Consegna dei documenti e lettura dei risultati​

Documenti sono un DocumentSource: sia i byte del file, sia una stringa API recupera se stesso, che può essere un pdf4meblobid://<id> riferimento blob o un https URLEntrambi i metodi convertono implicitamente, quindi uno dei due può essere passato direttamente. Una stringa non viene mai letta come percorso di file locale, quindi è necessario leggere il file e passarne i byte.

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>");

Risultati tornare in uno dei due modi. Le azioni che producono un documento restituiscono il suo byte[], COSÌ File.WriteAllBytes Lo prende direttamente. Le azioni che rispondono con dati restituiscono invece un modello tipizzato:

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}");

IL AI Il parser del documento decide la propria forma di risposta, quindi tutto ciò che restituisce arriva nel modello AdditionalData:

var parsed = await client.AiDocumentParserAsync(File.ReadAllBytes("invoice.pdf"), "invoice parser");
foreach (var (field, value) in parsed.AdditionalData)
Console.WriteLine($"{field}: {value}");

Diversi documenti unisci nell'ordine dato e alcune azioni non richiedono alcun documento perché l'input è testo o un 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");

Opzioni che sono oggetti, ad esempio ConvertToPdfAction E ImageActione tutti i modelli risultanti vivono in Pdf4me.Client.Generated.Models. Gli enum che un'azione esegue hanno nomi brevi in Pdf4me.Client QualityType, AlignX, SplitAction), mentre i pochi il cui nome generato è già breve (DocType, ImageTypeExtract) vengono utilizzati direttamente dallo spazio dei nomi generato:

using Pdf4me.Client;
using Pdf4me.Client.Generated.Models;

var pages = await client.CreateImagesAsync(
pdf, new ImageAction { ImageExtension = ImageExtension.Png }, pageNrs: "1");

Ogni azione comporta anche tre argomenti opzionali: extra, un dizionario di campi di richiesta aggiuntivi per le opzioni API la descrizione non è ancora elencata, inviata così com'è insieme all'azione stessa; maxWait, che limita l'attesa per il lavoro in coda di quella chiamata; e cancellationToken, il che annulla la richiesta e qualsiasi polling.

Configurazione client​

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>(),
});

In ASP.NET Core, o qualsiasi app che utilizzi l'iniezione delle dipendenze, registra un client per l'intera app e lascia che il logger provenga dalla configurazione di logging dell'app stessa:

builder.Services.AddSingleton(services => new Pdf4meClient(
builder.Configuration["Pdf4me:ApiKey"]!,
new Pdf4meClientOptions { Logger = services.GetRequiredService<ILogger<Pdf4meClient>>() }));

Dare al cliente un ILogger da Microsoft.Extensions.Logging per visualizzare ogni richiesta, risposta, lavoro in coda e sondaggio su Debug livello.

Come si gestiscono i processi di lunga durata e l'OCR in C#?​

Ogni azione viene inviata come un lavoro asincrono. Una chiamata restituisce il risultato finale indipendentemente dal fatto che il server abbia risposto immediatamente o abbia messo in coda il lavoro, eseguendo il polling tra le risposte all'intervallo suggerito dal server. Questo è importante per due motivi: un singolo await può bloccarsi per minuti, e la cosa che pone fine all'attesa è MaxWait, non Timeout.

  • Timeout si applica a ogni HTTP richiesta.
  • MaxWait si applica a l'intero lavoro in coda, E maxWait: su un'azione lo sovrascrive per quella chiamata.
  • IL OCR azioni, ConvertOcrPdfAsync E ImageExtractTextAsync, attendi almeno 10 minuti (DefaultOcrMaxWait), o più a lungo quando MaxWait è più alto.
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);

Errori​

Una richiesta rifiutata o fallita genera Pdf4meException, da Pdf4me.Client.Generated.Models:

ProprietàContiene
MessageIL APImessaggio, altrimenti il corpo della risposta viene troncato a 500 caratteri, altrimenti il HTTP stati
ResponseStatusCodeIL HTTP codice di stato
TraceIdIL APIID di tracciamento. Indicalo quando segnali un problema
ResponseBodyL'intero corpo della risposta è stato inviato
ResponseHeadersLe intestazioni della risposta

Un lavoro ancora in corso quando l'attesa finisce TimeoutException. Gli argomenti non validi, come un documento vuoto, generano un errore ArgumentException prima che venga inviata qualsiasi richiesta.

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);
}

Le 18 sezioni e tutte le 106 azioni​

Le azioni sono raggruppate per sezioni del PDF4me REST API riferimentoe i metodi di ciascuna sezione risiedono in un file separato nel codice sorgente. Alcuni si trovano in una sezione che potresti non intuire dal nome: OCR è in Trova Ricerca, PDF/A la creazione è in Converti e MergeV3Async è in PDF anziché Unisci e dividi.

SezioneAzioniMetodi su Pdf4meClient
AI Estrazione di documenti14AiDocumentParserAsync, ProcessBankChequeAsync, ProcessBankStatementAsync, ProcessContractAsync, ProcessCreditCardAsync, ProcessHealthCardAsync, ProcessInvoiceAsync, ProcessMarriageCertificateAsync, ProcessMortgageDocumentAsync, ProcessOrderAsync, ProcessPayStubAsync, ProcessReceiptAsync, ProcessShippingLabelAsync, ProcessTaxDocumentAsync
Codice a barre7AddBarcodeAsync, CreateBarcodeAsync, CreateSwissQrBillAsync, ReadBarcodesAsync, ReadSwissQrBillAsync, CreateEpcQrCodeAsync, ReadBarcodesFromImageAsync
Convertire13ConvertHtmlToPdfAsync, ConvertJsonToExcelAsync, ConvertMdToPdfAsync, ConvertPdfToExcelAsync, ConvertPdfToPowerpointAsync, ConvertPdfToWordAsync, ConvertToPdfAsync, ConvertUrlToPdfAsync, ConvertVisioAsync, ConvertWordToPdfFormAsync, CreatePdfAAsync, FlattenPdfAsync, LinearizePdfAsync
Modificare7AddAttachmentToPdfAsync, AddHtmlHeaderFooterAsync, ImageStampAsync, AddMarginAsync, AddPageNumberAsync, StampAsync, SignPdfAsync
Eccellere1FindAndReplaceTextInExcelAsync
Estrarre8ClassifyDocumentAsync, ExtractAttachmentFromPdfAsync, ExtractPdfFormDataAsync, ExtractResourcesAsync, ExtractTableFromPdfAsync, ExtractTextByExpressionAsync, ExtractTextFromWordAsync, ParseDocumentAsync
Trova l'antenna2FindAndReplaceAsync, ConvertOcrPdfAsync
Moduli2AddFormFieldAsync, FillPdfFormAsync
Generare6EnableTrackingChangesInWordAsync, GenerateDocumentSingleAsync, GenerateDocumentMultipleAsync, GetTrackingChangesInWordAsync, ReplaceTextWithImageInWordAsync, GenerateDocumentSingleV2Async
Immagine13AddImageWatermarkToImageAsync, AddTextWatermarkToImageAsync, CompressImageAsync, ConvertImageFormatAsync, CreateImagesAsync, CropImageAsync, FlipImageAsync, GetImageMetadataAsync, ImageExtractTextAsync, RemoveExifTagsFromImageAsync, ResizeImageAsync, RotateImageAsync, RotateImageByExifDataAsync
Unisci e dividi5MergeAsync, MergeOverlayAsync, SplitPdfAsync, SplitPdfByBarcodeAsync, SplitByTextAsync
Ottimizzare1OptimizeAsync
Organizzare5DeleteBlankPagesAsync, DeletePagesAsync, ExtractPagesAsync, RotateAsync, RotatePageAsync
PDF16MergeV3Async, GetPdfMetadataAsync, RepairPdfAsync, CreateHyperlinkAnnotationAsync, DeleteHyperlinkAnnotationAsync, DigitalSignPdfAsync, ExtractHyperlinkAnnotationAsync, GetDocumentByTextAsync, GetTextAndCoordinatesAsync, GetTextByPositionAsync, HighlightTextAsync, PrepareForPrintAsync, ReplaceTextWithImageAsync, ResizePdfAsync, SetPdfMetadataAsync, SignDocumentAsync
PDF4me1UpdateHyperlinkAnnotationAsync
Sicurezza2ProtectAsync, UnlockAsync
Parola2DisableTrackingChangesInWordAsync, FindAndReplaceTextInWordAsync
ZUGFeRD1CreateZugferdInvoiceAsync

Per i parametri e la forma di risposta di ciascuna azione, vedere il PDF4me REST API riferimentooppure passa il mouse sopra il metodo nel tuo editor: ogni metodo ha un riepilogo della documentazione che corrisponde alla sua pagina di documentazione.

Migrazione dalla versione 1.x​

La versione 2.0 è una riscrittura del PDF4me API v2 e nulla della versione 1.x continua a funzionare. Il titolo cambia:

  • Parla con API v2. 1.x chiamati endpoint v1 come /Optimize/OptimizeByProfile; 2.0 chiamate /api/v2/....
  • I clienti singoli e quelli per area sono stati eliminati. Pdf4me.Instance.Init(token) E Pdf4me.Instance.OptimizeClient diventare uno new Pdf4meClient(apiKey) con ogni azione come metodo su di essa.
  • Lo spazio dei nomi è Pdf4me.Client, non Pdf4meClient.
  • Newtonsoft.Json non è più una dipendenzae la versione vulnerabile 12.0.3, inclusa nella versione 1.x, viene rimossa insieme ad essa.
  • Gli errori sono un tipo. Pdf4meApiException E Pdf4meBackendException diventare Pdf4meException.
  • .NET Le versioni 4.5.2 e 4.6.1 del framework non sono più supportate. Il minimo è 4.6.2, tramite .NET Standard 2.0.
1.x2.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: ...)

Tuo API la chiave rimane la stessa. Sostituisci using Pdf4meClient; con using Pdf4me.Client;, aggiungere using Pdf4me.Client.Generated.Models; ovunque si utilizzino modelli di opzione o di risultato o catturi Pdf4meException, quindi esamina la tabella qui sopra.

Risoluzione dei problemi​

TimeoutException su un documento di grandi dimensioni. Il lavoro è sopravvissuto all'attesa, che è MaxWait e il valore predefinito è 5 minuti, non Timeout. Sollevalo durante la chiamata con maxWait: TimeSpan.FromMinutes(20), oppure sul client per ogni chiamata.

UN OCR La chiamata sembra rimanere in sospeso per dieci minuti. Questo è il piano documentato. ConvertOcrPdfAsync E ImageExtractTextAsync aspettare almeno DefaultOcrMaxWait, che è 10 minuti, quindi date loro il loro cancellationToken se chi chiama deve rinunciare prima.

Un 401 in Pdf4meException.ResponseStatusCode. La chiave è presente ma rifiutata. Rigenerala nel PDF4me pannello di controllo e confermare che la variabile sia visibile al processo. Su Windows, set non persiste tra le sessioni, quindi usa setx e apri un nuovo terminale.

ArgumentException prima che qualsiasi cosa raggiunga la rete. Un controllo locale non è riuscito, il più delle volte a causa di un documento vuoto, il che significa che la lettura del file ha restituito zero byte. Verificare il percorso e che il file non sia bloccato da un altro processo.

Hai specificato un percorso di file, ma non è successo nulla a quel file. Un argomento stringa viene trattato come un riferimento blob o un https URL, mai un percorso locale. Leggi il file e passa i suoi byte.

CreateThumbnailAsync non è stato trovato. I nomi dei metodi 1.x non esistono nella versione 2.0. Le miniature sono ora CreateImagesAsync con un ImageActionConsultare la tabella di migrazione.

Si è verificato un errore di compilazione su un tipo modello o enum. Gli oggetti opzione e i modelli di risultato sono in Pdf4me.Client.Generated.Models, mentre la maggior parte delle enumerazioni che un'azione prende sono in Pdf4me.ClientImporta entrambi.

Domande frequenti​

L'SDK .NET di PDF4me è gratuito?​

IL Pdf4me.Client il pacchetto è gratuito e MIT con licenza, quindi non ci sono costi per installarlo o ridistribuirlo. Il pacchetto è un client per il PDF4me API, che è un servizio ospitato con un livello gratuito e piani a pagamento superiori, quindi l'elaborazione dei documenti consuma API crediti sul tuo account. Il codice che colleghi non ha alcun costo; l'elaborazione è a consumo.

Il client .NET di PDF4me è open source?​

Sì. Il client è pubblicato sotto il MIT la licenza e la sua fonte sono a github.com/pdf4me/pdf4me-clientapi-dotnetUn avvertimento se intendete contribuire: src/Pdf4me.Client/Generated/ è prodotto da Kiota dal OpenAPI La descrizione viene sostituita interamente ad ogni rigenerazione, quindi per qualsiasi problema in quell'albero aprite una segnalazione invece di applicare una patch. Il client e i file di sezione circostanti sono scritti manualmente e sono il posto giusto per una pull request.

Quali versioni di .NET supportano Pdf4me.Client supporto?​

La versione 2.0.0 è destinata a .NET 8, .NET 9 e .NET 10, più .NET Standard 2.0, il che significa che funziona anche su .NET Framework 4.6.2 e versioni successive. .NET I framework 4.5.2 e 4.6.1 erano supportati dalla versione 1.x e non sono supportati dalla versione 2.0.

Come si converte un file HTML in PDF in C#?​

Chiamata ConvertHtmlToPdfAsync con il HTML byte del file, o ConvertUrlToPdfAsync con un URL stringa e scrivi la stringa restituita byte[] su disco:

byte[] fromHtml = await client.ConvertHtmlToPdfAsync(File.ReadAllBytes("page.html"));
byte[] fromUrl = await client.ConvertUrlToPdfAsync("https://example.com");
File.WriteAllBytes("page.pdf", fromUrl);

Il rendering avviene sul servizio, quindi non è necessario installare, containerizzare o applicare patch a un motore del browser, come di solito accade quando si utilizza una libreria locale.

Come si legge un file PDF in C#?​

Dipende da cosa si intende con "leggere". GetPdfMetadataAsync restituisce un DocMetadata con il conteggio delle pagine e PDF versione. ExtractTextByExpressionAsync, GetTextByPositionAsync E GetTextAndCoordinatesAsync estrarre il testo, l'ultimo con le posizioni. ExtractTableFromPdfAsync gestisce i contenuti tabellari e ConvertOcrPdfAsync fa uno scansionato PDF ricercabile prima. Queste azioni restituiscono modelli tipizzati piuttosto che un byte[].

È possibile creare un PDF in C# senza utilizzare una libreria?​

Puoi scrivere il PDF formato byte a mano, e per una singola pagina di testo semplice è un esercizio ragionevole. Smette di essere ragionevole rapidamente, perché font, codifiche, compressione e la tabella di riferimenti incrociati devono essere tutti corretti, e i lettori variano in quanto tollerano le malformazioni. In pratica la scelta è tra una libreria di rendering locale che distribuisci e mantieni aggiornata e un API client come questo in cui il rendering avviene lato server. PDF la specifica è pubblicata come ISO 32000-2 se vuoi renderti conto delle sue dimensioni.

Dove andare dopo?​