Jak pracować z Core Document Management w .NET

Aspose.PDF FOSS for .NET udostępnia klasę Document jako centralny punkt wejścia dla wszystkich operacji PDF. Zainstaluj pakiet przy użyciu dotnet add package Aspose.Pdf.Foss --version 0.1.0-alpha i użyj Document.Create(), Document.Open(), Document.Save() oraz Document.Merge() do zarządzania dokumentami PDF programowo na .NET 8+.

Przewodnik krok po kroku

Krok 1: Zainstaluj pakiet

Dodaj Aspose.PDF FOSS do swojego projektu:

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

Zweryfikuj odwołanie w swoim .csproj:

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

Krok 2: Importowanie wymaganych klas

Dodaj niezbędne dyrektywy using na początku pliku:

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

Krok 3: Utwórz nowy dokument PDF

Użyj Document.Create(), aby utworzyć pusty dokument w pamięci:

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

Krok 4: Otwórz istniejący plik PDF

Document.Open akceptuje tablicę bajtów, ścieżkę do pliku lub strumień. Użyj using, aby zapewnić zwolnienie dokumentu po użyciu:

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

Krok 5: Dostęp do stron

Właściwość Document.Pages zwraca PageCollection. Strony są indeksowane od 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;

Krok 6: Zapisz dokument

Zapisz do strumienia przy użyciu Document.Save(), lub serializuj do tablicy bajtów przy użyciu 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();

Krok 7: Scalanie wielu dokumentów

Użyj Document.Merge(), aby połączyć wiele instancji Document w jedną:

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() jest równoważnym przeciążeniem, które przyjmuje tablice ścieżek plików bezpośrednio.

Typowe problemy i rozwiązania

Kolekcja stron jest pusta po wywołaniu Document.Create()
Document.Create() zwraca dokument bez stron. Musisz wyraźnie dodać stronę przed dostępem do doc.Pages[1]. Próba dostępu do indeksu, który nie istnieje, powoduje wyrzucenie IndexOutOfRangeException.

InvalidOperationException podczas wywoływania Document.Open na uszkodzonym pliku
Jeśli tablica bajtów PDF lub plik jest obcięty lub nieprawidłowy, Document.Open zgłosi wyjątek. Zweryfikuj, że źródłowa tablica bajtów jest kompletnym PDF (zaczyna się od %PDF-) przed przekazaniem jej do Open.

Document not disposed — memory leak in high-throughput scenarios
Zawsze otaczaj wywołania Document.Open i Document.Create instrukcją using. Klasa Document implementuje IDisposable; niezwolnienie jej powoduje, że podstawowy strumień i tabela odwołań pozostają w pamięci.

Save(ms) po niezresetowanym ms.Position
Podczas odczytywania z powrotem z MemoryStream po doc.Save(ms), zresetuj ms.Position = 0 przed odczytem. Pominięcie tego kroku powoduje, że czytnik napotyka pusty lub częściowy PDF.

Merge produces a document with unexpected page count
Upewnij się, że wszystkie dokumenty źródłowe są w pełni załadowane przed przekazaniem ich do Document.Merge. Zwolnienie dokumentu źródłowego przed wywołaniem merge może spowodować niekompletną strukturę stron.

Najczęściej zadawane pytania

Czy mogę otworzyć zabezpieczony hasłem PDF?

Tak. Użyj Document.Open(data, password) lub Document.Open(path, password), aby podać hasło właściciela lub użytkownika jako drugi argument.

Czy Document.ToArray() różni się od zapisywania do MemoryStream?

Document.ToArray() jest metodą ułatwiającą, która wewnętrznie zapisuje do MemoryStream i zwraca wynikową tablicę bajtów. Obie ścieżki generują identyczny wynik PDF.

Jaki jest typ właściwości Pages?

Document.Pages jest typu PageCollection. Jest indeksowany od 1; doc.Pages[1] jest pierwszą stroną.

Czy mogę zapisać dokument wielokrotnie?

Tak. Możesz wywołać doc.Save() lub doc.ToArray() wielokrotnie na tej samej instancji dokumentu. Każde wywołanie serializuje bieżący stan dokumentu.

Jak sprawdzić, czy dokument jest licencjonowany?

Document.IsLicensed zwraca bool wskazujący na wewnętrzny stan licencjonowania. Dla Aspose.PDF FOSS jest to wyłącznie informacyjne — nie jest wymagana aktywacja.