.NET

The Unleash .NET SDK lets you evaluate feature flags in .NET applications. It connects to Unleash or Unleash Edge to fetch flag configurations and evaluates them locally against an Unleash context.

You can use this SDK with Unleash Enterprise or Unleash Open Source.

For an overview of how Unleash SDKs work, including offline behavior, feature compatibility across SDKs, and default refresh and metrics intervals, refer to the SDK overview.

Requirements

• .NET 6 and above
• .NET Standard 2.0
• .NET Framework 4.7 and above

Installation

Install the latest version of Unleash.Client from nuget.org or use the dotnet cli:

$
dotnet add package unleash.client

Initialization

To create a new instance of Unleash you need to create and pass in an UnleashSettings object.

The SDK synchronizes with the Unleash API on initialization. By default this happens asynchronously in the background. If you need to block until the SDK has synchronized, use synchronous startup.

1
using Unleash;
2
var settings = new UnleashSettings()
3
{
4
    AppName = "dotnet-test",
5
    UnleashApi = new Uri("<your-api-url>"),
6
    CustomHttpHeaders = new Dictionary<string, string>()
7
    {
8
      {"Authorization","<your-api-token>" }
9
    }
10
};
11
12
var unleash = new DefaultUnleash(settings);
13
14
// Add to Container as Singleton
15
// .NET Core 3/.NET 5/...
16
services.AddSingleton<IUnleash>(c => unleash);

When your application shuts down, remember to dispose the unleash instance.

1
unleash?.Dispose()

Synchronous startup

This unleash client does not throw any exceptions if the unleash server is unreachable. Also, fetching features will return the default value if the feature toggle cache has not yet been populated. In many situations it is perferable to throw an error than allow an application to startup with incorrect feature toggle values. For these cases, we provide a client factory with the option for synchronous initialization.

1
using Unleash;
2
using Unleash.ClientFactory;
3
4
var settings = new UnleashSettings()
5
{
6
    AppName = "dotnet-test",
7
    UnleashApi = new Uri("<your-api-url>"),
8
    CustomHttpHeaders = new Dictionary<string, string>()
9
    {
10
       {"Authorization","<your-api-token>" }
11
    }
12
};
13
var unleashFactory = new UnleashClientFactory();
14
15
IUnleash unleash = await unleashFactory.CreateClientAsync(settings, synchronousInitialization: true);
16
17
// this `unleash` has successfully fetched feature flags and written them to its cache.
18
// if network errors or disk permissions prevented this from happening, the above await would have thrown an exception
19
20
var awesome = unleash.IsEnabled("SuperAwesomeFeature");

The CreateClientAsync method was introduced in version 1.5.0, making the previous Generate method obsolete. There’s also a CreateClient method available if you don’t prefer the async version.

Project-scoped Unleash client

If you’re organizing your feature flags in projects in Unleash Enterprise, you can scope your API tokens to include only the specific projects needed for your client. Then use that token when configuring the Unleash client:

1
var settings = new UnleashSettings()
2
{
3
    AppName = "dotnet-test",
4
    UnleashApi = new Uri("https://eu.app.unleash-hosted.com/demo/api/"),
5
    CustomHttpHeaders = new Dictionary<string, string>()
6
    {
7
       {"Authorization","<your-project-scoped-api-token>" }
8
    }
9
};

Check flags

The IsEnabled method allows you to check whether a feature is enabled:

1
if(unleash.IsEnabled("SuperAwesomeFeature"))
2
{
3
  // new feature behavior
4
}
5
else
6
{
7
  // current behavior
8
}

If the Unleash client can’t find the feature you’re trying to check, it will default to returning false. You can change this behavior on a per-invocation basis by providing a fallback value as a second argument.

For instance, unleash.IsEnabled("SuperAwesomeFeature") would return false if SuperAwesomeFeature doesn’t exist. But if you’d rather it returned true, then you could pass that as the second argument:

1
unleash.IsEnabled("SuperAwesomeFeature", true)

You can also pass an Unleash context to evaluate flags for a specific user, session, or other properties required by strategies, constraints, and stickiness. Refer to the Unleash context section for details.

1
var context = new UnleashContext
2
{
3
  UserId = "61"
4
};
5
6
unleash.IsEnabled("someToggle", context);

Events

Currently supported events:

• Impression data events
• Error events
• Toggles updated event

1
var settings = new UnleashSettings()
2
{
3
    // ...
4
};
5
6
var unleash = new DefaultUnleash(settings);
7
8
// Set up handling of impression and error events
9
unleash.ConfigureEvents(cfg =>
10
{
11
    cfg.ImpressionEvent = evt => { Console.WriteLine($"{evt.FeatureName}: {evt.Enabled}"); };
12
    cfg.ErrorEvent = evt => { /* Handling code here */ Console.WriteLine($"{evt.ErrorType} occured."); };
13
    cfg.TogglesUpdatedEvent = evt => { /* Handling code here */ Console.WriteLine($"Toggles updated on: {evt.UpdatedOn}"); };
14
});

Activation strategies

The .NET client comes with implementations for the built-in activation strategies provided by unleash.

• DefaultStrategy
• UserWithIdStrategy
• GradualRolloutRandomStrategy
• GradualRolloutUserWithIdStrategy
• GradualRolloutSessionIdStrategy
• RemoteAddressStrategy
• ApplicationHostnameStrategy
• FlexibleRolloutStrategy

Read more about the strategies in the activation strategy reference docs.

Custom strategies

You can also specify and implement your own custom strategies. The specification must be registered in the Unleash UI and you must register the strategy implementation when you wire up unleash.

1
IStrategy s1 = new MyAwesomeStrategy();
2
IStrategy s2 = new MySuperAwesomeStrategy();
3
4
IUnleash unleash = new DefaultUnleash(config, s1, s2);

Unleash context

In order to use some of the common activation strategies you must provide an Unleash context.

If you have configured custom stickiness and want to use that with the FlexibleRolloutStrategy or Variants, add the custom stickiness parameters to the Properties dictionary on the Unleash Context:

1
HttpContext.Current.Items["UnleashContext"] = new UnleashContext
2
{
3
    UserId = HttpContext.Current.User?.Identity?.Name,
4
    SessionId = HttpContext.Current.Session?.SessionID,
5
    RemoteAddress = HttpContext.Current.Request.UserHostAddress,
6
    Properties = new Dictionary<string, string>
7
    {
8
        // Obtain "customField" and add it to the context properties
9
        { "customField", HttpContext.Current.Items["customField"].ToString() }
10
    }
11
};

UnleashContextProvider

The provider typically binds the context to the same thread as the request. If you are using Asp.Net the UnleashContextProvider will typically be a ‘request scoped’ instance.

1
public class AspNetContextProvider : IUnleashContextProvider
2
{
3
    public UnleashContext Context
4
    {
5
       get { return HttpContext.Current?.Items["UnleashContext"] as UnleashContext; }
6
    }
7
}
8
9
protected void Application_BeginRequest(object sender, EventArgs e)
10
{
11
    HttpContext.Current.Items["UnleashContext"] = new UnleashContext
12
    {
13
        UserId = HttpContext.Current.User?.Identity?.Name,
14
        SessionId = HttpContext.Current.Session?.SessionID,
15
        RemoteAddress = HttpContext.Current.Request.UserHostAddress,
16
        Properties = new Dictionary<string, string>()
17
        {
18
            {"UserRoles", "A,B,C"}
19
        }
20
    };
21
}
22
23
var settings = new UnleashSettings()
24
{
25
    AppName = "dotnet-test",
26
    UnleashApi = new Uri("https://eu.app.unleash-hosted.com/demo/api/"),
27
    UnleashContextProvider = new AspNetContextProvider(),
28
    CustomHttpHeaders = new Dictionary<string, string>()
29
    {
30
      {"Authorization", "API token" }
31
    }
32
};

Custom HTTP headers

If you want the client to send custom HTTP Headers with all requests to the Unleash api you can define that by setting them via the UnleashSettings.

1
var settings = new UnleashSettings()
2
{
3
    AppName = "dotnet-test",
4
    UnleashApi = new Uri("https://eu.app.unleash-hosted.com/demo/api/"),
5
    UnleashContextProvider = new AspNetContextProvider(),
6
    CustomHttpHeaders = new Dictionary<string, string>()
7
    {
8
        {"Authorization", "API token" }
9
    }
10
};

Custom HttpClient initialization

If you need to specify HttpMessageHandlers or to control the instantiation of the HttpClient, you can create a custom HttpClientFactory that inherits from DefaultHttpClientFactory, and override the method CreateHttpClientInstance. Then configure UnleashSettings to use your custom HttpClientFactory.

1
internal class CustomHttpClientFactory : DefaultHttpClientFactory
2
{
3
    protected override HttpClient CreateHttpClientInstance(Uri unleashApiUri)
4
    {
5
        var messageHandler = new CustomHttpMessageHandler();
6
        var httpClient = new HttpClient(messageHandler)
7
        {
8
            BaseAddress = apiUri,
9
            Timeout = TimeSpan.FromSeconds(5)
10
        };
11
    }
12
}
13
14
var settings = new UnleashSettings
15
{
16
    AppName = "dotnet-test",
17
    //...
18
    HttpClientFactory = new CustomHttpClientFactory()
19
};

Dynamic custom HTTP headers

If you need custom http headers that change during the lifetime of the client, a provider can be defined via the UnleashSettings.

1
Public Class CustomHttpHeaderProvider
2
    Implements IUnleashCustomHttpHeaderProvider
3
4
    Public Function GetCustomHeaders() As Dictionary(Of String, String) Implements IUnleashCustomHttpHeaderProvider.GetCustomHeaders
5
        Dim token = ' Acquire or refresh a token
6
        Return New Dictionary(Of String, String) From
7
                {{"Authorization", "Bearer " & token}}
8
    End Function
9
End Class
10
11
' ...
12
13
Dim unleashSettings As New UnleashSettings()
14
unleashSettings.AppName = "dotnet-test"
15
unleashSettings.InstanceTag = "instance z"
16
' add the custom http header provider to the settings
17
unleashSettings.UnleashCustomHttpHeaderProvider = New CustomHttpHeaderProvider()
18
unleashSettings.UnleashApi = new Uri("https://eu.app.unleash-hosted.com/demo/api/")
19
unleashSettings.UnleashContextProvider = New AspNetContextProvider()
20
Dim unleash = New DefaultUnleash(unleashSettings)

Logging

By default Unleash-client uses LibLog to integrate with the currently configured logger for your application. The supported loggers are:

• Serilog
• NLog
• Log4Net
• EntLib
• Loupe

Custom logger integration

To plug in your own logger you can implement the ILogProvider interface, and register it with Unleash:

1
Unleash.Logging.LogProvider.SetCurrentLogProvider(new CustomLogProvider());
2
var settings = new UnleashSettings()
3
//...

The GetLogger method is responsible for returning a delegate to be used for logging, and your logging integration should be placed inside that delegate:

1
using System;
2
using Unleash.Logging;
3
4
namespace Unleash.Demo.CustomLogging
5
{
6
    public class CustomLogProvider : ILogProvider
7
    {
8
        public Logger GetLogger(string name)
9
        {
10
            return (logLevel, messageFunc, exception, formatParameters) =>
11
            {
12
                // Plug in your logging code here
13
14
                return true;
15
            };
16
        }
17
18
        public IDisposable OpenMappedContext(string key, object value, bool destructure = false)
19
        {
20
            return new EmptyIDisposable();
21
        }
22
23
        public IDisposable OpenNestedContext(string message)
24
        {
25
            return new EmptyIDisposable();
26
        }
27
    }
28
29
    public class EmptyIDisposable : IDisposable
30
    {
31
        public void Dispose()
32
        {
33
        }
34
    }
35
}

Local caching and offline behavior

By default unleash-client fetches the feature flags from unleash-server every 20s, and stores the result in temporary .json file which is located in System.IO.Path.GetTempPath() directory. This means that if the unleash-server becomes unavailable, the unleash-client will still be able to toggle the features based on the values stored in .json file. As a result of this, the second argument of IsEnabled will be returned in two cases:

• When .json file does not exists
• When the named feature toggle does not exist in .json file

The backup file name will follow this pattern: {fileNameWithoutExtension}-{AppName}-{InstanceTag}-{SdkVersion}.{extension}, where InstanceTag is either what you configure on UnleashSettings during startup, or a formatted string with a random component following this pattern: {Dns.GetHostName()}-generated-{Guid.NewGuid()}.

You can configure InstanceTag like this:

1
var settings = new UnleashSettings()
2
{
3
    AppName = "dotnet-test",
4
    UnleashApi = new Uri("https://eu.app.unleash-hosted.com/demo/api/"),
5
    // Set an instance tag for consistent backup file naming
6
    InstanceTag = "CustomInstanceTag",
7
    UnleashContextProvider = new AspNetContextProvider(),
8
    CustomHttpHeaders = new Dictionary<string, string>()
9
    {
10
        {"Authorization", "API token" }
11
    }
12
};

Bootstrap

You can bootstrap the SDK with flag configuration to evaluate flags before connecting to Unleash. This is useful for applications deployed to ephemeral containers or environments where writing a local backup file is not possible.

By default, bootstrap data overrides any locally cached data. Set BootstrapOverride to false to keep cached data when available.

You can implement a custom provider using the IToggleBootstrapProvider interface, or use one of the built-in providers from Unleash.Utilities. Example bootstrap files are available in tests/Unleash.Tests/App_Data.

1
var settings = new UnleashSettings()
2
{
3
    AppName = "dotnet-test",
4
    UnleashApi = new Uri("https://<your-unleash-instance>/api/"),
5
    CustomHttpHeaders = new Dictionary<string, string>()
6
    {
7
        { "Authorization", "<your-backend-token>" }
8
    },
9
    ToggleOverride = false, // Defaults to true
10
    ToggleBootstrapProvider = new MyToggleBootstrapProvider()
11
};

Unit testing

You may want to mock the IUnleash interface in your unit tests. The SDK comes with a FakeUnleash implementation that you can use for this purpose.

Example usage:

1
var fakeUnleash = new FakeUnleash(); // Toggles and variants will be disabled by default
2
fakeUnleash.EnableAllToggles(); // All toggles will be enabled
3
fakeUnleash.DisableAllToggles(); // All toggles will be disabled
4
fakeUnleash.SetToggle("MyFeature", true); // Set a specific toggle to enabled
5
fakeUnleash.SetVariant("MyVariantFeature", new Variant("MyVariantFeature", new Payload("string", "valueA"), true, true)); // Set a specific variant

Migrating to v5

If you use bootstrapping, custom strategies, or a custom JSON serializer, read the complete v5 migration guide before upgrading.