Configure Native SDK settings

Nutrient .NET SDK exposes a hierarchical, type-safe settings system in the Nutrient.NativeSDK.API.Settings namespace. Settings let you change SDK behavior, such as CAD rendering, Instant JSON appearance, and PDF conformance, without passing options through every API call.

The SDK resolves each setting in three layers, with the highest precedence first: a per-document override on DocumentSettings.Get<T>(), an SDK-wide override on SdkSettings.Get<T>(), and the built-in default on the setting type. Reads return the merged view across all three layers, and writes target the level you access.

This sample shows how to use the settings system in a real workflow. It sets SDK-wide values for Instant JSON and CAD, overrides one of them for a specific document, persists the SDK overrides to a JSON file, and reloads them later.

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

Only the Nutrient.NativeSDK.API.Settings namespace is needed. Don’t import Nutrient.NativeSDK.API.Settings.Default — that namespace contains the raw definition classes, while the merged view types you actually use live one level up.

Set an SDK-wide value

Use SdkSettings.Get<T>() to get a writable settings instance for the whole process. The example below configures Instant JSON to use the Core appearance theme and to record changes for diff exports:

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

Every PDF document opened after this call inherits both values unless it sets its own override.

Configure CAD rendering

CadSettings controls how DWG and DXF documents are rasterized when you convert them to PDF. The same SdkSettings.Get accessor works for any setting type:

CadSettings cadSettings = SdkSettings.Get<CadSettings>();
cadSettings.EnableLineWeight = false;
cadSettings.ThumbnailMode = false;

EnableLineWeight controls whether the source CAD file’s per-entity line weights are honored, and ThumbnailMode switches to a faster, lower-fidelity rendering path for thumbnails.

Override a value for one document

Use DocumentSettings.Get<T>() when you need an override for a single document. Reads fall back from the document-level value to the SDK-wide value and then to the built-in default, but writes create an override that only affects that instance:

DocumentSettings legacyDocSettings = new DocumentSettings();
legacyDocSettings.Get<InstantJsonSettings>().RenderTheme = InstantJsonRenderTheme.Default;

Console.WriteLine($"SDK-wide theme: {SdkSettings.Get<InstantJsonSettings>().RenderTheme}");
Console.WriteLine($"Override theme: {legacyDocSettings.Get<InstantJsonSettings>().RenderTheme}");

The output shows the SDK-wide value (Core) and the per-document override (Default) side by side.

Apply settings to an Instant JSON import

The configured SDK-wide values flow through the standard GdPicturePDF workflow without extra parameters. Open a PDF and import an Instant JSON file — the import uses the Core appearance theme and feeds the change tracker because of the SDK-wide settings you set 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);
}

GdPictureStatus saveStatus = pdf.SaveToFile(@"output.pdf");
if (saveStatus != GdPictureStatus.OK)
{
    Console.Error.WriteLine($"Saving PDF failed: {saveStatus}");
    Environment.Exit(1);
}

Persist SDK settings as JSON

Use SdkSettings.Export to write the current SDK-wide overrides to a JSON file. The output includes only values that differ from the built-in defaults, so the file stays compact:

SdkSettings.Export(@"sdk-settings.json");

The exported file looks like this:

{
  "version": 1,
  "mode": "differential",
  "settings": {
    "InstantJson": {
      "renderTheme": "Core",
      "changeTrackingEnabled": true
    },
    "Cad": {
      "enableLineWeight": false
    }
  }
}

Reload SDK settings from JSON

At application startup, load the saved settings to restore the previous configuration. SdkSettings.Load throws FileNotFoundException if the path doesn’t exist and JsonException if the file content can’t be parsed, so wrap the call in a try/catch block when you load user-supplied paths:

try
{
    SdkSettings.Load(@"sdk-settings.json");
}
catch (FileNotFoundException)
{
    Console.WriteLine("No saved settings found — using defaults.");
}

SdkSettings.Load applies overrides in place. The file format is forward-compatible — unknown properties are ignored, and missing properties fall back to defaults.

Error handling

The settings types themselves don’t throw — Get<T>() returns a merged view and assignments are simple property writes. The serialization APIs (Load and Export) can raise FileNotFoundException, IOException, or JsonException, so wrap them in try/catch blocks when you read user-supplied paths. For status-handling patterns on the GdPicturePDF APIs, refer to the handling errors with .NET SDK guide.

Conclusion

This sample walks through the core operations you need to use the Native SDK settings system: setting SDK-wide values, overriding them for a single document, applying them to a real Instant JSON import, and persisting them to disk. The same SdkSettings.Get<T>() and DocumentSettings.Get<T>() pattern works for every setting type the SDK exposes.