.NET SDK reference (server-side)

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.

Get started

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.

We recommend making the LaunchDarkly observability plugin available as well. This plugin collects and sends observability data to LaunchDarkly. This means you can review error monitoring and logs from within the LaunchDarkly UI. It requires the .NET (server-side) SDK version 8.10 or later.

Here’s how:

$
Install-Package LaunchDarkly.ServerSdk
$
dotnet add package LaunchDarkly.Observability

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

1
using LaunchDarkly.Sdk;
2
using LaunchDarkly.Sdk.Server;
3
using LaunchDarkly.Observability;
4
5
6
// LaunchDarkly.Sdk defines general types like Context, which are also used in the client-side .NET SDK.
7
// LaunchDarkly.Sdk.Server defines the LdClient and Configuration types for the server-side .NET SDK.
8
// LaunchDarkly.Observability defines the optional observability,
9
// which requires .NET (server-side) SDK version 8.10 or later.

Initialize the client

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

To create a single instance:

1
var builder = WebApplication.CreateBuilder(args);
2
3
var config = Configuration.Builder("YOUR_SDK_KEY")
4
  .StartWaitTime(TimeSpan.FromSeconds(5))
5
  .Plugins(new PluginConfigurationBuilder()
6
      .Add(ObservabilityPlugin.Builder(builder.Services)
7
          .WithServiceName("your-service-name")
8
          .WithServiceVersion("example-sha")
9
          .Build()
10
      )
11
  ).Build();
12
13
var client = new LdClient(config);
14
15
// Client must be constructed before the web application.
16
var app = builder.Build();

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

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 Context configuration.

In the v7 example, the context key is the string “example-context-key”. In the v6 example, the user key is the string “example-user-key”:

1
var context = Context.Builder("example-context-key")
2
  .Name("Sandy")
3
  .Build();
4
5
var flagValue = client.BoolVariation("example-flag-key", context, false);
6
7
if (flagValue) {
8
    // application code to show the feature
9
}
10
else {
11
    // the code to run if the feature is off
12
}

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

1
var context = Context.Builder("example-context-key")
2
  .Kind("device")
3
  .Name("Android")
4
  .Build();

To learn more, read 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:

1
// Use `stream-tls10.launchdarkly.com` and `events-tls10.launchdarkly.com` TLSv1 endpoints
2
var config = Configuration.Builder("YOUR_SDK_KEY")
3
    .ServiceEndpoints(
4
        Components.ServiceEndpoints()
5
          .Streaming("https://stream-tls10.launchdarkly.com")
6
          .Events("https://events-tls10.launchdarkly.com"))
7
    .Build();

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:

• Anonymous contexts and users
• Big segments
• Configuration, including
  • Application metadata configuration
  • Migration configuration
  • Service endpoint configuration
• Context configuration
• Data saving mode
• Evaluating flags
• Flag evaluation reasons
• Flushing events
• Getting all flags
• Hooks
• Identifying and changing contexts
• Logging configuration
• Migrations
• Monitoring SDK status
• Observability
• Offline mode
• OpenTelemetry
• Private attributes
• Reading flags from a file
• Relay Proxy configuration
  • Using proxy mode
  • Using daemon mode
• Secure mode
• Sending custom events
• Shutting down
• Storing data
• Subscribing to flag changes
• Test data sources
• Web proxy configuration