.NET (client-side) SDK 4.x to 5.0 migration guide

Read time: 3 minutes

Last edited: Jun 07, 2024

Overview

This topic explains the changes in the .NET (client-side) SDK 5.0 release and how to migrate to that version.

The .NET (client-side) SDK 5.0 release is currently in alpha.

Version 5.0 contains breaking changes. It introduces support for .NET 7 and MAUI, and drops support for Xamarin. As part of this change, the values of some environment attributes have changed. You may need to adjust your flag targeting rules as a result.

Understanding changes to SDK compatibility

You can continue to use the LaunchDarkly .NET (client-side) SDK version 5 in applications that can use Microsoft's .NET Standard version 2.0 or higher, for example, console applications. You can also use it with MAUI, for example, for Android, Windows, and Mac applications.

If you use Xamarin, you cannot use version 5 of the LaunchDarkly .NET (client-side) SDK. You must migrate to MAUI to continue using the LaunchDarkly SDK. To learn more about migrating, read Microsoft's documentation on how to Upgrade from Xamarin to .NET.

Understanding changes to automatic environment attributes

When you upgrade your .NET (client-side) SDK to version 5, you should review your flag targeting rules carefully. Some of the automatic environment attributes you may use in your targeting rules may have changed as part of the new SDK version.

If you enable automatic environment attributes during SDK initialization, LaunchDarkly automatically provides data about the environment where the application is running. This data makes it simpler to target your mobile customers based on application name or version, or on device characteristics including manufacturer, model, operating system, locale, and so on.

Here's how:

var config = Configuration
    .Builder("mobile-key-123abc", ConfigurationBuilder.AutoEnvAttributes.Enabled)
    .Build();

This data is provided in two context kinds, ld_application and ld_device. The SDK automatically adds this data to each evaluation context you provide. To learn more, read Automatic environment attributes.

When you upgrade from version 4 to version 5 of the LaunchDarkly .NET (client-side) SDK, the SDK returns different values for some of the attributes in the ld_application and ld_device contexts:

For Android, the ld_device attribute os/name now returns only the name. For example, the version 5 SDK returns Android, while the version 4 SDK returns Android28 or similar. Use the ld_device attribute os/version to access the version information.
For iOS, the ld_device attribute model now returns model numbers in some cases. For example, the version 5 SDK returns iPad5,2 or iPhone10,3, while the version 4 SDK returns iPad or iPhone.
For iOS, the ld_application attribute name is populated as follows:
- ld_application.name returns the name that you set using application metadata configuration in the SDK, if any.
- If that is not set, then the version 5 SDK returns the CFBundleDisplayName if defined. Otherwise, it returns the CFBundleName. This is a change in behavior. The version 4 SDK always returns the CFBundleName.
- If that is not set, ld_application.name returns the LaunchDarkly SDK name and version.

These different context attribute values are because version 5 of the LaunchDarkly SDK uses .NET MAUI, while version 4 uses Xamarin Essentials.