Cómo trabajar con la gestión central de documentos en .NET

Aspose.PDF FOSS for .NET proporciona la clase Document como el punto de entrada central para todas las operaciones con PDF. Instale el paquete con dotnet add package Aspose.Pdf.Foss --version 0.1.0-alpha y use Document.Create(), Document.Open(), Document.Save() y Document.Merge() para gestionar documentos PDF programáticamente en .NET 8+.

Guía paso a paso

Paso 1: Instalar el paquete

Agrega Aspose.PDF FOSS a tu proyecto:

dotnet add package Aspose.Pdf.Foss --version 0.1.0-alpha

Verifique la referencia en su .csproj:

<PackageReference Include="Aspose.Pdf.Foss" Version="0.1.0-alpha" />

Paso 2: Importar clases requeridas

Agregue las directivas using necesarias al principio de su archivo:

using Aspose.Pdf;
using Aspose.Pdf.Annotations;

Paso 3: Crear un nuevo documento PDF

Utilice Document.Create() para crear un documento vacío en memoria:

using var doc = Document.Create();
// The document has no pages yet; add pages before saving
using var ms = new MemoryStream();
doc.Save(ms);
byte[] pdfBytes = ms.ToArray();

Paso 4: Abrir un PDF existente

Document.Open acepta una matriz de bytes, una ruta de archivo o un flujo. Use using para garantizar que el documento se libere después de su uso:

// From a file path
using var doc = Document.Open("input.pdf");
var page = doc.Pages[1];
// From a byte array loaded elsewhere
byte[] data = File.ReadAllBytes("input.pdf");
using var doc2 = Document.Open(data);

Paso 5: Acceder a páginas

La propiedad Document.Pages devuelve un PageCollection. Las páginas están indexadas a partir de 1:

using var doc = Document.Open("input.pdf");
int pageCount = doc.Pages.Count;
var firstPage = doc.Pages[1];
double width = firstPage.Width;
double height = firstPage.Height;

Paso 6: Guardar un documento

Guarde en un flujo con Document.Save(), o serialice a una matriz de bytes con Document.ToArray():

using var doc = Document.Open("input.pdf");
var page = doc.Pages[1];
var action = PdfAction.CreateUri("https://aspose.com/test");
page.Annotations.AddLinkAnnotation(new Rectangle(50, 700, 200, 720), action);
using var ms = new MemoryStream();
doc.Save(ms);
ms.Position = 0;
byte[] savedBytes = ms.ToArray();

Paso 7: Fusionar varios documentos

Utilice Document.Merge() para combinar múltiples instancias de Document en una:

using var doc1 = Document.Open("part1.pdf");
using var doc2 = Document.Open("part2.pdf");
var merged = Document.Merge(new[] { doc1, doc2 });
merged.Save("combined.pdf");

Document.MergeDocuments() es una sobrecarga equivalente que acepta matrices de rutas de archivo directamente.

Problemas comunes y soluciones

La colección de páginas está vacía después de Document.Create()
Document.Create() devuelve un documento sin páginas. Debe agregar explícitamente una página antes de acceder a doc.Pages[1]. Intentar acceder a un índice que no existe lanza un IndexOutOfRangeException.

InvalidOperationException al llamar a Document.Open en un archivo corrupto
Si la matriz de bytes PDF o el archivo está truncado o es inválido, Document.Open lanzará una excepción. Valide que la matriz de bytes de origen sea un PDF completo (comienza con %PDF-) antes de pasarla a Open.

Documento no liberado — fuga de memoria en escenarios de alto rendimiento Siempre envuelva las llamadas Document.Open y Document.Create en una declaración using. La clase Document implementa IDisposable; no disponer de ella provoca que el flujo subyacente y la tabla de referencias cruzadas permanezcan en memoria.

Save(ms) después de que ms.Position no se restablece
Al leer de nuevo desde un MemoryStream después de doc.Save(ms), restablezca ms.Position = 0 antes de leer. Omitir este paso hace que el lector encuentre un PDF vacío o parcial.

Merge produce un documento con un recuento de páginas inesperado
Asegúrese de que todos los documentos de origen estén completamente cargados antes de pasarlos a Document.Merge. Liberar un documento de origen antes de la llamada de fusión puede resultar en un árbol de páginas incompleto.

Preguntas frecuentes

¿Puedo abrir un PDF protegido con contraseña?

Sí. Utilice Document.Open(data, password) o Document.Open(path, password) para suministrar la contraseña de propietario o de usuario como segundo argumento.

¿Document.ToArray() difiere de guardar en un MemoryStream?

Document.ToArray() es un método de conveniencia que internamente guarda en un MemoryStream y devuelve el arreglo de bytes resultante. Ambas rutas producen una salida PDF idéntica.

¿Cuál es el tipo de la propiedad Pages?

Document.Pages es de tipo PageCollection. Está indexado a 1; doc.Pages[1] es la primera página.

¿Puedo guardar un documento varias veces?

Sí. Puedes llamar doc.Save() o doc.ToArray() varias veces en la misma instancia del documento. Cada llamada serializa el estado actual del documento.

¿Cómo verifico si un documento está licenciado?

Document.IsLicensed devuelve un bool que indica el estado interno de licenciamiento. Para Aspose.PDF FOSS esto es solo informativo — no se requiere activación.