GroupDocs.Annotation for .NET 26.6 Release Notes

GroupDocs.Annotation for .NET 26.6 is built on the latest underlying document engines and ships with a new, modular package layout. The NuGet package is now split into a lightweight router plus per-target-framework runtime packages, adding first-class .NET 6 and .NET 8 builds. The engine upgrade also required a set of fixes: presentation (PPTX) image annotations, Visio (Diagram) area/redaction fill and slide-preview generation, a crash when cleaning Visio documents that contain hyperlinks, Diagram document-info text extraction, a NotImplementedException when saving annotated image files, and a NullReferenceException when reading annotations from HTML documents with footnotes or endnotes. It also documents one behaviour change for spreadsheet text-replacement font colour.

Full list of changes in this release

Enhancements

NuGet package split — per-target-framework runtime packages

To keep the package well under NuGet’s 250 MB limit as more target frameworks are added, GroupDocs.Annotation is now published as a lightweight router metapackage plus one runtime package per target framework:

• GroupDocs.Annotation — the router (a few KB). You still install this; nothing changes for consumers.
• GroupDocs.Annotation.Net462 — .NET Framework 4.6.2 assemblies
• GroupDocs.Annotation.Net60 — .NET 6 assemblies
• GroupDocs.Annotation.Net80 — .NET 8 assemblies

When you install GroupDocs.Annotation, NuGet automatically resolves the runtime package matching your project’s target framework. Install command, namespaces, types and public API are unchanged — you’ll just see one extra package (the runtime package for your TFM) under Dependencies.

This release also adds first-class .NET 6 and .NET 8 builds (replacing the previous netstandard2.1 build). A .NET 10 build is planned for a future release once the underlying engines support that runtime.

# Unchanged — the router picks the right runtime package for your TFM
dotnet add package GroupDocs.Annotation

# Or, if you prefer, install a specific runtime package directly
dotnet add package GroupDocs.Annotation.Net80

⚠️ Reading documents annotated by older versions on .NET 8. GroupDocs.Annotation stores its annotations inside the document. Versions before 26.6 wrote that data with .NET’s BinaryFormatter; 26.6 and later write it as XML. Because BinaryFormatter is disabled on .NET 8, documents that were annotated by a pre-26.6 version cannot have those existing annotations re-read/edited/removed/exported on the .NET 8 build (you’ll get a clear NotSupportedException). This affects only re-processing of legacy-annotated documents on .NET 8 — creating new annotations, and any document annotated with 26.6+, work on every framework. Workaround: process such legacy documents on the .NET 6 (or .NET Framework) build, or re-annotate them with 26.6+ so their metadata is upgraded to XML.

Verification. Annotate a document and round-trip it on .NET 8 — new (26.6+) annotations read back correctly on every framework:

using GroupDocs.Annotation;
using GroupDocs.Annotation.Models;
using GroupDocs.Annotation.Models.AnnotationModels;

using (Annotator annotator = new Annotator("input.pdf"))
{
    annotator.Add(new AreaAnnotation { Box = new Rectangle(100, 100, 100, 100), PageNumber = 0 });
    annotator.Save("annotated.pdf"); // metadata stored as XML (26.6+)
}

// Re-open and read the annotations back — works on net462 / net6.0 / net8.0:
using (Annotator annotator = new Annotator("annotated.pdf"))
{
    var annotations = annotator.Get();
}

Upgrade the underlying document engines

The bundled document engines have been updated to their latest releases. Annotation, rendering and document-info extraction across all supported formats are now produced by these updated engines.

Note: Because the underlying rendering and serialization engines changed, regenerated documents and page previews may differ slightly at the byte/pixel level (anti-aliasing, content-stream packing, text layout) while remaining visually equivalent. If your pipeline compares generated output byte-for-byte against stored baselines, refresh those baselines after upgrading.

Verification. Existing annotation code continues to compile and run; the fixes below address the behavioural changes the new engines introduced.

using GroupDocs.Annotation;
using GroupDocs.Annotation.Models;
using GroupDocs.Annotation.Models.AnnotationModels;

using (Annotator annotator = new Annotator("input.pdf"))
{
    annotator.Add(new AreaAnnotation
    {
        Box = new Rectangle(100, 100, 100, 100),
        BackgroundColor = 65535,
        PageNumber = 0
    });
    annotator.Save("output.pdf");
}

Behaviour Changes

Spreadsheet text-replacement font colour must now be set explicitly

With the new spreadsheet engine, the foreground colour of replaced text in a spreadsheet is no longer left “automatic” when the annotation does not specify one — the engine now materialises it as White, which can be invisible on a white background. The library does not silently override the engine, so applications that rely on a specific replacement-text colour should now set FontColor explicitly on the ReplacementAnnotation.

Action required. If you use ReplacementAnnotation (text replacement) on .xlsx/.xls documents and previously relied on the default colour, set FontColor explicitly:

using System.Collections.Generic;
using GroupDocs.Annotation;
using GroupDocs.Annotation.Models;
using GroupDocs.Annotation.Models.AnnotationModels;

using (Annotator annotator = new Annotator("input.xlsx"))
{
    ReplacementAnnotation replacement = new ReplacementAnnotation
    {
        FontColor = 0,           // ARGB — set explicitly (e.g. 0 = black) instead of relying on the default
        FontSize = 12,
        Message = "Replacement",
        PageNumber = 0,
        Points = new List<Point>
        {
            new Point(80, 60), new Point(240, 60),
            new Point(80, 80), new Point(240, 80)
        },
        TextToReplace = "New text"
    };

    annotator.Add(replacement);
    annotator.Save("output.xlsx");
}

Fixes

Fix image annotations failing on presentations (PPTX)

Adding an ImageAnnotation to a presentation threw on the new presentation engine, because an internal image API the exporter relied on was removed. The exporter now uses a stable byte-stream based path, so image annotations are added to PPTX documents again.

Verification. Add an image annotation to a presentation and confirm the save succeeds and the image appears on the slide:

using GroupDocs.Annotation;
using GroupDocs.Annotation.Models;
using GroupDocs.Annotation.Models.AnnotationModels;

using (Annotator annotator = new Annotator("input.pptx"))
{
    ImageAnnotation image = new ImageAnnotation
    {
        Box = new Rectangle(100, 100, 100, 100),
        ImagePath = "picture.png",
        Opacity = 0.7,
        PageNumber = 0
    };

    annotator.Add(image);
    annotator.Save("output.pptx"); // no longer throws; the image is rendered on the slide
}

Fix Visio (Diagram) area/redaction annotations rendering as empty outlines

On the new diagram engine, area/background and resource-redaction annotations were rendered as empty outlines instead of filled shapes, because the engine no longer defaults shapes to a solid fill pattern. Filling is now applied explicitly whenever a fill colour is set, so area annotations are filled with their background colour and redaction boxes are solid again (important for redaction).

Verification. Add a filled area annotation to a Visio document and render a preview — the box is filled, not just outlined:

using GroupDocs.Annotation;
using GroupDocs.Annotation.Models;
using GroupDocs.Annotation.Models.AnnotationModels;
using GroupDocs.Annotation.Options;

using (Annotator annotator = new Annotator("input.vsdx"))
{
    annotator.Add(new AreaAnnotation
    {
        Box = new Rectangle(100, 100, 150, 80),
        BackgroundColor = 0x00FFFF, // cyan fill
        PageNumber = 0
    });
    annotator.Save("output.vsdx");

    // Render a preview to confirm the area is filled (not an empty outline):
    using (Annotator preview = new Annotator("output.vsdx"))
    {
        PreviewOptions options = new PreviewOptions(pageNumber =>
            File.Create($"preview_{pageNumber}.png"))
        {
            PreviewFormat = PreviewFormats.PNG
        };
        preview.Document.GeneratePreview(options);
    }
}

Fix ArgumentOutOfRangeException when removing annotations from Visio documents with hyperlinks

Removing or cleaning annotations on a Visio document whose shapes contain hyperlinks (for example, link annotations or version cleanup) threw System.ArgumentOutOfRangeException. The new diagram engine shrinks the hyperlink collection as items are removed, and the cleanup loop iterated it forward over the original count. The loop now iterates in reverse, so the operation completes without error.

Verification. Remove an annotation from a Visio document that contains link annotations and confirm Save no longer throws:

using GroupDocs.Annotation;

using (Annotator annotator = new Annotator("input-with-links.vsdx"))
{
    // Remove the first annotation (or pass a specific annotation id)
    annotator.Remove(0);
    annotator.Save("output.vsdx"); // previously threw ArgumentOutOfRangeException
}

Fix Diagram GetDocumentInfo returning no text lines

Document.GetDocumentInfo() returned empty TextLines for Visio pages, because the extractor only collected text from shapes whose text was empty — and the new diagram engine now exposes the shape text (with internal markup such as <cp IX='0'/>Page1). The extractor now reads the shape text correctly (stripping the markup) and accumulates grouped sub-shape text.

Verification. Read the document info for a Visio file and confirm each page’s text lines are populated:

using GroupDocs.Annotation;

using (Annotator annotator = new Annotator("input.vsd"))
{
    IDocumentInfo info = annotator.Document.GetDocumentInfo();

    foreach (var page in info.PagesInfo)
    {
        foreach (var line in page.TextLines)
            Console.WriteLine($"Page {page.PageNumber}: {line.Text}"); // e.g. "Page 1: Page1"
    }
}

Restore slide-preview generation

Document.GeneratePreview(...) for presentations used an internal thumbnail API that was removed from the new presentation engine. It now uses the engine’s current image-rendering API with the matching image format, so slide previews continue to generate (output is equivalent). No API change for callers.

Fix System.NotImplementedException when annotating image files

Saving an annotated image file (for example JPG) could throw System.NotImplementedException from the imaging engine’s raw-data save path (RasterImage.SaveRawData) in Annotator.Save. This affected both adding and removing annotations on image documents. The issue is resolved by the updated imaging engine shipped in this release.

Verification. Annotate an image, save it, then re-open and remove the annotations — both saves succeed:

using GroupDocs.Annotation;
using GroupDocs.Annotation.Models;
using GroupDocs.Annotation.Models.AnnotationModels;

using (Annotator annotator = new Annotator("input.jpg"))
{
    annotator.Add(new AreaAnnotation
    {
        Box = new Rectangle(100, 100, 200, 100),
        BackgroundColor = 65535,
        PageNumber = 0
    });
    annotator.Save("annotated.jpg"); // previously threw NotImplementedException
}

// Removing annotations from an image works as well:
using (Annotator annotator = new Annotator("annotated.jpg"))
{
    annotator.Remove(annotator.Get());
    annotator.Save("output.jpg");
}

Fix NullReferenceException when reading annotations from HTML documents with footnotes or endnotes

Opening an HTML document that contains text comments and footnotes or endnotes (for example, HTML exported from Word) threw System.NullReferenceException from the Annotator constructor, so such documents could not be processed at all. The internal page-layout walker did not recognise the footnote/endnote content container exposed by the word-processing engine, silently truncating the layout model; reading the comment positions then dereferenced the missing footnote content. The walker now handles note containers, and footnote/endnote layout lookups are null-safe. The same code path serves Word and email documents, so comment extraction near footnotes/endnotes is more reliable for those formats as well.

Verification. Open an HTML document with comments and footnotes and read the annotations back:

using GroupDocs.Annotation;

// HTML exported from Word, containing comments with replies, a footnote and an endnote
using (Annotator annotator = new Annotator("input.html")) // previously threw NullReferenceException
{
    var annotations = annotator.Get();

    foreach (var annotation in annotations)
        Console.WriteLine($"#{annotation.Id}: {annotation.Message}, replies: {annotation.Replies?.Count ?? 0}");
}