PDF4me .NET SDK: C# PDF Biblioteca y API Cliente
Pdf4me.Cliente es un .NET biblioteca cliente para el PDF4me API que expone 106 acciones de documentos como métodos asíncronos tipados. Instálelo desde NuGet, crea uno Pdf4meClient con tu API clave, y convertir, optimizar, fusionar, dividir, OCR o extracto de documentos en C# sin incluir un motor de renderizado.
Información del paquete
| Campo | Valor |
|---|---|
| Nombre del paquete | Pdf4me.Client |
| Versión actual | 2.0.0 (Última actualización: 13/10/2026) |
| Licencia | MIT |
| .NET apoyo | .NET 8, 9 y 10, más .NET Estándar 2.0 para .NET Framework 4.6.2 y versiones posteriores |
| Descargas totales | 246,4K en todas las versiones |
| Tamaño del paquete | 1,34 MB |
| Comportamiento | 106 en 18 secciones |
| dependencias de tiempo de ejecución | Microsoft.Kiota.Bundle (>= 2.1.2) y Microsoft.Extensions.Logging.Abstractions (>= 8.0.3) |
| Base URL | https://api.pdf4me.com |
| Fuente | github.com/pdf4me/pdf4me-clientapi-dotnet |
| NuGet | nuget.org/packages/Pdf4me.Client |
Requisitos previos
- .NET 8 o más reciente, o .NET Framework 4.6.2 o posterior a través de .NET Estándar 2.0.
- A PDF4me cuenta y API llave.
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
Configura tu API clave en el entorno:
- 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
En Windows, set dura solo el tiempo actual CMD sesión. Usar setx PDF4ME_API_KEY "your-api-key" Para un valor que se conserva tras un reinicio, abra una nueva terminal para que el proceso lo detecte.
El cliente toma la clave en su constructor. Nada de lo que registra lleva la API clave o el contenido de un documento, y una clave vacía o solo con espacios en blanco genera un error. ArgumentException antes de que se envíe cualquier solicitud.
Inicio rápido
Este programa sube input.pdf para optimización y guarda el 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);
Crea un cliente y reutilízalo para cada llamada. Mantiene una conexión compartida, por lo que un cliente por llamada negociaría TLS Cada vez. Deséchelo cuando termine.
¿Qué es el SDK .NET de PDF4me?
Es un solo NuGet paquete, Pdf4me.Client, que envuelve el PDF4me API v2 detrás de una clase. Cada acción es un método asíncrono en Pdf4meClient llamado así por su punto final, por lo que /api/v2/ConvertOcrPdf es ConvertOcrPdfAsyncLos primeros parámetros son aquellos sobre los que opera la acción, y todo lo demás es opcional, así que páselos por su nombre:
var searchable = await client.ConvertOcrPdfAsync(
scan, language: "English", qualityType: QualityType.Draft);
var numbered = await client.AddPageNumberAsync(
pdf, pageNumberFormat: "Page # of {1}", alignX: AddPageNumberAlignX.Center);
El Generated El árbol dentro del paquete es producido por Microsoft Kiota del PDF4me OpenAPI descripción, razón por la cual los modelos de opciones y resultados son consistentes con la REST API y con el Python y JavaScript Clientes: las mismas acciones, con los mismos nombres y valores predeterminados.
¿En qué se diferencia una biblioteca PDF en C# de un cliente API?
La mayoría de los resultados para "c# pdf Las "bibliotecas" son bibliotecas de renderizado autoalojadas: usted agrega el paquete, este realiza el trabajo en su proceso y usted es el propietario del motor de renderizado. Pdf4me.Client es la otra forma. Envía el documento a PDF4me y devuelve los bytes terminados. El intercambio es real en ambas direcciones, por lo que conviene ser claros al respecto:
| Biblioteca local frente a biblioteca alojada API | Biblioteca autogestionada | Pdf4me.Client |
|---|---|---|
| Donde se trabaja | En tu proceso | En el PDF4me servicio |
| Se requiere conexión a internet | No | Sí, cada llamada |
| Forma de costo | Licencia de paquete, a veces por desarrollador o por implementación. | MIT cliente, API créditos en un plan gratuito o de pago |
| Funciona sin conexión o aislado de la red. | Sí | No |
| Los documentos salen de su infraestructura | No | Sí |
| OCR, AI extracción, ZUGFeRD | Normalmente es un producto aparte, si está disponible. | Incluido en las mismas 106 acciones |
| Usted mantiene | El motor, sus fuentes y su CVEs | Un API llave |
Elija una biblioteca local cuando los documentos no puedan salir de su red, cuando necesite trabajar sin conexión o cuando el costo por documento a su volumen sea mejor que una suscripción. Elija este cliente cuando de otro modo estaría integrando varios productos para cubrir la conversión, OCR, códigos de barras, facturación electrónica y AI extracción, y preferirías no enviar ni parchear un motor de renderizado en absoluto.
Tenga en cuenta que las dos preguntas que la función de autocompletar hace con más frecuencia sobre esta categoría se responden de manera diferente aquí. El cliente en sí es MIT con licencia y de código abiertoPor lo tanto, las casillas de "gratuito" y "código abierto" están marcadas para el código con el que se enlaza. El procesamiento subyacente es un servicio alojado, que no es gratuito más allá de su nivel gratuito.
Pasar documentos y leer los resultados
Documentos área DocumentSource: ya sea los bytes del archivo o una cadena API se trae a sí mismo, lo cual puede ser un pdf4meblobid://<id> referencia de blob o un https URLAmbos tipos de datos se convierten implícitamente, por lo que cualquiera de ellos se puede pasar directamente. Una cadena nunca se lee como una ruta de archivo local, así que lea el archivo y pase sus 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 regresar de dos maneras. Las acciones que producen un documento devuelven su byte[], entonces File.WriteAllBytes Lo toma directamente. Las acciones que responden con datos devuelven un modelo tipado en su lugar:
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}");
El AI El analizador de documentos decide su propia forma de respuesta, por lo que todo lo que devuelve llega en el modelo. AdditionalData:
var parsed = await client.AiDocumentParserAsync(File.ReadAllBytes("invoice.pdf"), "invoice parser");
foreach (var (field, value) in parsed.AdditionalData)
Console.WriteLine($"{field}: {value}");
Varios documentos fusionar en el orden dado, y algunas acciones no toman ningún documento porque la entrada es texto 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");
Opciones que son objetos, como ConvertToPdfAction y ImageActiony todos los modelos resultantes, viven en Pdf4me.Client.Generated.Models. Las enumeraciones que toma una acción tienen nombres cortos en Pdf4me.Client (QualityType, AlignX, SplitAction), mientras que los pocos cuyo nombre generado ya es corto (DocType, ImageTypeExtract) se utilizan directamente desde el espacio de nombres generado:
using Pdf4me.Client;
using Pdf4me.Client.Generated.Models;
var pages = await client.CreateImagesAsync(
pdf, new ImageAction { ImageExtension = ImageExtension.Png }, pageNrs: "1");
Cada acción también requiere tres argumentos opcionales: extra, un diccionario de campos de solicitud adicionales para las opciones API La descripción aún no aparece, se envía tal cual junto con la acción misma; maxWait, que limita el tiempo de espera para el trabajo en cola de esa llamada; y cancellationToken, lo que cancela la solicitud y cualquier sondeo.
Configuración del 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>(),
});
En ASP.NET Core, o cualquier aplicación que utilice inyección de dependencias, registre un cliente para toda la aplicación y deje que el registrador provenga de la configuración de registro propia de la aplicación:
builder.Services.AddSingleton(services => new Pdf4meClient(
builder.Configuration["Pdf4me:ApiKey"]!,
new Pdf4meClientOptions { Logger = services.GetRequiredService<ILogger<Pdf4meClient>>() }));
Déle al cliente un ILogger de Microsoft.Extensions.Logging para ver cada solicitud, respuesta, trabajo en cola y sondeo en Debug nivel.
¿Cómo se gestionan los trabajos largos y el OCR en C#?
Cada acción se envía como un trabajo asíncrono. Una llamada devuelve el resultado final, ya sea que el servidor haya respondido de inmediato o haya puesto el trabajo en cola, realizando sondeos entretanto en el intervalo que el servidor sugiera. Esto importa por dos razones: una sola await puede bloquearse durante minutos, y lo que pone fin a la espera es MaxWait, no Timeout.
Timeoutse aplica a cada HTTP pedido.MaxWaitse aplica a todo el trabajo en cola, ymaxWait:en una acción lo anula para esa llamada.- El OCR acciones,
ConvertOcrPdfAsyncyImageExtractTextAsync, espere al menos 10 minutos (DefaultOcrMaxWait), o más tiempo cuandoMaxWaites más 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);
Errores
Una solicitud rechazada o fallida arroja Pdf4meException, de Pdf4me.Client.Generated.Models:
| Propiedad | Se sostiene |
|---|---|
Message | El APIEl mensaje, de lo contrario el cuerpo de la respuesta se recorta a 500 caracteres, de lo contrario el HTTP estado |
ResponseStatusCode | El HTTP código de estado |
TraceId | El APIID de seguimiento. Cítelo al informar de un problema. |
ResponseBody | El cuerpo completo de la respuesta tal como se envió |
ResponseHeaders | Los encabezados de respuesta |
Un trabajo que sigue en ejecución cuando se acaba la espera lanza TimeoutExceptionLos argumentos no válidos, como un documento vacío, generan una excepción. ArgumentException antes de que se envíe cualquier solicitud.
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);
}
Las 18 secciones y las 106 acciones
Las acciones se agrupan por las secciones de la PDF4me REST API referenciay los métodos de cada sección residen en su propio archivo en el código fuente. Algunos se encuentran en una sección que tal vez no adivinarías por el nombre: OCR está en Buscar búsqueda, PDF/A La creación está en Convert y MergeV3Async está en PDF en lugar de Fusionar y Dividir.
| Sección | Comportamiento | Métodos sobre Pdf4meClient |
|---|---|---|
| AI Extracción 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 |
| Convertir | 13 | ConvertHtmlToPdfAsync, ConvertJsonToExcelAsync, ConvertMdToPdfAsync, ConvertPdfToExcelAsync, ConvertPdfToPowerpointAsync, ConvertPdfToWordAsync, ConvertToPdfAsync, ConvertUrlToPdfAsync, ConvertVisioAsync, ConvertWordToPdfFormAsync, CreatePdfAAsync, FlattenPdfAsync, LinearizePdfAsync |
| Editar | 7 | AddAttachmentToPdfAsync, AddHtmlHeaderFooterAsync, ImageStampAsync, AddMarginAsync, AddPageNumberAsync, StampAsync, SignPdfAsync |
| Sobresalir | 1 | FindAndReplaceTextInExcelAsync |
| Extracto | 8 | ClassifyDocumentAsync, ExtractAttachmentFromPdfAsync, ExtractPdfFormDataAsync, ExtractResourcesAsync, ExtractTableFromPdfAsync, ExtractTextByExpressionAsync, ExtractTextFromWordAsync, ParseDocumentAsync |
| Buscar | 2 | FindAndReplaceAsync, ConvertOcrPdfAsync |
| Formularios | 2 | AddFormFieldAsync, FillPdfFormAsync |
| Generar | 6 | EnableTrackingChangesInWordAsync, GenerateDocumentSingleAsync, GenerateDocumentMultipleAsync, GetTrackingChangesInWordAsync, ReplaceTextWithImageInWordAsync, GenerateDocumentSingleV2Async |
| Imagen | 13 | AddImageWatermarkToImageAsync, AddTextWatermarkToImageAsync, CompressImageAsync, ConvertImageFormatAsync, CreateImagesAsync, CropImageAsync, FlipImageAsync, GetImageMetadataAsync, ImageExtractTextAsync, RemoveExifTagsFromImageAsync, ResizeImageAsync, RotateImageAsync, RotateImageByExifDataAsync |
| Fusionar y dividir | 5 | MergeAsync, MergeOverlayAsync, SplitPdfAsync, SplitPdfByBarcodeAsync, SplitByTextAsync |
| Optimizar | 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 |
| Seguridad | 2 | ProtectAsync, UnlockAsync |
| Palabra | 2 | DisableTrackingChangesInWordAsync, FindAndReplaceTextInWordAsync |
| ZUGFeRD | 1 | CreateZugferdInvoiceAsync |
Para conocer los parámetros y la forma de respuesta de cada acción, consulte la PDF4me REST API referenciao bien, coloque el cursor sobre el método en su editor: cada método incluye un resumen de la documentación que coincide con su página de documentación.
Migración desde 1.x
La versión 2.0 es una reescritura de la PDF4me API v2 y nada de la versión 1.x sigue funcionando. El titular cambia:
- Habla con API v2. 1.x denominó a los puntos finales v1 tales como
/Optimize/OptimizeByProfile; 2.0 llamadas/api/v2/.... - Los clientes individuales y los clientes por área han desaparecido.
Pdf4me.Instance.Init(token)yPdf4me.Instance.OptimizeClientconvertirse en unonew Pdf4meClient(apiKey)con cada acción como un método sobre ella. - El espacio de nombres es
Pdf4me.Client, noPdf4meClient. - Newtonsoft.Json ya no es una dependenciay la versión vulnerable 12.0.3 que la versión 1.x incluyó viene con ella.
- Los errores son un tipo.
Pdf4meApiExceptionyPdf4meBackendExceptionconvertirsePdf4meException. - .NET Las versiones 4.5.2 y 4.6.1 de Framework ya no son compatibles. El mínimo es 4.6.2, a través de .NET Estándar 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: ...) |
Su API La clave sigue siendo la misma. Reemplazar using Pdf4meClient; con using Pdf4me.Client;, agregar using Pdf4me.Client.Generated.Models; dondequiera que utilice modelos de opciones o resultados o capture Pdf4meException, luego trabaje con la tabla anterior.
Solución de problemas
TimeoutException en un documento grande. El trabajo sobrevivió a la espera, que es MaxWait y por defecto es de 5 minutos, no Timeout. Plantéalo en la llamada con maxWait: TimeSpan.FromMinutes(20)o en el cliente para cada llamada.
Un OCR La llamada parece quedarse colgada durante diez minutos. Ese es el piso documentado. ConvertOcrPdfAsync y ImageExtractTextAsync espera al menos DefaultOcrMaxWait, que son 10 minutos, así que dales el suyo propio cancellationToken si la persona que llama necesita desistir antes.
Un 401 en Pdf4meException.ResponseStatusCode. La clave está presente pero rechazada. Vuelva a generarla en el PDF4me panel y confirme que la variable es visible para el proceso. En Windows, set no persiste entre sesiones, por lo que utiliza setx y abrir una nueva terminal.
ArgumentException antes de que nada llegue a la red. Se produjo un error en la comprobación local, generalmente debido a un documento vacío, lo que significa que la lectura del archivo devolvió cero bytes. Verifique la ruta y asegúrese de que el archivo no esté bloqueado por otro proceso.
Introdujiste una ruta de archivo y no le pasó nada a ese archivo. Un argumento de cadena se trata como una referencia a un blob o un https URL, nunca una ruta local. Lee el archivo y pasa sus bytes.
CreateThumbnailAsync No se encuentra. Los nombres de los métodos de la versión 1.x no existen en la versión 2.0. Las miniaturas ahora son CreateImagesAsync con un ImageActionConsulte la tabla de migración.
Un error de compilación en un modelo o tipo enumerado. Los objetos de opción y los modelos de resultados se encuentran en Pdf4me.Client.Generated.Models, mientras que la mayoría de las enumeraciones que toma una acción están en Pdf4me.ClientImporta ambos.
Preguntas frecuentes
¿El SDK .NET de PDF4me es gratuito?
El Pdf4me.Client El paquete es gratuito y MIT con licencia, por lo que no hay costo para instalarlo o redistribuirlo. El paquete es un cliente para el PDF4me API, que es un servicio alojado con un nivel gratuito y planes de pago superiores, por lo que el procesamiento de documentos consume API Créditos en tu cuenta. El código que utilizas no tiene costo; el procesamiento se factura.
¿El cliente PDF4me .NET es de código abierto?
Sí. El cliente está publicado bajo el MIT La licencia y su fuente se encuentran en github.com/pdf4me/pdf4me-clientapi-dotnetUna advertencia si planea contribuir: src/Pdf4me.Client/Generated/ es producido por Kiota del OpenAPI La descripción se reemplaza por completo en cada regeneración, así que abre un problema si encuentras algún error en ese árbol en lugar de parchearlo. El cliente y los archivos de sección que lo rodean están escritos manualmente y son el lugar adecuado para una solicitud de extracción.
¿Qué versiones de .NET admite Pdf4me.Client?
Objetivos de la versión 2.0.0 .NET 8, .NET 9 y .NET 10, más .NET Estándar 2.0, lo que significa que también funciona en .NET Framework 4.6.2 y versiones posteriores. .NET Las versiones 4.5.2 y 4.6.1 del framework eran compatibles con la versión 1.x, pero no lo son con la versión 2.0.
¿Cómo convierto HTML a PDF en C#?
Llamar ConvertHtmlToPdfAsync con el HTML bytes del archivo, o ConvertUrlToPdfAsync con un URL cadena, y escribir el resultado byte[] al disco:
byte[] fromHtml = await client.ConvertHtmlToPdfAsync(File.ReadAllBytes("page.html"));
byte[] fromUrl = await client.ConvertUrlToPdfAsync("https://example.com");
File.WriteAllBytes("page.pdf", fromUrl);
El renderizado se realiza en el servicio, por lo que no hay que instalar, contenerizar ni parchear ningún motor de navegador, que es el coste habitual de hacerlo con una biblioteca local.
¿Cómo puedo leer un PDF en C#?
Depende de lo que signifique "leer". GetPdfMetadataAsync devuelve un DocMetadata con el recuento de páginas y PDF versión. ExtractTextByExpressionAsync, GetTextByPositionAsync y GetTextAndCoordinatesAsync Extraer el texto, el último con posiciones. ExtractTableFromPdfAsync maneja contenido tabular y ConvertOcrPdfAsync hace un escaneo PDF primero se puede buscar. Estas acciones devuelven modelos tipificados en lugar de un byte[].
¿Puedo crear un PDF en C# sin usar ninguna biblioteca?
Puedes escribir el PDF formatear bytes manualmente, y para una sola página de texto plano es un ejercicio razonable. Deja de ser razonable rápidamente, porque las fuentes, las codificaciones, la compresión y la tabla de referencias cruzadas tienen que ser correctas, y los lectores varían en la cantidad de errores que toleran. En la práctica, la elección es entre una biblioteca de renderizado local que se distribuye y se mantiene parcheada, y una API cliente como este donde el renderizado se realiza en el servidor. El PDF La especificación se publica como ISO 32000-2 Si quieres ver la magnitud del asunto.