Unleash.Client
4.1.6
See the version list below for details.
dotnet add package Unleash.Client --version 4.1.6
NuGet\Install-Package Unleash.Client -Version 4.1.6
<PackageReference Include="Unleash.Client" Version="4.1.6" />
paket add Unleash.Client --version 4.1.6
#r "nuget: Unleash.Client, 4.1.6"
// Install Unleash.Client as a Cake Addin #addin nuget:?package=Unleash.Client&version=4.1.6 // Install Unleash.Client as a Cake Tool #tool nuget:?package=Unleash.Client&version=4.1.6
Unleash FeatureToggle Client for .Net
Introduction
Unleash Client SDK for .Net. It is compatible with the Unleash-hosted.com SaaS offering and Unleash Open-Source.
The main motivation for doing feature toggling is to decouple the process for deploying code to production and releasing new features. This helps reducing risk, and allow us to easily manage which features to enable.
Feature toggles decouple deployment of code from release of new features.
Take a look at the demonstration site at unleash.herokuapp.com
Read more of the main project at github.com/unleash/unleash
Features
Supported Frameworks
- NET Standard 2.0
- .Net 4.8
- .Net 4.7.2
- .Net 4.7
- .Net 4.6.1
- .Net 4.6
- .Net 4.5.1
- .Net 4.5
Extendable architecture
- Inject your own implementations of key components (Json serializer, background task scheduler, http client factory)
Getting started
Install the package
Install the latest version of Unleash.Client
from nuget.org or use the dotnet
cli:
dotnet add package unleash.client
If you do not have a json library in your project:
dotnet add package Newtonsoft.Json
Create a new a Unleash instance
⚠️ Important: In almost every case, you only want a single, shared instance of the Unleash client (a singleton) in your application . You would typically use a dependency injection framework to inject it where you need it. Having multiple instances of the client in your application could lead to inconsistencies and performance degradation.
If you create more than 10 instances, Unleash will attempt to log warnings about your usage.
To create a new instance of Unleash you need to create and pass in an UnleashSettings
object.
When creating an instance of the Unleash client, you can choose to do it either synchronously or asynchronously. The SDK will synchronize with the Unleash API on initialization, so it can take a moment for the it to reach the correct state. With an asynchronous startup, this would happen in the background while the rest of your code keeps executing. In most cases, this isn't an issue. But if you want to wait until the SDK is fully synchronized, then you should use the configuration explained in the synchronous startup section. This is usually not an issue and Unleash will do this in the background as soon as you initialize it. However, if it's important that you do not continue execution until the SDK has synchronized, then you should use the configuration explained in the synchronous startup section.
using Unleash;
var settings = new UnleashSettings()
{
AppName = "dotnet-test",
UnleashApi = new Uri("<your-api-url>"),
CustomHttpHeaders = new Dictionary()
{
{"Authorization","<your-api-token>" }
}
};
var unleash = new DefaultUnleash(settings);
// Add to Container as Singleton
// .NET Core 3/.NET 5/...
services.AddSingleton<IUnleash>(c => unleash);
When your application shuts down, remember to dispose the unleash instance.
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.
using Unleash;
using Unleash.ClientFactory;
var settings = new UnleashSettings()
{
AppName = "dotnet-test",
UnleashApi = new Uri("<your-api-url>"),
CustomHttpHeaders = new Dictionary<string, string>()
{
{"Authorization","<your-api-token>" }
}
};
var unleashFactory = new UnleashClientFactory();
IUnleash unleash = await unleashFactory.CreateClientAsync(settings, synchronousInitialization: true);
// this `unleash` has successfully fetched feature toggles and written them to its cache.
// if network errors or disk permissions prevented this from happening, the above await would have thrown an exception
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.
Configuring projects in unleash client
If you're organizing your feature toggles in Projects
in Unleash Enterprise, you can specify the ProjectId
on the UnleashSettings
to select which project to fetch feature toggles for.
var settings = new UnleashSettings()
{
AppName = "dotnet-test",
UnleashApi = new Uri("http://unleash.herokuapp.com/api/"),
ProjectId = "projectId"
};
Check feature toggles
The IsEnabled
method allows you to check whether a feature is enabled:
if(unleash.IsEnabled("SuperAwesomeFeature"))
{
//do some magic
}
else
{
//do old boring stuff
}
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:
unleash.IsEnabled("SuperAwesomeFeature", true)
Providing context
You can also provide an Unleash context to the IsEnabled
method:
var context = new UnleashContext
{
UserId = "61"
};
unleash.IsEnabled("someToggle", context);
Refer to the Unleash context section for more information about using the Unleash context in the .NET SDK.
Handling events
Currently supported events:
- Impression data events
- Error events
- Toggles updated event
var settings = new UnleashSettings()
{
// ...
};
var unleash = new DefaultUnleash(settings);
// Set up handling of impression and error events
unleash.ConfigureEvents(cfg =>
{
cfg.ImpressionEvent = evt => { Console.WriteLine($"{evt.FeatureName}: {evt.Enabled}"); };
cfg.ErrorEvent = evt => { /* Handling code here */ Console.WriteLine($"{evt.ErrorType} occured."); };
cfg.TogglesUpdatedEvent = evt => { /* Handling code here */ Console.WriteLine($"Toggles updated on: {evt.UpdatedOn}"); };
});
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.
IStrategy s1 = new MyAwesomeStrategy();
IStrategy s2 = new MySuperAwesomeStrategy();
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:
HttpContext.Current.Items["UnleashContext"] = new UnleashContext
{
UserId = HttpContext.Current.User?.Identity?.Name,
SessionId = HttpContext.Current.Session?.SessionID,
RemoteAddress = HttpContext.Current.Request.UserHostAddress,
Properties = new Dictionary<string, string>
{
// Obtain "customField" and add it to the context properties
{ "customField", HttpContext.Current.Items["customField"].ToString() }
}
};
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.
public class AspNetContextProvider : IUnleashContextProvider
{
public UnleashContext Context
{
get { return HttpContext.Current?.Items["UnleashContext"] as UnleashContext; }
}
}
protected void Application_BeginRequest(object sender, EventArgs e)
{
HttpContext.Current.Items["UnleashContext"] = new UnleashContext
{
UserId = HttpContext.Current.User?.Identity?.Name,
SessionId = HttpContext.Current.Session?.SessionID,
RemoteAddress = HttpContext.Current.Request.UserHostAddress,
Properties = new Dictionary<string, string>()
{
{"UserRoles", "A,B,C"}
}
};
}
var settings = new UnleashSettings()
{
AppName = "dotnet-test",
UnleashApi = new Uri("http://unleash.herokuapp.com/api/"),
UnleashContextProvider = new AspNetContextProvider(),
CustomHttpHeaders = new Dictionary()
{
{"Authorization", "API token" }
}
};
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
.
var settings = new UnleashSettings()
{
AppName = "dotnet-test",
UnleashApi = new Uri("http://unleash.herokuapp.com/api/"),
UnleashContextProvider = new AspNetContextProvider(),
CustomHttpHeaders = new Dictionary<string, string>()
{
{"Authorization", "API token" }
}
};
HttpMessageHandlers/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.
internal class CustomHttpClientFactory : DefaultHttpClientFactory
{
protected override HttpClient CreateHttpClientInstance(Uri unleashApiUri)
{
var messageHandler = new CustomHttpMessageHandler();
var httpClient = new HttpClient(messageHandler)
{
BaseAddress = apiUri,
Timeout = TimeSpan.FromSeconds(5)
};
}
}
var settings = new UnleashSettings
{
AppName = "dotnet-test",
//...
HttpClientFactory = new CustomHttpClientFactory()
};
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
.
Public Class CustomHttpHeaderProvider
Implements IUnleashCustomHttpHeaderProvider
Public Function GetCustomHeaders() As Dictionary(Of String, String) Implements IUnleashCustomHttpHeaderProvider.GetCustomHeaders
Dim token = ' Acquire or refresh a token
Return New Dictionary(Of String, String) From
{{"Authorization", "Bearer " & token}}
End Function
End Class
' ...
Dim unleashSettings As New UnleashSettings()
unleashSettings.AppName = "dotnet-test"
unleashSettings.InstanceTag = "instance z"
' add the custom http header provider to the settings
unleashSettings.UnleashCustomHttpHeaderProvider = New CustomHttpHeaderProvider()
unleashSettings.UnleashApi = new Uri("http://unleash.herokuapp.com/api/")
unleashSettings.UnleashContextProvider = New AspNetContextProvider()
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:
Unleash.Logging.LogProvider.SetCurrentLogProvider(new CustomLogProvider());
var settings = new UnleashSettings()
//...
The GetLogger
method is responsible for returning a delegate to be used for logging, and your logging integration should be placed inside that delegate:
using System;
using Unleash.Logging;
namespace Unleash.Demo.CustomLogging
{
public class CustomLogProvider : ILogProvider
{
public Logger GetLogger(string name)
{
return (logLevel, messageFunc, exception, formatParameters) =>
{
// Plug in your logging code here
return true;
};
}
public IDisposable OpenMappedContext(string key, object value, bool destructure = false)
{
return new EmptyIDisposable();
}
public IDisposable OpenNestedContext(string message)
{
return new EmptyIDisposable();
}
}
public class EmptyIDisposable : IDisposable
{
public void Dispose()
{
}
}
}
Local backup
By default unleash-client fetches the feature toggles 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:
var settings = new UnleashSettings()
{
AppName = "dotnet-test",
UnleashApi = new Uri("http://unleash.herokuapp.com/api/"),
// Set an instance tag for consistent backup file naming
InstanceTag = "CustomInstanceTag",
UnleashContextProvider = new AspNetContextProvider(),
CustomHttpHeaders = new Dictionary<string, string>()
{
{"Authorization", "API token" }
}
};
Bootstrapping
- Unleash supports bootstrapping from a JSON string.
- Configure your own custom provider implementing the
IToggleBootstrapProvider
interface's single methodToggleCollection Read()
. This should return aToggleCollection
. TheUnleashSettings.JsonSerializer
can be used to deserialize a JSON string in the same format returned from/api/client/features
. - Example bootstrap files can be found in the json files located in tests/Unleash.Tests/App_Data
- Our assumption is this can be use for applications deployed to ephemeral containers or more locked down file systems where Unleash's need to write the backup file is not desirable or possible.
- Loading with bootstrapping defaults to override feature toggles loaded from Local Backup, this override can be switched off by setting the
UnleashSettings.ToggleOverride
property tofalse
Configuring with the UnleashSettings:
var settings = new UnleashSettings()
{
AppName = "dotnet-test",
UnleashApi = new Uri("http://unleash.herokuapp.com/api/"),
CustomHttpHeaders = new Dictionary()
{
{"Authorization","API token" }
},
ToggleOverride = false, // Defaults to true
ToggleBootstrapProvider = new MyToggleBootstrapProvider() // A toggle bootstrap provider implementing IToggleBootstrapProvider here
};
Provided Bootstrappers
- Two ToggleBootstrapProviders are provided
- These are found in the
Unleash.Utilities
:
ToggleBootstrapFileProvider
- Unleash comes with a
ToggleBootstrapFileProvider
which implements theIToggleBootstrapProvider
interface. - Configure with
UnleashSettings
helper method:
settings.UseBootstrapFileProvider("./path/to/file.json");
ToggleBootstrapUrlProvider
Unleash also comes with a
ToggleBootstrapUrlProvider
which implements theIToggleBootstrapProvider
interface.Fetches JSON from a webaddress using
HttpMethod.Get
Configure with
UnleashSettings
helper method:
var shouldThrowOnError = true; // Throws for 500, 404, etc
var customHeaders = new Dictionary<string, string>()
{
{ "Authorization", "Bearer ABCdefg123" } // Or whichever set of headers would be required to GET this file
}; // Defaults to null
settings.UseBootstrapUrlProvider("://domain.top/path/to/file.json", shouldThrowOnError, customHeaders);
Json Serialization
The unleash client is dependant on a json serialization library. If your application already have Newtonsoft.Json >= 9.0.1 installed, everything should work out of the box. If not, you will get an error message during startup telling you to implement an 'IJsonSerializer' interface, which needs to be added to the configuration.
With Newtonsoft.Json version 7.0.0.0, the following implementation can be used. For older versions, consider to upgrade.
var settings = new UnleashSettings()
{
AppName = "dotnet-test",
UnleashApi = new Uri("http://unleash.herokuapp.com/api/"),
JsonSerializer = new NewtonsoftJson7Serializer()
};
public class NewtonsoftJson7Serializer : IJsonSerializer
{
private readonly Encoding utf8 = Encoding.UTF8;
private static readonly JsonSerializer Serializer = new JsonSerializer()
{
ContractResolver = new CamelCaseExceptDictionaryKeysResolver()
};
public T Deserialize<T>(Stream stream)
{
using (var streamReader = new StreamReader(stream, utf8))
using (var textReader = new JsonTextReader(streamReader))
{
return Serializer.Deserialize<T>(textReader);
}
}
public void Serialize<T>(Stream stream, T instance)
{
using (var writer = new StreamWriter(stream, utf8, 1024 * 4, leaveOpen: true))
using (var jsonWriter = new JsonTextWriter(writer))
{
Serializer.Serialize(jsonWriter, instance);
jsonWriter.Flush();
stream.Position = 0;
}
}
class CamelCaseExceptDictionaryKeysResolver : CamelCasePropertyNamesContractResolver
{
protected override JsonDictionaryContract CreateDictionaryContract(Type objectType)
{
var contract = base.CreateDictionaryContract(objectType);
contract.DictionaryKeyResolver = propertyName =>
{
return propertyName;
};
return contract;
}
}
}
The server api needs camel cased json, but not for certain dictionary keys. The implementation can be naively validated by the JsonSerializerTester.Assert
function. (Work in progress).
Run unleash server with Docker locally
The Unleash team have made a separate project which runs unleash server inside docker. Please see unleash-docker for more details.
Development
Visual Studio 2017 / Code
Cakebuild
Other information
- Check out our guide for more information on how to build and scale feature flag systems
Product | Versions Compatible and additional computed target framework versions. |
---|---|
.NET | net5.0 was computed. net5.0-windows was computed. net6.0 was computed. net6.0-android was computed. net6.0-ios was computed. net6.0-maccatalyst was computed. net6.0-macos was computed. net6.0-tvos was computed. net6.0-windows was computed. net7.0 was computed. net7.0-android was computed. net7.0-ios was computed. net7.0-maccatalyst was computed. net7.0-macos was computed. net7.0-tvos was computed. net7.0-windows was computed. net8.0 was computed. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. |
.NET Core | netcoreapp2.0 was computed. netcoreapp2.1 was computed. netcoreapp2.2 was computed. netcoreapp3.0 was computed. netcoreapp3.1 was computed. |
.NET Standard | netstandard2.0 is compatible. netstandard2.1 was computed. |
.NET Framework | net45 is compatible. net451 is compatible. net452 was computed. net46 is compatible. net461 is compatible. net462 was computed. net463 was computed. net47 is compatible. net471 was computed. net472 is compatible. net48 is compatible. net481 was computed. |
MonoAndroid | monoandroid was computed. |
MonoMac | monomac was computed. |
MonoTouch | monotouch was computed. |
Tizen | tizen40 was computed. tizen60 was computed. |
Xamarin.iOS | xamarinios was computed. |
Xamarin.Mac | xamarinmac was computed. |
Xamarin.TVOS | xamarintvos was computed. |
Xamarin.WatchOS | xamarinwatchos was computed. |
-
.NETFramework 4.5
- murmurhash (>= 1.0.3)
- NuGet.Versioning (>= 6.1.0)
-
.NETFramework 4.5.1
- murmurhash (>= 1.0.3)
- NuGet.Versioning (>= 6.1.0)
-
.NETFramework 4.6
- murmurhash (>= 1.0.3)
- NuGet.Versioning (>= 6.1.0)
-
.NETFramework 4.6.1
- murmurhash (>= 1.0.3)
- NuGet.Versioning (>= 6.1.0)
-
.NETFramework 4.7
- murmurhash (>= 1.0.3)
- NuGet.Versioning (>= 6.1.0)
-
.NETFramework 4.7.2
- murmurhash (>= 1.0.3)
- NuGet.Versioning (>= 6.1.0)
-
.NETFramework 4.8
- murmurhash (>= 1.0.3)
- NuGet.Versioning (>= 6.1.0)
-
.NETStandard 2.0
- Microsoft.CSharp (>= 4.5.0)
- murmurhash (>= 1.0.3)
- NuGet.Versioning (>= 6.1.0)
NuGet packages (4)
Showing the top 4 NuGet packages that depend on Unleash.Client:
Package | Downloads |
---|---|
PiBox.Plugins.Management.Unleash
PiBox is a `service hosting framework` that allows `.net devs` to `decorate their services with behaviours or functionality (think of plugins) while only using minimal configuration`. |
|
Gems.FeatureToggle
Package Description |
|
FeatureFleet
A .NET library for streamlined feature flag implementation, enabling teams to deliver code faster and with higher quality. Choose from multiple feature flag implementations such as "Unleash," "InMemory," and "Azure Feature Manager" to suit your project's needs. |
|
Alaman.Utils
Вспомогательные библиотеки |
GitHub repositories
This package is not used by any popular GitHub repositories.
Version | Downloads | Last updated |
---|---|---|
4.1.11-beta.0 | 33 | 8/13/2024 |
4.1.10 | 21,168 | 7/29/2024 |
4.1.9 | 330,631 | 4/22/2024 |
4.1.8 | 5,298 | 4/18/2024 |
4.1.8-beta.0 | 47 | 4/18/2024 |
4.1.7 | 1,041,981 | 3/1/2024 |
4.1.7-beta.0 | 51 | 2/22/2024 |
4.1.6 | 58,858 | 2/8/2024 |
4.1.5 | 242,136 | 1/22/2024 |
4.1.4 | 3,076 | 1/19/2024 |
4.1.3 | 44,727 | 1/10/2024 |
4.1.2 | 114,643 | 1/3/2024 |
4.1.2-beta.0 | 59 | 1/3/2024 |
4.1.1 | 66,067 | 12/8/2023 |
4.1.0 | 106,315 | 11/29/2023 |
4.1.0-beta.0 | 61 | 11/28/2023 |
4.0.0 | 159,491 | 10/31/2023 |
3.4.1 | 83,129 | 10/20/2023 |
3.4.1-beta.0 | 73 | 10/20/2023 |
3.4.0 | 3,952 | 10/17/2023 |
3.3.3 | 54,731 | 10/4/2023 |
3.3.3-beta.0 | 68 | 10/4/2023 |
3.3.2 | 290,060 | 9/8/2023 |
3.3.1-beta.0 | 71 | 9/7/2023 |
3.3.0 | 53,418 | 8/24/2023 |
3.2.0 | 13,364 | 8/17/2023 |
3.1.0 | 93,853 | 8/14/2023 |
3.0.1 | 58,827 | 7/14/2023 |
3.0.0 | 293,187 | 6/15/2023 |
3.0.0-beta.0 | 75 | 6/13/2023 |
2.5.0 | 234,323 | 5/22/2023 |
2.4.3 | 377,009 | 3/8/2023 |
2.4.2 | 582,007 | 2/28/2023 |
2.4.1 | 33,668 | 2/22/2023 |
2.4.0 | 191,248 | 1/10/2023 |
2.4.0-beta.0 | 116 | 12/13/2022 |
2.3.1 | 426,928 | 10/20/2022 |
2.3.1-beta.0 | 127 | 10/20/2022 |
2.3.0 | 25,190 | 10/11/2022 |
2.3.0-beta.0 | 238 | 9/1/2022 |
2.2.0 | 592,376 | 6/7/2022 |
2.2.0-beta.0 | 122 | 5/10/2022 |
2.1.0 | 215,263 | 4/25/2022 |
2.1.0-beta1 | 712 | 4/6/2022 |
2.1.0-beta | 667 | 3/31/2022 |
2.0.0 | 466,283 | 8/18/2021 |
2.0.0-beta | 14,321 | 7/2/2021 |
1.6.1 | 359,513 | 10/20/2020 |
1.6.0 | 11,438 | 10/4/2020 |
1.5.1 | 11,596 | 8/21/2020 |
1.5.0 | 2,615 | 7/27/2020 |
1.4.1 | 23,256 | 6/23/2020 |
1.4.0 | 75,836 | 2/26/2020 |
0.0.23 | 1,536 | 11/24/2017 |
0.0.22 | 1,502 | 11/22/2017 |
0.0.20 | 1,383 | 11/18/2017 |
0.0.14 | 1,423 | 11/18/2017 |
0.0.13 | 1,484 | 11/15/2017 |
0.0.11 | 1,906 | 11/14/2017 |