Classi di utilità e di supporto

Classi di utilità e helper

Questa guida mostra come utilizzare le piccole classi helper, mirate, che Aspose.PDF FOSS per .NET fornisce per attività di basso livello comuni: matematica intera usata dalle primitive di sicurezza, configurazione di ricerca regex, valutazione di funzioni PostScript, individuazione di font esterni, estrazione di sotto-percorsi di vettori, misurazione fisica del testo, modifiche di flussi di contenuto bufferizzati, grandi flussi in memoria e segnalazione della versione della libreria. Queste classi non sono punti di ingresso autonomi, ma supportano operazioni di documento, testo e rendering di livello superiore in tutto il API.

Helper per la matematica intera

MathExtensions è un piccolo helper statico utilizzato internamente dalle primitive di sicurezza della libreria, ma è disponibile per uso generale ogni volta che è necessaria un’operazione modulo che restituisca sempre un risultato non negativo.

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

Configurazione della ricerca regex

RegexManager è una classe statica che configura il motore di espressioni regolari usato dalle operazioni di ricerca testuale come TextFragmentAbsorber. Imposta MatchTimeout per limitare la durata massima di esecuzione di un pattern, e abilita NonBacktracking per utilizzare il motore regex non backtracking per ricerche sensibili alle prestazioni.

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

Valutazione delle funzioni PostScript

PostScriptEvaluator è una classe statica che valuta le funzioni PDF di tipo 4 (PDF32000 §7.10.5) — programmi calcolatore PostScript incorporati in un PDF, come quelli usati in alcune definizioni di spazio colore e sfumature.

double[] inputs = { 0.5 };

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

Percorsi di ricerca dei font esterni

ExternalFontCache gestisce le cartelle ricercate per TrueType/OpenType esterni (non incorporati) durante il rendering e la conversione. Usa Instance per raggiungere il singleton, GetDefaultFontsFolders per ispezionare le posizioni di ricerca predefinite e SetFontsFolders per aggiungerle o sostituirle.

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

Estrazione di sotto-percorsi vettoriali

GraphicsAbsorber visita una pagina ed estrae i suoi sotto-percorsi vettoriali dipinti come elementi SubPath, ognuno con il proprio riquadro di delimitazione Rectangle nello spazio della pagina. Questo è utile per ispezionare o misurare l’arte vettoriale senza dover analizzare manualmente lo stream di contenuto.

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}]");
    }
}

Misurazione fisica del segmento di testo

PhysicalTextSegment è la proiezione nello spazio della pagina di un TextSegment assorbito. Accedici tramite TextSegment.PhysicalSegment per misurare una sequenza di caratteri o leggere il suo TextState risolto.

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;
    }
}

Buffering delle modifiche allo stream di contenuto

ContentsAppender, raggiunto tramite Page.ContentsAppender, memorizza in buffer gli operatori per anteporre o aggiungere al flusso di contenuti di una pagina e li esegue in un’unica passata con UpdateData.

using var doc = Document.Open(pdfBytes);

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

Flussi in memoria di grandi dimensioni

OptimizedMemoryStream è un flusso in memoria espandibile che può superare il limite di 2GB per array singolo di MemoryStream memorizzando i dati in blocchi di dimensione fissa. Deriva da Stream, quindi supporta le consuete operazioni di lettura, scrittura e seek.

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

Informazioni sulla versione della libreria

BuildVersionInfo è una classe statica che espone il nome del prodotto della libreria e i numeri di versione a runtime — utile per diagnostica e richieste di supporto.

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

Suggerimenti e migliori pratiche

• Imposta RegexManager.MatchTimeout prima di eseguire ricerche su modelli non attendibili o forniti dall’utente per evitare un backtracking catastrofico.
• Chiama ExternalFontCache.SetFontsFolders con reset: true quando desideri sostituire completamente i percorsi di ricerca predefiniti invece di aggiungerli.
• Preferisci OptimizedMemoryStream rispetto a MemoryStream quando si esegue il buffering di documenti molto grandi o di dati immagine che possono superare i 2GB.
• Completa sempre un batch di modifiche ContentsAppender con UpdateData() — gli operatori bufferizzati non vengono impegnati nel flusso di contenuto fino a quel momento.
• GraphicsAbsorber.Elements può contenere istanze GraphicElement diverse da SubPath; verifica il tipo prima di eseguire il cast.

Problemi comuni

FAQ

Perché MathExtensions.Mod differisce dall’operatore % C#?

MathExtensions.Mod restituisce sempre un resto non negativo, mentre l’operatore integrato % può restituire un valore negativo quando il dividendo è negativo.

Come posso impedire che una ricerca di testo basata su regex duri troppo a lungo?

Imposta RegexManager.MatchTimeout su un TimeSpan prima di costruire o eseguire un TextFragmentAbsorber che utilizza un regex pattern.

Il SetFontsFolders sostituisce o aggiunge ai percorsi di ricerca esistenti?

Dipende dall’argomento reset: passa true per sostituire l’elenco delle cartelle corrente, oppure false per aggiungere le nuove cartelle.

Cosa estrae realmente GraphicsAbsorber?

Estrae i sotto-percorsi vettoriali dipinti di una pagina come elementi SubPath, ciascuno con un bounding Rectangle nello spazio della pagina, tramite GraphicsAbsorber.Visit.

Quando dovrei usare OptimizedMemoryStream invece di MemoryStream?

Quando i dati bufferizzati possono avvicinarsi o superare i 2GB, poiché MemoryStream è supportato da un unico array con quel limite rigido.

API Reference Sommario

Vedi anche

• Metadati e Utilità
• Aspose.PDF for .NET Enterprise Product
• Aspose.PDF for .NET — Enterprise Documentation