No results for ""
EXPAND ALL
  • Home
  • API docs

GIVE DOCS FEEDBACK

.NET SDK reference (server-side)

Read time: 6 minutes
Last edited: May 20, 2024
Recent major versions

Version 8 of the .NET SDK supports migration feature flags. These are temporary flags used to migrate data or systems while keeping your application available and disruption free. To learn more about upgrading, read .NET SDK 7.x to 8.0 migration guide.

Version 7 of the .NET SDK replaces users with contexts. A context is a generalized way of referring to the people, services, machines, or other resources that encounter feature flags in your product. Contexts replace another data object in LaunchDarkly: "users." To learn more about upgrading, read .NET (server-side) SDK 6.x to 7.0 migration guide and Best practices for upgrading users to contexts.

Code samples on this page are from the three most recent SDK versions where they differ.

Overview

This topic documents how to get started with the server-side .NET SDK, and links to reference information on all of the supported features.

SDK quick links

LaunchDarkly's SDKs are open source. In addition to this reference guide, we provide source, API reference documentation, and a sample application:

ResourceLocation
SDK API documentationSDK API docs
GitHub repositorydotnet-server-sdk
Sample application.NET (server-side)
OpenFeature .NET (server-side)
Published moduleNuGet
For use in server-side applications only

This SDK is intended for use in multi-user .NET server applications. If you have a .NET application and want to set up LaunchDarkly in a mobile, desktop, or embedded application, read the client-side .NET SDK reference.

To learn more about LaunchDarkly's different SDK types, read Client-side, server-side, and edge SDKs.

Get started

SDK version compatibility

The LaunchDarkly .NET SDK, version 7.0 and higher, is compatible with .NET 6.0+, .NET Framework 4.6.2+, .NET Standard 2.0+, and .NET Core 3.1.

Prior to version 7.0, the LaunchDarkly .NET SDK also supported .NET 5.0, .NET Framework 4.5.2 and .NET Framework 4.6.1, and .NET Core 2.1.

After you complete the Getting Started process, follow these instructions to start using the LaunchDarkly SDK in your .NET application.

Install the SDK

First, install the LaunchDarkly SDK as a dependency in your application using your application's dependency manager.

Here's how:

Install-Package LaunchDarkly.ServerSdk

Next, import the LaunchDarkly SDK's namespaces in your application code. The namespace is not the same as the package name:

using LaunchDarkly.Sdk;
using LaunchDarkly.Sdk.Server;
// LaunchDarkly.Sdk defines general types like Context, which are also used in the client-side .NET SDK.
// LaunchDarkly.Sdk.Server defines the LdClient and Configuration types for the server-side .NET SDK.
The .NET (server-side) SDK uses an SDK key

The .NET (server-side) SDK uses an SDK key. Your environment's SDK key is available in the Projects tab of your Account settings page. To learn more about key types, read Keys.

Initialize the client

After you install and import the SDK, create a single, shared instance of LdClient. Specify your SDK key here to authorize your application to connect to a particular environment within LaunchDarkly.

To create a single instance:

LdClient client = new LdClient("sdk-key-123abc");

When you initialize the client, you can optionally provide configuration options. To learn how, read Configuration. To learn more about the specific configuration that are available in this SDK, read ConfigurationBuilder.

LdClient should be a singleton

In the standard use case where there is only one SDK key, it's important to make the LdClient a singleton for each LaunchDarkly project. The client instance maintains internal state that allows LaunchDarkly to serve feature flags without making any remote requests. Do not instantiate a new client with every request.

If you need to use more than one SDK key, the SDK allows you to create more than one LdClient instance. This is an uncommon requirement, but one the SDK supports.

If you have multiple LaunchDarkly projects, you can create one LDClient for each. In this situation, the clients operate independently. For example, they do not share a single connection to LaunchDarkly.

Evaluate a context

You can use client to check which variation a particular context will receive for a given feature flag. To learn more, read Evaluating flags and Flag evaluation reasons. For more information about how contexts are specified, read User and context configuration.

In the v7 example, the context key is the string "context-key-123abc". In the v6 example, the user key is the string "user-key-123abc":

var context = Context.Builder("context-key-123abc")
.Name("Sandy")
.Build();
var flagValue = client.BoolVariation(FeatureFlagKey, context, false);
if (flagValue) {
// application code to show the feature
}
else {
// the code to run if the feature is off
}

Contexts have a context kind of "user" by default. To specify a different kind, use the Kind method:

var context = Context.Builder("context-key-123abc")
.Kind("device")
.Name("Android")
.Build();

To learn more, read Contexts and context kinds.

Transport Layer Security (TLS) and other networking issues

LaunchDarkly is deprecating support for TLS versions 1.0 and 1.1. .NET applications running on older operating systems are prone to use these older, less secure versions of TLS. It is possible to increase your application's security using AppContext switches.

To learn more, read Microsoft's documentation.

If you cannot update your application platform's configurations to support TLS version 1.2, you can update your application's SDK configuration to use new LaunchDarkly endpoints that support TLS versions 1.0 and later. Here is an example:

// Use `stream-tls10.launchdarkly.com` and `events-tls10.launchdarkly.com` TLSv1 endpoints
var config = Configuration.Builder("sdk-key-123abc")
.DataSource(
Components.StreamingDataSource()
.BaseUri(new Uri("https://stream-tls10.launchdarkly.com")))
.Events(
Components.SendEvents()
.BaseUri(new Uri("https://events-tls10.launchdarkly.com")))
.Build();
Potential network connectivity issues caused by DNS caching

LaunchDarkly servers operate in a load-balancing framework which may cause their IP addresses to change. This could result in the SDK failing to connect to LaunchDarkly if an old IP address is still in your system's DNS cache. In .NET, the DNS cache retains IP addresses for two minutes by default. If you notice intermittent connection failures that always resolve in two minutes, you may want to change this setting to a lower value as described in Microsoft's documentation.

Shut down the client

Shut down the client when your application terminates. To learn more, read Shutting down.

Supported features

This SDK supports the following features: