Utility- und Hilfsklassen

Dienstprogramme und Hilfsklassen

Dieser Leitfaden zeigt, wie die kleinen, fokussierten Hilfsklassen verwendet werden, die Aspose.PDF FOSS für .NET bereitstellt für gängige Low-Level-Aufgaben: Ganzzahlarithmetik, die von Sicherheits-Primitiven verwendet wird, Regex-Suchkonfiguration, PostScript-Funktionsauswertung, externe Schriftartenerkennung, Vektor-Unterpfad-Extraktion, physische Textmessung, gepufferte Inhalts-Stream-Bearbeitungen, große In-Memory-Streams und Bibliotheks-Versionsberichterstattung. Diese Klassen sind keine eigenständigen Einstiegspunkte, sondern unterstützen höhere Dokument-, Text- und Rendering-Operationen im gesamten API.

Hilfsfunktionen für Ganzzahlarithmetik

MathExtensions ist ein kleiner statischer Helfer, der intern von den Sicherheitsprimitiven der Bibliothek verwendet wird, aber er steht für allgemeine Nutzung zur Verfügung, wann immer Sie eine Modulo-Operation benötigen, die immer ein nicht-negatives Ergebnis liefert.

// Unlike the C# % operator, Mod never returns a negative value.
int wrapped = MathExtensions.Mod(-3, 5); // 2

Regex-Suchkonfiguration

RegexManager ist eine statische Klasse, die die reguläre Ausdrucks-Engine konfiguriert, die von Textsuch-Operationen wie TextFragmentAbsorber verwendet wird. Setzen Sie MatchTimeout, um zu begrenzen, wie lange ein Muster ausgeführt werden darf, und aktivieren Sie NonBacktracking, um die nicht-zurückverfolgende Regex-Engine für leistungssensible Suchen zu nutzen.

using var doc = Document.Open(pdfBytes);

// Guard against runaway regex patterns.
RegexManager.MatchTimeout = TimeSpan.FromSeconds(5);
RegexManager.NonBacktracking = true;

var absorber = new TextFragmentAbsorber(@"\d{3}-\d{4}", true);
doc.Pages[1].Accept(absorber);

Auswertung von PostScript-Funktionen

PostScriptEvaluator ist eine statische Klasse, die Type-4-PDF-Funktionen (PDF32000 §7.10.5) auswertet — PostScript Rechnerprogramme, die in ein PDF eingebettet sind, wie sie in einigen Farb- und Schattierungsdefinitionen verwendet werden.

double[] inputs = { 0.5 };

// Evaluate a PostScript calculator program against the input array.
var outputs = PostScriptEvaluator.Evaluate("{ 2 mul }", inputs);

Externe Schriftart-Suchpfade

ExternalFontCache verwaltet die Ordner, die nach externen (nicht eingebetteten) TrueType/OpenType-Faces während des Renderns und der Konvertierung durchsucht werden. Verwenden Sie Instance, um das Singleton zu erreichen, GetDefaultFontsFolders, um die integrierten Suchorte zu inspizieren, und SetFontsFolders, um sie hinzuzufügen oder zu ersetzen.

var cache = ExternalFontCache.Instance;
var defaultFolders = cache.GetDefaultFontsFolders();

// reset: false appends to the existing search paths instead of replacing them.
cache.SetFontsFolders(new[] { @"C:\Fonts\Custom" }, reset: false);

Extrahieren von Vektor-Teilpfaden

GraphicsAbsorber besucht eine Seite und extrahiert deren gemalte Vektor-Teilpfade als SubPath-Elemente, wobei jedes sein eigenes seitenbezogenes Begrenzungs-Rectangle trägt. Das ist nützlich, um Vektorkunst zu inspizieren oder zu messen, ohne den Inhaltsstrom von Hand zu parsen.

using var doc = Document.Open(pdfBytes);

var absorber = new GraphicsAbsorber();
absorber.Visit(doc.Pages[1]);

Console.WriteLine($"Elements found: {absorber.Elements.Count}");

foreach (var element in absorber.Elements)
{
    if (element is SubPath subPath)
    {
        Rectangle bounds = subPath.Rectangle;
        Console.WriteLine($"Sub-path bounds: [{bounds.LLX}, {bounds.LLY}, {bounds.URX}, {bounds.URY}]");
    }
}

Physikalische Messung von Textsegmenten

PhysicalTextSegment ist die seitenbezogene Projektion eines absorbierten TextSegment. Greifen Sie über TextSegment.PhysicalSegment darauf zu, um einen Zeichenlauf zu messen oder sein aufgelöstes TextState zu lesen.

using var doc = Document.Open(pdfBytes);

var absorber = new TextFragmentAbsorber();
doc.Pages[1].Accept(absorber);

foreach (TextFragment fragment in absorber.TextFragments)
{
    foreach (TextSegment segment in fragment.Segments)
    {
        PhysicalTextSegment physical = segment.PhysicalSegment;
        var width = physical.MeasureSegment(segment.StartCharIndex, segment.EndCharIndex, true);
        TextState state = physical.TextState;
    }
}

Zwischenspeichern von Inhalts-Stream-Änderungen

ContentsAppender, über Page.ContentsAppender erreicht, puffert Operatoren, um Inhalte am Anfang oder Ende des Seiteninhaltsstroms anzufügen, und führt sie in einem Durchgang mit UpdateData aus.

using var doc = Document.Open(pdfBytes);

Page page = doc.Pages[1];
page.ContentsAppender.AppendToBegin(new GSave());
page.ContentsAppender.AppendToEnd(new GRestore());
page.ContentsAppender.UpdateData();

Große In-Memory-Streams

OptimizedMemoryStream ist ein wachsender In-Memory-Stream, der das 2GB-Einzelarray-Limit von MemoryStream überschreiten kann, indem er Daten in festgroßen Chunks speichert. Er leitet sich von Stream ab, sodass er die üblichen Lese-, Schreib- und Suchvorgänge unterstützt.

using var stream = new OptimizedMemoryStream();

byte[] buffer = System.Text.Encoding.UTF8.GetBytes("large payload");
stream.Write(buffer, 0, buffer.Length);

bool canSeek = stream.CanSeek;
byte[] allBytes = stream.ToArray();

Bibliotheksversionsinformationen

BuildVersionInfo ist eine statische Klasse, die den Produktnamen und die Versionsnummern der Bibliothek zur Laufzeit bereitstellt — nützlich für Diagnose- und Supportanfragen.

Console.WriteLine(BuildVersionInfo.Product);
Console.WriteLine(BuildVersionInfo.AssemblyVersion);
Console.WriteLine(BuildVersionInfo.FileVersion);

Tipps und bewährte Verfahren

• Setzen Sie RegexManager.MatchTimeout bevor Sie Suchvorgänge über nicht vertrauenswürdige oder vom Benutzer bereitgestellte Muster ausführen, um katastrophales Backtracking zu vermeiden.
• Rufen Sie ExternalFontCache.SetFontsFolders mit reset: true auf, wenn Sie die Standard-Suchpfade vollständig ersetzen möchten, anstatt sie anzuhängen.
• Bevorzuge OptimizedMemoryStream gegenüber MemoryStream, wenn sehr große Dokumente oder Bilddaten gepuffert werden, die 2GB überschreiten können.
• Schließe immer einen Stapel von ContentsAppender-Bearbeitungen mit UpdateData() ab – gepufferte Operatoren werden erst dann in den Inhaltsstrom übernommen.
• GraphicsAbsorber.Elements kann GraphicElement-Instanzen enthalten, die nicht SubPath sind; prüfe den Typ vor dem Cast.

Häufige Probleme

FAQ

Warum unterscheidet sich MathExtensions.Mod vom C# %-Operator?

MathExtensions.Mod liefert immer einen nicht-negativen Rest, während der eingebaute %-Operator einen negativen Wert zurückgeben kann, wenn der Dividend negativ ist.

Wie kann ich verhindern, dass eine regex-basierte Textsuche zu lange läuft?

Setzen Sie RegexManager.MatchTimeout auf ein TimeSpan, bevor Sie ein TextFragmentAbsorber konstruieren oder ausführen, das ein Regex-Muster verwendet.

Ersetzt SetFontsFolders die bestehenden Suchpfade oder fügt er sie hinzu?

Das hängt vom reset-Argument ab: Übergeben Sie true, um die aktuelle Ordnerliste zu ersetzen, oder false, um die neuen Ordner anzuhängen.

Was extrahiert GraphicsAbsorber tatsächlich?

Es extrahiert die gemalten Vektor-Teilpfade einer Seite als SubPath-Elemente, jeweils mit einer seitenräumlichen Begrenzung Rectangle, über GraphicsAbsorber.Visit.

Wann sollte ich OptimizedMemoryStream statt MemoryStream verwenden?

Wenn die gepufferten Daten 2GB annähern oder überschreiten könnten, da MemoryStream von einem einzelnen Array mit dieser harten Grenze unterstützt wird.

API Reference Zusammenfassung

Siehe auch

• Metadaten und Dienstprogramme
• Aspose.PDF for .NET Enterprise Product
• Aspose.PDF for .NET — Enterprise Documentation