ConfigCat.Client 10.0.0

ConfigCat SDK for .NET

ConfigCat SDK for .NET provides easy integration for your application to ConfigCat.

Supported runtimes

• .NET 6+
• .NET Framework 4.6.2+
• Other runtimes which implement .NET Standard 2.0+ like .NET Core 2.0+, Xamarin.Android 8.0+, Xamarin.iOS 10.14+, etc. (For more details, see the Platform compatiblity section below.)

Getting started

1. Install the package with NuGet

The core package, which works across all supported .NET applications, can be installed as follows:

dotnet add package ConfigCat.Client

or

Install-Package ConfigCat.Client

For ASP.NET Core applications and other modern .NET applications built on .NET Generic Host (Microsoft.Extensions.Hosting) or .NET's standard dependency injection (Microsoft.Extensions.DependencyInjection), it's recommended to install the integration package:

dotnet add package ConfigCat.Extensions.Hosting

or

Install-Package ConfigCat.Extensions.Hosting

For Unity, see the instructions here.

2. Import ConfigCat namespaces to your application

If using the core package:

using ConfigCat.Client;

If using the integration package:

using ConfigCat.Client;
using ConfigCat.Extensions.Hosting;

3. Go to the <a href="https://app.configcat.com/sdkkey" target="_blank">ConfigCat Dashboard</a> to get your SDK Key:

4. Obtain a ConfigCat client instance:

If using the core package:

var client = ConfigCatClient.Get("#YOUR-SDK-KEY#");

If using the integration package:

1. First, configure your application host or DI services:

   • If your application uses the modern, linear, property-based configuration style:

     var configCatBuilder = builder.UseConfigCat();
     configCatBuilder.AddDefaultClient(options =>
     {
         options.SdkKey = "#YOUR-SDK-KEY#";
     });
     

   • If your application uses the traditional, callback-based approach:

     builder.ConfigureConfigCat(configCatBuilder =>
     {
         configCatBuilder.AddDefaultClient(options =>
         {
             options.SdkKey = "#YOUR-SDK-KEY#";
         });
     });
     

   • If your application performs setup via a host builder not compatible with .NET Generic Host or manually builds a DI container using ServiceCollection:

     services.AddConfigCat(configCatBuilder =>
     {
         configCatBuilder.AddDefaultClient(options =>
         {
             options.SdkKey = "#YOUR-SDK-KEY#";
         });
     });
     

2. Build the application host or DI container.

3. Finally, resolve the singleton IConfigCatClient service from the DI container via constructor injection, method injection, etc., or by ServiceProvider.GetRequiredService<IConfigCatClient>(). E.g.:

   var client = app.Services.GetRequiredService<IConfigCatClient>();
   

5. Get your setting value:

var isMyAwesomeFeatureEnabled = await client.GetValueAsync("isMyAwesomeFeatureEnabled", false);

if (isMyAwesomeFeatureEnabled)
{
    doTheNewThing();
}
else
{
    doTheOldThing();
}

6. On application exit:

If using the core package:

client.Dispose();

If using the integration package:

You don't need to explicitly dispose of the resolved IConfigCatClient service. It will be automatically disposed when the application host or DI container is disposed.

Getting user-specific setting values with targeting

This feature allows you to get different setting values for different users in your application by passing a User Object to GetValueAsync().

Read more about targeting here.

var currentUser = new User("#USER-IDENTIFIER#");

var isMyAwesomeFeatureEnabled = await client.GetValueAsync(
	"isMyAwesomeFeatureEnabled",
	defaultValue: false,
	user: currentUser);

Sample/demo apps

• Sample Console App
• Sample Multi-Page Web App
• Sample Single-Page Web App
• Sample Mobile/Windows Store App
• Sample Windows Service (Worker Service built on .NET Generic Host)

Polling modes

The ConfigCat SDK supports 3 different polling strategies to fetch feature flags and settings from the ConfigCat CDN. Once the latest data is downloaded, it is stored in the cache, then the SDK uses the cached data to evaluate feature flags and settings. Read more about polling modes and how to use them at ConfigCat Docs.

Platform compatibility

The ConfigCat SDK supports all the widespread .NET JIT runtimes, everything that implements .NET Standard 2.0+ and supports TLS 1.2 should work. Starting with v9.3.0, it can also be used in applications that employ trimmed self-contained or various ahead-of-time (AOT) compilation deployment models.

Based on our tests, the SDK is compatible with the following runtimes/deployment models:

• .NET Framework 4.6.2+ (including Ngen)
• .NET Core 2.0+, .NET 5+ (including Crossgen2/ReadyToRun and Native AOT)
• Mono 5.10+
• .NET for Android (formerly known as Xamarin.Android)
• .NET for iOS (formerly known as Xamarin.iOS)
• Unity 2021.3+ (Mono JIT)
• Unity 2021.3+ (IL2CPP)^{<small>*</small>}
• Universal Windows Platform 10.0.16299.0+ (.NET Native)^{<small>**</small>}
• WebAssembly (Mono AOT/Emscripten, also known as wasm-tools)

^{<small>*</small>}Unity WebGL also works but needs a bit of extra effort: you will need to enable WebGL compatibility by calling the ConfigCatClient.PlatformCompatibilityOptions.EnableUnityWebGLCompatibility method. For more details, see Sample Scripts.<br/> ^{<small>**</small>}To make the SDK work in Release builds on UWP, you will need to add <Namespace Name="System.Text.Json.Serialization.Converters" Browse="Required All"/> to your application's .rd.xml file. See also this discussion.

Need help?

https://configcat.com/support

Contributing

Contributions are welcome. For more info please read the Contribution Guideline.

About ConfigCat

ConfigCat is a feature flag and configuration management service that lets you separate releases from deployments. You can turn your features ON/OFF using <a href="https://app.configcat.com" target="_blank">ConfigCat Dashboard</a> even after they are deployed. ConfigCat lets you target specific groups of users based on region, email or any other custom user attribute.

ConfigCat is a <a href="https://configcat.com" target="_blank">hosted feature flag service</a>. Manage feature toggles across frontend, backend, mobile, desktop apps. <a href="https://configcat.com" target="_blank">Alternative to LaunchDarkly</a>. Management app + feature flag SDKs.

• Official ConfigCat SDKs for other platforms
• Documentation
• Blog