Art.DocumentUtilities.Images 3.0.0

Art.DocumentUtilities

Art.DocumentUtilities provides synchronous, in-memory document utilities for .NET Framework 4.6.2 server code and Dataverse plug-ins. Version 3 splits the former monolithic package into independently installable functional packages while preserving the existing namespaces.

Choose the smallest package

flowchart TD
    Templates[DataverseTemplates] --> CRM[Microsoft.CrmSdk.CoreAssemblies\ncompile assets only]
    Images --> Core
    Barcodes --> Core
    Barcodes --> Images
    Barcodes --> ZXing[ZXing.Net]
    OpenXml --> Core
    OpenXml --> Images
    OpenXml --> DFO[DocumentFormat.OpenXml]
    OpenXml --> HAP[HtmlAgilityPack]
    Pdf --> Core
    Pdf --> HAP
    Pdf --> PDFsharp
    Legacy --> Barcodes
    Legacy --> OpenXml
    Legacy --> Pdf
    Umbrella[Art.DocumentUtilities] --> Templates
    Umbrella --> Legacy

There are no cycles. Core has no external NuGet dependency. DataverseTemplates + Pdf does not restore or reference Open XML or ZXing. Open Sans font files are embedded only in the PDF-capable assemblies, so PDF conversion does not depend on machine fonts.

Install

dotnet add package Art.DocumentUtilities.DataverseTemplates
dotnet add package Art.DocumentUtilities.Pdf

Other examples:

dotnet add package Art.DocumentUtilities.OpenXml
dotnet add package Art.DocumentUtilities.Barcodes
dotnet add package Art.DocumentUtilities.Images

Use dotnet add package Art.DocumentUtilities only when an existing application needs the complete legacy surface. New Dataverse plug-ins should reference DataverseTemplates and the specific functional packages they use.

Dataverse template → HTML → PDF

using Art.DocumentUtilities.Pdf;
using Art.DocumentUtilities.Templates;

HtmlTemplateRenderResult rendered = DataverseHtmlTemplateRenderer.RenderWithTextAttribute(
    service,
    templateTableLogicalName: "art_documenttemplate",
    templateNameColumnLogicalName: "art_name",
    mainTableColumnLogicalName: "art_maintablelogicalname",
    templateHtmlFileColumnLogicalName: "art_htmlfile",
    templateTextAttributeLogicalName: "art_subject",
    templateName: "Welcome email",
    mainTableLogicalName: "account",
    mainRecordId: accountId,
    tracingService: tracingService);

byte[] pdf = new HtmlToPdfConverter().Convert(rendered.Html).Value;
string subject = rendered.Text;
Guid templateId = rendered.TemplateId;

Microsoft.CrmSdk.CoreAssemblies is declared by DataverseTemplates with runtime assets excluded. Dataverse supplies those platform assemblies; they are not copied into a plug-in package by this library.

DOCX, XLSX, images, and barcodes

using Art.DocumentUtilities.Docx;

var options = new DocxTransformOptions();
options.Replacements.Add(new DocxReplacement
{
    Type = DocxReplacementType.Text,
    Placeholder = "{{customerName}}",
    Text = "Ada Lovelace"
});

byte[] transformed = new DocxProcessor().Transform(templateBytes, options).Value;

using Art.DocumentUtilities.Xlsx;

var options = new XlsxTransformOptions();
options.Operations.Add(new XlsxCellFill
{
    SheetIndex = 0,
    RowIndex = 1,
    ColumnIndex = 2,
    Value = WorkbookCellValue.Decimal(1234.50m)
});

byte[] transformed = new XlsxProcessor().Transform(workbookBytes, options).Value;

Every transforming operation returns ProcessingResult<T>. Inspect Diagnostics for stable non-fatal warning codes. Invalid documents, unsupported features, and resource-limit violations throw exceptions in Art.DocumentUtilities.Processing.

Bounded processing

HTML conversion supports paragraphs, headings, line breaks, inline bold/italic/underline, lists, simple tables without spans, and block-level base64 PNG/JPEG/BMP images. DOCX-to-PDF remains available through the compatibility package. Scripts, external resources, arbitrary CSS, SVG, positioned layouts, Word fields, tracked changes, charts, SmartArt, and other layout-engine features are rejected.

The default profile allows 16 MiB compressed input, 128 MiB expanded OOXML, 32 MiB output, 2,048 ZIP entries, a 100:1 entry compression ratio, 25-megapixel images, 1,000 ordered operations, and one million extracted worksheet cells. Callers can supply stricter DocumentProcessingLimits.

Build, test, pack, and verify

dotnet restore Art.DocumentUtilities.sln
dotnet build Art.DocumentUtilities.sln -c Release --no-restore
dotnet test Art.DocumentUtilities.sln -c Release --no-build
dotnet pack Art.DocumentUtilities.sln -c Release --no-build -o artifacts/packages
dotnet restore smoke/DataversePdfPackageConsumer/DataversePdfPackageConsumer.csproj
dotnet build smoke/DataversePdfPackageConsumer/DataversePdfPackageConsumer.csproj -c Release --no-restore
./smoke/DataversePdfPackageConsumer/bin/Release/net462/DataversePdfPackageConsumer.exe
dotnet restore smoke/UmbrellaPackageConsumer/UmbrellaPackageConsumer.csproj
dotnet build smoke/UmbrellaPackageConsumer/UmbrellaPackageConsumer.csproj -c Release --no-restore
./smoke/UmbrellaPackageConsumer/bin/Release/net462/UmbrellaPackageConsumer.exe
./build/Verify-Packages.ps1

See MIGRATION.md for upgrading from 2.x and docs/PUBLIC-API.md for the package ownership inventory.