Skip to main content

Provider settings

XyzProviderSettings.cs declares what users can configure for your provider — API keys, endpoints, model choice, generation parameters — and validates their values. You don't build any UI: the host renders the settings dialog from your setting descriptors, persists values through IProviderSettingsStore, and puts secrets in OS secure storage automatically.

The contract​

public class XyzProviderSettings : AIProviderSettings
{
private readonly IAIProvider provider;

public XyzProviderSettings(IAIProvider provider) : base(provider)
{
this.provider = provider;
}

// Required — the settings the dialog renders and the store persists.
public override IEnumerable<SettingDescriptor> GetSettingDescriptors() { … }

// Required — validate a candidate settings dictionary (e.g. on Save).
public override bool ValidateSettings(Dictionary<string, object> settings) { … }

// Optional — users can toggle streaming for this provider (default true).
public override bool EnableStreaming => true;
}

Declaring settings​

Each SettingDescriptor describes one field:

public override IEnumerable<SettingDescriptor> GetSettingDescriptors()
{
return new[]
{
// Secrets — IsSecret routes the value to OS secure storage.
new SettingDescriptor
{
Name = "ApiKey", // used by GetSetting<T>("ApiKey")
DisplayName = "API Key",
Description = "Your API key — get one at https://platform.xyz.com/",
IsSecret = true,
Type = typeof(string),
},

// A default resolved lazily — evaluated when first read, not at load.
new SettingDescriptor
{
Name = "Model",
DisplayName = "Model",
Description = "The model to use for generating responses",
Type = typeof(string),
}.Apply(d => d.SetLazyDefault(() => this.provider.GetDefaultModel())),

// Constrained choices — rendered as a dropdown.
new SettingDescriptor
{
Name = "ReasoningEffort",
Type = typeof(string),
DefaultValue = "high",
DisplayName = "Reasoning Effort",
Description = "Controls thinking depth.",
AllowedValues = new[] { "none", "high", "max" },
},

// Numeric with UI control hints.
new SettingDescriptor
{
Name = "MaxTokens",
DisplayName = "Max Tokens",
Description = "Maximum number of tokens to generate",
Type = typeof(int),
DefaultValue = 2000,
ControlParams = new NumericSettingDescriptorControl
{
UseSlider = false,
Min = 1,
Max = 400000,
Step = 1,
},
},
};
}

SettingDescriptor fields:

FieldPurpose
NameStorage/lookup key — what GetSetting<T>("Name") and IsSettingConfigured("Name") use. Keep stable; renaming orphans saved values.
DisplayName, DescriptionDialog label and help text.
TypeValue type (string, int, bool…) — drives the control and conversion.
IsSecrettrue → OS secure storage (Windows Credential Manager / macOS Keychain). Always set for API keys/tokens.
DefaultValue / SetLazyDefaultStatic default, or a Func<object> evaluated on first read (e.g. GetDefaultModel()).
AllowedValuesConstrained set → dropdown.
ControlParamsUI control customization (NumericSettingDescriptorControl, etc.).
IsHiddenStored but not shown in the dialog.
CompanionDescriptorA paired secondary control for one setting.
EnabledWhether the control is interactive.

Validation​

ValidateSettings receives the candidate values as a Dictionary<string, object> before they're saved. Return false to reject (the dialog surfaces the problem); extract values defensively since any key may be absent or the wrong type:

public override bool ValidateSettings(Dictionary<string, object> settings)
{
if (settings == null) return false;

if (settings.TryGetValue("ApiKey", out var apiKeyObj))
{
var apiKey = apiKeyObj?.ToString();
if (string.IsNullOrWhiteSpace(apiKey))
{
return false; // required for IsConfigured
}
}

if (settings.TryGetValue("MaxTokens", out var maxObj)
&& maxObj is int max && max <= 0)
{
return false;
}

return true;
}

Reading settings at runtime​

Inside your provider, values come back through the base-class helpers:

var apiKey  = this.GetSetting<string>("ApiKey");          // decrypted from secure storage
var effort = this.GetSetting<string>("ReasoningEffort");
var max = this.GetSetting<int>("MaxTokens");

this.IsSettingConfigured("ApiKey"); // drives your IsConfigured override
this.SetSetting("LastUsedModel", model); // persist programmatic values

IsConfigured is what gates the provider as usable — the standard pattern is requiring the API key:

public override bool IsConfigured => this.IsSettingConfigured("ApiKey");
Convention

Every provider exposes at least ApiKey (secret) and Model (lazy default via GetDefaultModel()). Local providers like Ollama skip the key and instead expose a ServerUrl/Endpoint descriptor.