---
title: "Configure Native SDK settings | Nutrient .NET SDK"
canonical_url: "https://www.nutrient.io/guides/dotnet/about/configure-native-sdk-settings/"
md_url: "https://www.nutrient.io/guides/dotnet/about/configure-native-sdk-settings.md"
last_updated: "2026-06-26T00:00:00.000Z"
description: "Configure SDK-wide and per-document settings in Nutrient .NET SDK."
---

# 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](https://www.nutrient.io/api/gdpicture/GdPicture.NET.14.API~Nutrient.NativeSDK.API.Settings.InstantJsonSettings.html), 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>()`](https://www.nutrient.io/api/gdpicture/GdPicture.NET.14.API~Nutrient.NativeSDK.API.Settings.DocumentSettings~Get.html), an SDK-wide override on [`SdkSettings.Get<T>()`](https://www.nutrient.io/api/gdpicture/GdPicture.NET.14.API~Nutrient.NativeSDK.API.Settings.SdkSettings~Get.html), 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](https://www.nutrient.io/sdk/dotnet/getting-started.md) guide.

```csharp

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>()`](https://www.nutrient.io/api/gdpicture/GdPicture.NET.14.API~Nutrient.NativeSDK.API.Settings.SdkSettings~Get.html) 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:

```csharp

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`](https://www.nutrient.io/api/gdpicture/GdPicture.NET.14.API~Nutrient.NativeSDK.API.Settings.CadSettings.html) controls how DWG and DXF documents are rasterized when you convert them to PDF. The same [`SdkSettings.Get`](https://www.nutrient.io/api/gdpicture/GdPicture.NET.14.API~Nutrient.NativeSDK.API.Settings.SdkSettings~Get.html) accessor works for any setting type:

```csharp

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>()`](https://www.nutrient.io/api/gdpicture/GdPicture.NET.14.API~Nutrient.NativeSDK.API.Settings.DocumentSettings~Get.html) 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:

```csharp

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:

```csharp

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`](https://www.nutrient.io/api/gdpicture/GdPicture.NET.14.API~Nutrient.NativeSDK.API.Settings.SdkSettings~Export.html) 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:

```csharp

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

```

The exported file looks like this:

```json

{
  "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`](https://www.nutrient.io/api/gdpicture/GdPicture.NET.14.API~Nutrient.NativeSDK.API.Settings.SdkSettings~Load.html) 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:

```csharp

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

```

[`SdkSettings.Load`](https://www.nutrient.io/api/gdpicture/GdPicture.NET.14.API~Nutrient.NativeSDK.API.Settings.SdkSettings~Load.html) 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>()`](https://www.nutrient.io/api/gdpicture/GdPicture.NET.14.API~Nutrient.NativeSDK.API.Settings.SdkSettings~Get.html) returns a merged view and assignments are simple property writes. The serialization APIs ([`Load`](https://www.nutrient.io/api/gdpicture/GdPicture.NET.14.API~Nutrient.NativeSDK.API.Settings.SdkSettings~Load.html) and [`Export`](https://www.nutrient.io/api/gdpicture/GdPicture.NET.14.API~Nutrient.NativeSDK.API.Settings.SdkSettings~Export.html)) 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](https://www.nutrient.io/guides/dotnet/best-practices.md#error-handling) 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>()`](https://www.nutrient.io/api/gdpicture/GdPicture.NET.14.API~Nutrient.NativeSDK.API.Settings.SdkSettings~Get.html) and [`DocumentSettings.Get<T>()`](https://www.nutrient.io/api/gdpicture/GdPicture.NET.14.API~Nutrient.NativeSDK.API.Settings.DocumentSettings~Get.html) pattern works for every setting type the SDK exposes.
---

## Related pages

- [PSPDFKit Library for .NET Changelog](/guides/dotnet/about/changelog-dotnetlibrary.md)
- [PSPDFKit GdPicture.NET Library Changelog](/guides/dotnet/about/changelog.md)
- [PSPDFKit Library for .NET API Reference](/guides/dotnet/about/api.md)
- [Migrating from iText to Nutrient .NET SDK](/guides/dotnet/about/itext-migration.md)
- [Supported file types](/guides/dotnet/about/file-type-support.md)
- [System compatibility for Nutrient .NET SDK](/guides/dotnet/about/system-compatibility.md)