This HTML page is not optimized for LLM or AI agent consumption. Fetch the Markdown version instead: /guides/dotnet/annotations/configure-instant-json-appearance-and-tracking.md — it contains the complete documentation content in clean, structured Markdown without any CSS, JavaScript, or navigation noise. Configure Instant JSON appearance and tracking | Nutrient .NET SDK

Configure Instant JSON appearance and tracking

Markdown version of this page, suitable for AI agents and automation

Instant JSON import and export in Nutrient .NET SDK uses two SDK-wide settings on InstantJsonSettings: RenderTheme controls how annotation appearances are drawn, and ChangeTrackingEnabled controls whether exports return a diff or a full snapshot.

The Core appearance theme matches the rendering produced by Nutrient Web SDK and Nutrient Document Engine, so PDFs that pass through the .NET SDK look the same as PDFs touched by any other Nutrient SDK. The legacy GdPicture theme keeps the rendering used by earlier Nutrient .NET SDK releases.

Change tracking records every annotation, form field, comment, and bookmark added, modified, or removed after the document loads. With it enabled — the default — ExportInstantJSONDataToFile returns only what changed. Disable it when every export must contain the complete document state, or pass fullState: true to force a single export to emit a full snapshot regardless of the tracking flag.

This sample shows how to configure both settings, import an Instant JSON file with the Core theme, and export both diff and full-state Instant JSON files from the result.

Prepare the project

Start by registering the SDK license before you process documents. For setup details, refer to the getting started with .NET SDK guide.

using GdPicture14;
using Nutrient.NativeSDK.API.Settings;


LicenseManager licence = new LicenseManager();
licence.RegisterKEY(""); // Set your license key

Configure the appearance theme

Set RenderTheme at process startup. Every Instant JSON import that follows uses the configured renderer to generate annotation appearance streams:

InstantJsonSettings instantJson = SdkSettings.Get<InstantJsonSettings>();
instantJson.RenderTheme = InstantJsonRenderTheme.Core;

Switch to InstantJsonRenderTheme.Default to keep the legacy GdPicture appearance. The setting only affects new appearance streams generated during import — it doesn’t rewrite appearances already in the source PDF.

Enable change tracking

ChangeTrackingEnabled defaults to true, but you may want to set it explicitly when you need every export to be a diff. With tracking on, the SDK sends each change to the change tracker whenever you call AddSquareAnnotation, AddStickyNoteAnnotation, RemoveAnnotation, or any other mutating API:

instantJson.ChangeTrackingEnabled = true;

Import the Instant JSON file

Load a PDF with LoadFromFile, then apply the Instant JSON file with ImportInstantJSONDataFromFile. The import uses the Core theme because of the SDK-wide setting above:

using GdPicturePDF pdf = new GdPicturePDF();
GdPictureStatus loadStatus = pdf.LoadFromFile(@"test_form_fields.pdf");
if (loadStatus != GdPictureStatus.OK)
{
    Console.Error.WriteLine($"Loading PDF failed: {loadStatus}");
    Environment.Exit(1);
}


GdPictureStatus importStatus = pdf.ImportInstantJSONDataFromFile(@"test_annotations_instant.json");
if (importStatus != GdPictureStatus.OK)
{
    Console.Error.WriteLine($"Instant JSON import failed: {importStatus}");
    Environment.Exit(1);
}

Add a couple of post-import changes

Make a few document changes so the diff export has something to capture:

pdf.AddSquareAnnotation(72, 144, 200, 60, "Reviewer", "Highlighted region", 2.0f,
    PdfAnnotationBorderStyle.PdfAnnotationBorderStyleSolid, 0, 0, 1.0f, 255, 0, 0);
pdf.AddStickyNoteAnnotation(PdfStickyNoteAnnotationIcon.PdfAnnotationIconComment,
    72, 220, "Reviewer", "Section question", "Please confirm this section.",
    1.0f, false, 255, 255, 0, 0, 0, 0, 0);

Export the diff

ExportInstantJSONDataToFile produces a diff that includes only the two annotations added above, plus any other changes the tracker recorded. The annotations imported earlier aren’t repeated:

GdPictureStatus diffStatus = pdf.ExportInstantJSONDataToFile(@"diff.json");
if (diffStatus != GdPictureStatus.OK)
{
    Console.Error.WriteLine($"Diff Instant JSON export failed: {diffStatus}");
    Environment.Exit(1);
}

Export the full snapshot

Use fullState: true on the stream overload to emit a complete snapshot of the document, regardless of the change tracker. Use ExportInstantJSONDataToStream for archival, document hand-off, or first-time syncs:

using FileStream fullStream = new FileStream(@"full.json", FileMode.Create, FileAccess.Write);
GdPictureStatus fullStatus = pdf.ExportInstantJSONDataToStream(fullStream, fullState: true);
if (fullStatus != GdPictureStatus.OK)
{
    Console.Error.WriteLine($"Full Instant JSON export failed: {fullStatus}");
    Environment.Exit(1);
}

Both shapes use the same Instant JSON schema, so ImportInstantJSONDataFromFile accepts either.

Diff versus full state — when to use which

Choose the export that matches the workflow. The two options serve different scenarios:

  • Diff export (default, change tracking on) — Use this for incremental updates. A server can hold the source PDF, while the client edits annotations and sends back only what changed. The payload stays smaller, and the data is simpler to merge.
  • Full export (fullState: true or change tracking off) — Use this for archival, document hand-off, or first-time syncs when the receiver doesn’t yet have the original PDF. The payload is larger, but it contains the full document state.

To disable change tracking globally so every export becomes a full snapshot, use SdkSettings.Get<InstantJsonSettings>() to set ChangeTrackingEnabled to false:

SdkSettings.Get<InstantJsonSettings>().ChangeTrackingEnabled = false;

Error handling

Both settings are part of the Native SDK settings system, so they don’t throw — invalid enum values simply fail to compile. The Instant JSON APIs return GdPictureStatus for runtime errors:

  • GdPictureStatus.PdfDocumentMustBeUnencrypted — Instant JSON refuses to operate on encrypted PDFs
  • GdPictureStatus.FileNotFound — the path supplied to an import call doesn’t exist
  • GdPictureStatus.GenericError — malformed Instant JSON, or no PDF is loaded

For status-handling patterns, refer to the handling errors with .NET SDK guide. For a comprehensive walkthrough of the settings system, refer to the configure .NET SDK settings sample. For visual examples of theme differences, refer to the Instant JSON appearance theme comparison guide.

Conclusion

This sample configures the two Instant JSON settings that matter for import and export, imports a JSON file with the Core appearance theme, and produces both diff and full-state exports from the result. The same settings work across every Instant JSON import and export in the SDK, so configuring them once at startup is usually enough.