유틸리티 및 도우미 클래스

유틸리티 및 헬퍼 클래스

이 가이드는 Aspose.PDF FOSS for .NET가 제공하는 작고 집중된 헬퍼 클래스를 사용하는 방법을 보여줍니다. 이 클래스들은 보안 기본 연산에 사용되는 정수 수학, 정규식 검색 구성, PostScript 함수 평가, 외부 폰트 검색, 벡터 서브 경로 추출, 물리적 텍스트 측정, 버퍼링된 콘텐츠 스트림 편집, 대용량 인메모리 스트림, 라이브러리 버전 보고와 같은 일반적인 저수준 작업에 사용됩니다. 이러한 클래스는 자체적으로 진입점이 아니라 API 전반에 걸쳐 상위 수준의 문서, 텍스트 및 렌더링 작업을 지원합니다.

정수 수학 헬퍼

MathExtensions는 라이브러리의 보안 기본 연산에서 내부적으로 사용되는 작은 정적 헬퍼이지만, 항상 음수가 아닌 결과를 반환하는 모듈로 연산이 필요할 때 일반적으로 사용할 수 있습니다.

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

정규식 검색 구성

RegexManager는 TextFragmentAbsorber과 같은 텍스트 검색 작업에 사용되는 정규식 엔진을 구성하는 정적 클래스입니다. MatchTimeout를 설정하여 패턴이 실행될 수 있는 시간을 제한하고, NonBacktracking를 활성화하여 성능에 민감한 검색에 비백트래킹 정규식 엔진을 사용합니다.

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

PostScript 함수 평가

PostScriptEvaluator은(는) Type4PDF함수(PDF32000§7.10.5)를 평가하는 정적 클래스이며 — PDF에 내장된 PostScript 계산기 프로그램으로, 일부 색공간 및 쉐이딩 정의에 사용됩니다.

double[] inputs = { 0.5 };

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

외부 글꼴 검색 경로

ExternalFontCache은(는) 렌더링 및 변환 중에 외부(비내장) TrueType/OpenType 얼굴을 검색하는 폴더를 관리합니다. 싱글톤에 접근하려면 Instance을(를) 사용하고, 기본 검색 위치를 확인하려면 GetDefaultFontsFolders을(를) 사용하며, 이를 추가하거나 교체하려면 SetFontsFolders을(를) 사용하십시오.

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

벡터 하위 경로 추출

GraphicsAbsorber은(는) 페이지를 방문하여 그 페이지에 그려진 벡터 하위 경로를 SubPath 요소로 추출합니다. 각 요소는 자체 페이지 공간 경계 Rectangle를 가지고 있습니다. 이는 콘텐츠 스트림을 직접 파싱하지 않고도 벡터 아트워크를 검사하거나 측정하는 데 유용합니다.

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

물리적 텍스트 세그먼트 측정

PhysicalTextSegment은(는) 흡수된 TextSegment의 페이지 공간 투영입니다. 문자 연속을 측정하거나 해결된 TextState을(를) 읽으려면 TextSegment.PhysicalSegment를 통해 접근하십시오.

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

콘텐츠 스트림 편집 버퍼링

ContentsAppender는 Page.ContentsAppender을 통해 접근하며, 페이지 콘텐츠 스트림에 앞에 붙이거나 뒤에 추가하는 연산자를 버퍼링하고 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();

대용량 인메모리 스트림

OptimizedMemoryStream은 고정 크기 청크에 데이터를 저장하여 MemoryStream의 2GB 단일 배열 한계를 초과할 수 있는 확장 가능한 인메모리 스트림입니다. Stream를 상속받았으므로 일반적인 읽기, 쓰기 및 탐색 작업을 지원합니다.

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

라이브러리 버전 정보

BuildVersionInfo은 런타임에 라이브러리의 제품명과 버전 번호를 노출하는 정적 클래스이며, 진단 및 지원 요청에 유용합니다.

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

팁 및 모범 사례

• 신뢰할 수 없거나 사용자 제공 패턴에 대한 검색을 실행하기 전에 RegexManager.MatchTimeout을 설정하여 치명적인 백트래킹을 방지하십시오.
• 기본 검색 경로에 추가하는 대신 완전히 교체하려면 ExternalFontCache.SetFontsFolders을 reset: true과 함께 호출하십시오.
• 버퍼링 시 2GB를 초과할 수 있는 매우 큰 문서나 이미지 데이터를 처리할 때는 OptimizedMemoryStream을 MemoryStream보다 선호합니다.
• 항상 ContentsAppender 편집 배치를 UpdateData()으로 마무리하십시오 — 버퍼링된 연산자는 그때까지 콘텐츠 스트림에 커밋되지 않습니다.
• GraphicsAbsorber.Elements에는 SubPath 이외의 GraphicElement 인스턴스가 포함될 수 있습니다; 형변환하기 전에 타입을 확인하십시오.

일반적인 문제

FAQ

왜 MathExtensions.Mod가 C# % 연산자와 다른가요?

MathExtensions.Mod은 항상 음수가 아닌 나머지를 반환하지만, 내장된 % 연산자는 피제수가 음수일 때 음수 값을 반환할 수 있습니다.

정규식 기반 텍스트 검색이 너무 오래 실행되는 것을 어떻게 중지할 수 있나요?

정규식 패턴을 사용하는 TextFragmentAbsorber를 구성하거나 실행하기 전에 RegexManager.MatchTimeout을 TimeSpan으로 설정하십시오.

SetFontsFolders은 기존 검색 경로를 교체합니까, 아니면 추가합니까?

이는 reset 인수에 따라 달라집니다: 현재 폴더 목록을 교체하려면 true을 전달하고, 새 폴더를 추가하려면 false를 전달하십시오.

GraphicsAbsorber은 실제로 무엇을 추출합니까?

이는 페이지의 페인팅된 벡터 하위 경로를 SubPath 요소로 추출하며, 각 요소는 페이지 공간 경계 Rectangle을 가지고, GraphicsAbsorber.Visit를 통해 수행됩니다.

MemoryStream 대신 OptimizedMemoryStream을 언제 사용해야 합니까?

버퍼링된 데이터가 2GB에 가까워지거나 초과할 수 있을 때, MemoryStream은 해당 하드 제한을 가진 단일 배열에 기반하기 때문입니다.

API Reference 요약

참조

• 메타데이터 및 유틸리티
• Aspose.PDF for .NET Enterprise Product
• Aspose.PDF for .NET — Enterprise Documentation