PDF4me .NET SDK: C# PDF Biblioteca e API Cliente
Pdf4me.Cliente é um .NET biblioteca cliente para o PDF4me API que expõe 106 ações de documento como métodos assíncronos tipados. Instale-o a partir de NuGet, crie um Pdf4meClient com o seu API chave, e converter, otimizar, mesclar, dividir, OCR ou extrair de documentos em C# sem incluir um mecanismo de renderização.
Informações sobre o pacote
| Campo | Valor |
|---|---|
| Nome do pacote | Pdf4me.Client |
| Versão atual | 2.0.0 (última atualização em 13/10/2026) |
| Licença | MIT |
| .NET apoiar | .NET 8, 9 e 10, mais .NET Padrão 2.0 para .NET Framework 4.6.2 e versões posteriores |
| Total de downloads | 246,4 mil em todas as versões |
| Tamanho da embalagem | 1,34 MB |
| Ações | 106 em 18 seções |
| Dependências de tempo de execução | Microsoft.Kiota.Bundle (>= 2.1.2) e Microsoft.Extensions.Logging.Abstractions (>= 8.0.3) |
| Base URL | https://api.pdf4me.com |
| Fonte | github.com/pdf4me/pdf4me-clientapi-dotnet |
| NuGet | nuget.org/packages/Pdf4me.Client |
Pré-requisitos
- .NET 8 ou mais recente, ou .NET Framework 4.6.2 ou mais recente até .NET Padrão 2.0.
- A PDF4me conta e API chave.
Instalar
- 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" />
Autenticar
Defina seu API chave no ambiente:
- 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
No Windows, set dura apenas pelo período atual CMD sessão. Use setx PDF4ME_API_KEY "your-api-key" Para obter um valor que persista após uma reinicialização, abra um novo terminal para que o processo o reconheça.
O cliente recebe a chave em seu construtor. Nada do que ele registra carrega a chave. API uma chave ou o conteúdo de um documento, e uma chave vazia ou composta apenas por espaços em branco, gera um erro. ArgumentException antes que qualquer solicitação seja enviada.
Início rápido
Este programa carrega input.pdf para otimização e salva o resultado como 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);
Crie um cliente e reutilize-o para todas as chamadas. Isso mantém uma conexão compartilhada, de forma que um cliente por chamada negociaria. TLS Sempre que usar. Descarte quando terminar.
O que é o SDK .NET do PDF4me?
É um único NuGet pacote, Pdf4me.Client, que envolve o PDF4me API v2 por trás de uma classe. Cada ação é um método assíncrono em Pdf4meClient batizado de acordo com seu ponto final, então /api/v2/ConvertOcrPdf é ConvertOcrPdfAsyncOs primeiros parâmetros definem o que a ação irá processar, e todo o resto é opcional, então passe-o pelo 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);
O Generated A árvore dentro da embalagem é produzida por Microsoft Kiota do PDF4me OpenAPI descrição, razão pela qual os modelos de opção e resultado são consistentes com o REST API e com o Python e JavaScript Clientes: as mesmas ações, com os mesmos nomes e valores padrão.
Qual a diferença entre uma biblioteca PDF em C# e um cliente de API?
A maioria dos resultados para "c# pdf As "bibliotecas" são bibliotecas de renderização auto-hospedadas: você adiciona o pacote, ele realiza o trabalho em seu processo e você é o proprietário do mecanismo de renderização. Pdf4me.Client é a outra forma. Ela envia o documento para PDF4me e retorna os bytes finalizados. A troca é real em ambas as direções, portanto, vale a pena ser claro sobre isso:
| Biblioteca local vs. biblioteca hospedada API | Biblioteca auto-hospedada | Pdf4me.Client |
|---|---|---|
| Onde o trabalho acontece | Em seu processo | No PDF4me serviço |
| É necessário ter conexão de rede. | Não | Sim, todas as ligações |
| Formato de custo | Licença de pacote, às vezes por desenvolvedor ou por implantação. | MIT cliente, API créditos em um plano gratuito ou pago |
| Funciona offline ou isolado da internet. | Sim | Não |
| Os documentos saem da sua infraestrutura. | Não | Sim |
| OCR, AI extração, ZUGFeRD | Geralmente um produto separado, se disponível. | Incluído nas mesmas 106 ações |
| Você mantém | O motor, suas fontes e seus CVEs | Um API chave |
Escolha uma biblioteca local quando os documentos não puderem sair da sua rede, quando precisar trabalhar offline ou quando o custo por documento, no seu volume, for mais vantajoso do que uma assinatura. Escolha este cliente quando, de outra forma, você precisaria integrar vários produtos para realizar a conversão. OCR, códigos de barras, faturamento eletrônico e AI extração, e você prefere não distribuir ou corrigir um mecanismo de renderização.
Observe que as duas perguntas que o recurso de autocompletar mais faz sobre esta categoria são respondidas de forma diferente aqui. O próprio cliente é MIT licenciado e de código abertoAssim, as opções "gratuito" e "código aberto" estão marcadas para o código que você está vinculando. O processamento por trás disso é um serviço hospedado, que não é gratuito além do seu plano gratuito.
Passar documentos e ler resultados
Documentos área DocumentSource: os bytes do arquivo ou uma string API busca a si mesmo, o que pode ser um pdf4meblobid://<id> referência de blob ou um https URLAmbos os tipos de dados são convertidos implicitamente, portanto, qualquer um deles pode ser passado diretamente. Uma string nunca é lida como um caminho de arquivo local, então leia o arquivo e passe seus bytes.
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>");
Resultados retorna de duas maneiras. As ações que produzem um documento retornam seu byte[], então File.WriteAllBytes A ação que responde com dados retorna um modelo tipado. Já as ações que respondem com dados retornam um modelo tipado:
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}");
O AI O analisador de documentos decide o formato da sua própria resposta, portanto, tudo o que ele retorna chega ao modelo. AdditionalData:
var parsed = await client.AiDocumentParserAsync(File.ReadAllBytes("invoice.pdf"), "invoice parser");
foreach (var (field, value) in parsed.AdditionalData)
Console.WriteLine($"{field}: {value}");
Vários documentos mesclar na ordem fornecida, e algumas ações não executam nenhum documento porque a entrada é texto ou um 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");
Opções que são objetos, como ConvertToPdfAction e ImageActione todos os modelos resultantes, residem em Pdf4me.Client.Generated.ModelsOs enums que uma ação executa têm nomes curtos em Pdf4me.Client (QualityType, AlignX, SplitAction), enquanto os poucos cujos nomes gerados já são curtos (DocType, ImageTypeExtract) são usados diretamente do namespace gerado:
using Pdf4me.Client;
using Pdf4me.Client.Generated.Models;
var pages = await client.CreateImagesAsync(
pdf, new ImageAction { ImageExtension = ImageExtension.Png }, pageNrs: "1");
Cada ação também leva três argumentos opcionais: extra, um dicionário de campos de solicitação adicionais para opções API A descrição ainda não está listada; os itens foram enviados como estão, juntamente com a própria ação. maxWait, que limita o tempo de espera para a tarefa enfileirada dessa chamada; e cancellationToken, o que cancela a solicitação e qualquer sondagem.
Configuração do cliente
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>(),
});
Em ASP.NET O Core, ou qualquer aplicativo que utilize injeção de dependência, registra um único cliente para todo o aplicativo e permite que o logger seja obtido da própria configuração de logs do aplicativo:
builder.Services.AddSingleton(services => new Pdf4meClient(
builder.Configuration["Pdf4me:ApiKey"]!,
new Pdf4meClientOptions { Logger = services.GetRequiredService<ILogger<Pdf4meClient>>() }));
Dê ao cliente um ILogger de Microsoft.Extensions.Logging Para visualizar todas as solicitações, respostas, tarefas em fila e pesquisas em Debug nível.
Como lidar com tarefas longas e OCR em C#?
Cada ação é submetida como uma tarefa assíncrona. Uma chamada retorna o resultado final, independentemente de o servidor ter respondido imediatamente ou ter enfileirado o trabalho, verificando o resultado no intervalo sugerido pelo servidor. Isso é importante por dois motivos: um único await pode bloquear por minutos, e o que encerra a espera é MaxWait, não Timeout.
Timeoutaplica-se a cada HTTP solicitar.MaxWaitaplica-se a todo o trabalho enfileirado, emaxWait:Uma ação substitui a anterior para essa chamada.- O OCR ações,
ConvertOcrPdfAsynceImageExtractTextAsyncAguarde pelo menos 10 minutos (DefaultOcrMaxWait), ou mais tempo quandoMaxWaité maior.
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);
Erros
Uma solicitação recusada ou falha gera uma exceção. Pdf4meException, de Pdf4me.Client.Generated.Models:
| Propriedade | Segura |
|---|---|
Message | O APIa mensagem de , caso contrário o corpo da resposta é cortado para 500 caracteres, caso contrário HTTP status |
ResponseStatusCode | O HTTP código de status |
TraceId | O APIID de rastreamento. Cite-o ao relatar um problema. |
ResponseBody | Todo o corpo da resposta, conforme enviado. |
ResponseHeaders | Os cabeçalhos de resposta |
Um trabalho que continua em andamento quando a espera termina. TimeoutExceptionArgumentos inválidos, como um documento vazio, lançam uma exceção. ArgumentException antes que qualquer solicitação seja enviada.
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);
}
As 18 seções e todas as 106 ações
As ações são agrupadas pelas seções do PDF4me REST API referênciaE os métodos de cada seção residem em seu próprio arquivo no código-fonte. Alguns estão em uma seção cujo nome você talvez não imagine: OCR Está em Localizar Pesquisa, PDF/A A criação está em Converter, e MergeV3Async está em PDF em vez de Mesclar e Dividir.
| Seção | Ações | Métodos sobre Pdf4meClient |
|---|---|---|
| AI Extração de Documentos | 14 | AiDocumentParserAsync, ProcessBankChequeAsync, ProcessBankStatementAsync, ProcessContractAsync, ProcessCreditCardAsync, ProcessHealthCardAsync, ProcessInvoiceAsync, ProcessMarriageCertificateAsync, ProcessMortgageDocumentAsync, ProcessOrderAsync, ProcessPayStubAsync, ProcessReceiptAsync, ProcessShippingLabelAsync, ProcessTaxDocumentAsync |
| Código de barras | 7 | AddBarcodeAsync, CreateBarcodeAsync, CreateSwissQrBillAsync, ReadBarcodesAsync, ReadSwissQrBillAsync, CreateEpcQrCodeAsync, ReadBarcodesFromImageAsync |
| Converter | 13 | ConvertHtmlToPdfAsync, ConvertJsonToExcelAsync, ConvertMdToPdfAsync, ConvertPdfToExcelAsync, ConvertPdfToPowerpointAsync, ConvertPdfToWordAsync, ConvertToPdfAsync, ConvertUrlToPdfAsync, ConvertVisioAsync, ConvertWordToPdfFormAsync, CreatePdfAAsync, FlattenPdfAsync, LinearizePdfAsync |
| Editar | 7 | AddAttachmentToPdfAsync, AddHtmlHeaderFooterAsync, ImageStampAsync, AddMarginAsync, AddPageNumberAsync, StampAsync, SignPdfAsync |
| Excel | 1 | FindAndReplaceTextInExcelAsync |
| Extrair | 8 | ClassifyDocumentAsync, ExtractAttachmentFromPdfAsync, ExtractPdfFormDataAsync, ExtractResourcesAsync, ExtractTableFromPdfAsync, ExtractTextByExpressionAsync, ExtractTextFromWordAsync, ParseDocumentAsync |
| Encontrar Pesquisa | 2 | FindAndReplaceAsync, ConvertOcrPdfAsync |
| Formulários | 2 | AddFormFieldAsync, FillPdfFormAsync |
| Gerar | 6 | EnableTrackingChangesInWordAsync, GenerateDocumentSingleAsync, GenerateDocumentMultipleAsync, GetTrackingChangesInWordAsync, ReplaceTextWithImageInWordAsync, GenerateDocumentSingleV2Async |
| Imagem | 13 | AddImageWatermarkToImageAsync, AddTextWatermarkToImageAsync, CompressImageAsync, ConvertImageFormatAsync, CreateImagesAsync, CropImageAsync, FlipImageAsync, GetImageMetadataAsync, ImageExtractTextAsync, RemoveExifTagsFromImageAsync, ResizeImageAsync, RotateImageAsync, RotateImageByExifDataAsync |
| Mesclar e dividir | 5 | MergeAsync, MergeOverlayAsync, SplitPdfAsync, SplitPdfByBarcodeAsync, SplitByTextAsync |
| Otimizar | 1 | OptimizeAsync |
| Organizar | 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 |
| Segurança | 2 | ProtectAsync, UnlockAsync |
| Palavra | 2 | DisableTrackingChangesInWordAsync, FindAndReplaceTextInWordAsync |
| ZUGFeRD | 1 | CreateZugferdInvoiceAsync |
Para obter informações sobre os parâmetros e o formato da resposta de cada ação, consulte o PDF4me REST API referênciaOu passe o cursor sobre o método no seu editor: cada método contém um resumo da documentação que corresponde à sua página de documentação.
Migrando da versão 1.x
A versão 2.0 é uma reescrita do PDF4me API A versão 2 e nenhuma versão da 1.x continuam funcionando. As alterações no título são as seguintes:
- Ele conversa com API v2. A versão 1.x chamava os endpoints v1 de:
/Optimize/OptimizeByProfile; 2.0 chamadas/api/v2/.... - Os clientes individuais e os clientes por área desapareceram.
Pdf4me.Instance.Init(token)ePdf4me.Instance.OptimizeClienttornar-se umnew Pdf4meClient(apiKey)com cada ação sendo um método sobre ela. - O espaço de nomes é
Pdf4me.Client, nãoPdf4meClient. - Newtonsoft.Json não é mais uma dependênciaE a versão vulnerável 12.0.3 que a versão 1.x trouxe consigo desaparece junto.
- Os erros são um tipo.
Pdf4meApiExceptionePdf4meBackendExceptiontornar-sePdf4meException. - .NET Os frameworks 4.5.2 e 4.6.1 não são mais suportados. O mínimo é 4.6.2, até .NET Padrão 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: ...) |
Seu API A chave permanece a mesma. Substitua using Pdf4meClient; com using Pdf4me.Client;, adicionar using Pdf4me.Client.Generated.Models; sempre que você usar modelos de opção ou resultado ou captura Pdf4meExceptionEm seguida, analise a tabela acima.
Solução de problemas
TimeoutException em um documento grande. O trabalho sobreviveu à espera, que é MaxWait e o padrão é de 5 minutos, não TimeoutLevante essa questão durante a chamada com maxWait: TimeSpan.FromMinutes(20)ou no cliente para cada chamada.
Um OCR A chamada parece ficar em espera por dez minutos. Esse é o piso documentado. ConvertOcrPdfAsync e ImageExtractTextAsync espere pelo menos DefaultOcrMaxWaitque dura 10 minutos, então dê a eles o seu próprio tempo. cancellationToken se a pessoa que ligou precisar desistir mais cedo.
Um 401 em Pdf4meException.ResponseStatusCode. A chave está presente, mas foi rejeitada. Gere-a novamente em PDF4me painel e confirme se a variável está visível para o processo. No Windows, set não persiste entre sessões, então use setx e abra um novo terminal.
ArgumentException antes que qualquer coisa chegue à rede. Uma verificação local falhou, geralmente devido a um documento vazio, o que significa que o arquivo lido retornou zero bytes. Verifique o caminho e certifique-se de que o arquivo não esteja bloqueado por outro processo.
Você passou o caminho de um arquivo e nada aconteceu com ele. Um argumento de string é tratado como uma referência de blob ou um https URL, nunca um caminho local. Leia o arquivo e passe seus bytes.
CreateThumbnailAsync Não foi encontrado. Os nomes de métodos da versão 1.x não existem na versão 2.0. As miniaturas agora são CreateImagesAsync com um ImageActionConsulte a tabela de migração.
Um erro de compilação em um modelo ou tipo de enumeração. Objetos de opção e modelos de resultado estão em Pdf4me.Client.Generated.Models, enquanto a maioria dos enums que uma ação assume estão em Pdf4me.ClientImporte ambos.
Perguntas frequentes
O SDK .NET do PDF4me é gratuito?
O Pdf4me.Client O pacote é gratuito e MIT licenciado, portanto não há custo para instalar ou redistribuir. O pacote é um cliente para o PDF4me API, que é um serviço hospedado com um nível gratuito e planos pagos acima dele, portanto o processamento de documentos consome API Créditos na sua conta. O código que você vincula não tem custo; o processamento é cobrado à parte.
O cliente PDF4me .NET é de código aberto?
Sim. O cliente está publicado sob a categoria MIT a licença e sua fonte estão em github.com/pdf4me/pdf4me-clientapi-dotnetUma ressalva, caso você planeje contribuir: src/Pdf4me.Client/Generated/ é produzido por Kiota do OpenAPI A descrição é substituída integralmente a cada regeneração, portanto, abra uma issue para qualquer problema nessa árvore em vez de corrigi-la. O cliente e os arquivos de seção relacionados são escritos manualmente e são o local correto para um pull request.
Quais versões do .NET fazem Pdf4me.Client apoiar?
Metas da versão 2.0.0 .NET 8, .NET 9 e .NET 10, mais .NET Standard 2.0, o que significa que também funciona em .NET Framework 4.6.2 e versões posteriores. .NET Os frameworks 4.5.2 e 4.6.1 eram suportados pela versão 1.x e não são suportados pela versão 2.0.
Como faço para converter HTML em PDF em C#?
Chamar ConvertHtmlToPdfAsync com o HTML bytes do arquivo, ou ConvertUrlToPdfAsync com um URL string e escreva o resultado byte[] para o disco:
byte[] fromHtml = await client.ConvertHtmlToPdfAsync(File.ReadAllBytes("page.html"));
byte[] fromUrl = await client.ConvertUrlToPdfAsync("https://example.com");
File.WriteAllBytes("page.pdf", fromUrl);
A renderização ocorre no próprio serviço, portanto não há mecanismo de navegador para instalar, conteinerizar ou corrigir, que é o custo usual de fazer isso com uma biblioteca local.
Como faço para ler um PDF em C#?
Depende do que você entende por "ler". GetPdfMetadataAsync retorna um DocMetadata com a contagem de páginas e PDF versão. ExtractTextByExpressionAsync, GetTextByPositionAsync e GetTextAndCoordinatesAsync Extraia o texto, o último com as posições. ExtractTableFromPdfAsync Lida com conteúdo tabular e ConvertOcrPdfAsync faz um escaneado PDF pesquisáveis primeiro. Essas ações retornam modelos tipados em vez de um byte[].
Posso criar um PDF em C# sem usar nenhuma biblioteca?
Você pode escrever o PDF Formatar o byte manualmente é um exercício razoável para uma única página de texto simples. Mas essa razoabilidade desaparece rapidamente, pois as fontes, codificações, compressão e a tabela de referências cruzadas precisam estar corretas, e a tolerância a erros varia entre os leitores. Na prática, a escolha se resume a uma biblioteca de renderização local, que você distribui e mantém atualizada, e uma... API Cliente como este, onde a renderização ocorre no lado do servidor. O PDF A especificação é publicada como ISO 32000-2 Se você quiser ter uma noção da dimensão disso.