Как работать с Core Document Management в .NET

Aspose.PDF FOSS for .NET предоставляет класс Document в качестве центральной точки входа для всех операций с PDF. Установите пакет с помощью dotnet add package Aspose.Pdf.Foss --version 0.1.0-alpha и используйте Document.Create(), Document.Open(), Document.Save() и Document.Merge() для программного управления PDF‑документами на .NET 8+.

Пошаговое руководство

Шаг 1: Установить пакет

Добавьте Aspose.PDF FOSS в ваш проект:

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

Проверьте ссылку в вашем .csproj:

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

Шаг 2: Импортировать необходимые классы

Добавьте необходимые директивы using в начало вашего файла:

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

Шаг 3: Создать новый PDF‑документ

Используйте Document.Create() для создания пустого документа в памяти:

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

Шаг 4: Открыть существующий PDF

Document.Open принимает массив байтов, путь к файлу или поток. Используйте using, чтобы гарантировать освобождение документа после использования:

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

Шаг 5: Доступ к страницам

Свойство Document.Pages возвращает PageCollection. Страницы нумеруются с 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;

Шаг 6: Сохранить документ

Сохранить в поток с помощью Document.Save(), или сериализовать в массив байтов с помощью 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();

Шаг 7: Объединить несколько документов

Используйте Document.Merge() для объединения нескольких экземпляров Document в один:

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() является эквивалентной перегрузкой, которая принимает массивы путей к файлам напрямую.

Общие проблемы и решения

Коллекция страниц пуста после Document.Create()
Document.Create() возвращает документ без страниц. Вы должны явно добавить страницу перед доступом к doc.Pages[1]. Попытка доступа к индексу, которого не существует, вызывает IndexOutOfRangeException.

InvalidOperationException при вызове Document.Open на повреждённом файле
Если массив байтов PDF или файл усечён или недействителен, Document.Open выбросит исключение. Убедитесь, что исходный массив байтов является полным PDF (начинается с %PDF-) перед передачей его в Open.

Документ не освобожден — утечка памяти в сценариях с высокой пропускной способностью
Всегда оборачивайте вызовы Document.Open и Document.Create в оператор using. Класс Document реализует IDisposable; если не освободить его, базовый поток и таблица перекрестных ссылок останутся в памяти.

Save(ms) после того как ms.Position не сбрасывается
При чтении обратно из MemoryStream после doc.Save(ms), сбросьте ms.Position = 0 перед чтением. Пропуск этого шага приводит к тому, что читатель сталкивается с пустым или частичным PDF.

Слияние создает документ с неожиданным количеством страниц
Убедитесь, что все исходные документы полностью загружены перед передачей их в Document.Merge. Удаление исходного документа до вызова слияния может привести к неполному дереву страниц.

Часто задаваемые вопросы

Могу ли я открыть PDF, защищённый паролем?

Да. Используйте Document.Open(data, password) или Document.Open(path, password), чтобы передать пароль владельца или пользователя в качестве второго аргумента.

Отличается ли Document.ToArray() от сохранения в MemoryStream?

Document.ToArray() — это удобный метод, который внутри сохраняет в MemoryStream и возвращает полученный массив байтов. Оба пути дают идентичный вывод PDF.

Каков тип свойства Pages?

Document.Pages имеет тип PageCollection. Он индексируется с 1; doc.Pages[1] — первая страница.

Могу ли я сохранить документ несколько раз?

Да. Вы можете вызвать doc.Save() или doc.ToArray() несколько раз для одного и того же экземпляра документа. Каждый вызов сериализует текущее состояние документа.

Как проверить, лицензирован ли документ?

Document.IsLicensed возвращает bool, указывающий внутреннее состояние лицензирования. Для Aspose.PDF FOSS это только информационно — активация не требуется.