> ## Documentation Index
> Fetch the complete documentation index at: https://launchdarkly.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# .NET (client-side) SDK 3.x to 4.0 migration guide

<View title="Developer" />

<View title="Federal docs" />

<View title="EU docs" />

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

**Version 4.0 contains breaking changes**. It introduces the ability to have LaunchDarkly automatically provide data about the mobile 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, and so on.

When you configure the SDK, starting in version 4.0 you must indicate whether LaunchDarkly should or should not include this data. As part of this change, the `Init` and `InitAsync` methods now include an additional required parameter. To learn more, read [Understanding changes to configuration options](#understanding-changes-to-configuration-options), below.

This data is provided in two new context kinds. The data is added automatically to each evaluation context you provide.

Customers who are billed by MAU may be charged based on the `ld_device` context kind if it becomes the context kind with the highest volume of monthly activity in their account. This feature does not affect customers on other billing models. To learn more, read [Account usage metrics](/docs/home/account/metrics).

Version 4.0 of the SDK also introduces the ability to configure the SDK to send application metadata to LaunchDarkly.

Before you migrate to version 4.0, we recommend updating to the latest 3.x version. If you update to the latest 3.x version, deprecation warnings appear in areas of your code that need to be changed for 4.0. You can update these areas at your own pace while still using 3.x, rather than migrating everything simultaneously. To learn more about updating to the latest 3.x version, visit the [SDK's GitHub repository](https://github.com/launchdarkly/dotnet-client-sdk).

## Understanding changes to configuration options

Version 4.0 introduces a new, required configuration parameter. Use this to indicate whether LaunchDarkly should automatically provide data about the mobile environment where the application is running as part of each evaluation context. You must include this parameter when building your `Configuration`.

Here's how:

<CodeGroup>
  ```csharp title=".NET SDK v4.0 (C#)" lines wrap theme={null}
  var config = Configuration
    .Builder("example-mobile-key", ConfigurationBuilder.AutoEnvAttributes.Enabled)
    .Build();
  ```

  ```csharp title=".NET SDK v3.x (C#)" lines wrap theme={null}
  var config = Configuration
    .Builder("example-mobile-key")
    .Build();
  ```
</CodeGroup>

You must also include this new parameter when calling `Init` or `InitAsync`.

For example:

<CodeGroup>
  ```csharp title=".NET SDK v4.0 (C#), using Init" lines wrap theme={null}
  var context = Context.New("example-context-key");
  var timeSpan = TimeSpan.FromSeconds(10);

  client = LdClient.Init("example-mobile-key", ConfigurationBuilder.AutoEnvAttributes.Enabled, context, timeSpan);
  ```

  ```csharp title=".NET SDK v3.x (C#), using Init" lines wrap theme={null}
  var context = Context.New("example-context-key");
  var timeSpan = TimeSpan.FromSeconds(10);
  client = LdClient.Init("example-mobile-key", context, timeSpan);
  ```

  ```csharp title=".NET SDK v4.0 (C#), using InitAsync" lines wrap theme={null}
  var context = Context.New("example-context-key");
  client = await LdClient.InitAsync("example-mobile-key", ConfigurationBuilder.AutoEnvAttributes.Enabled, context);
  ```

  ```csharp title=".NET SDK v3.x (C#), using InitAsync" lines wrap theme={null}
  var context = Context.New("example-context-key");
  client = await LdClient.InitAsync("example-mobile-key", context);
  ```
</CodeGroup>

To disable this option, pass in `AutoEnvAttributes.Disabled` instead.

To learn more, read [`Configuration`](https://launchdarkly.github.io/dotnet-core/pkgs/sdk/client/api/LaunchDarkly.Sdk.Client.Configuration.html).

## Understanding the automatically added environment attributes

If you use `AutoEnvAttributes.Enabled` in the SDK client configuration, the SDK automatically adds two additional contexts to each context that you evaluate. You can use attributes from these contexts in your targeting rules.

<Tip>
  **Working with multi-contexts**

  Because the SDK automatically adds contexts, every evaluation context is now a set of multiple contexts, which is called a multi-context. This means to you can create targeting rules in your feature flags based on data from multiple contexts at once. To learn more, read [Multi-contexts](/docs/home/flags/multi-contexts).
</Tip>

These automatically added contexts include the following attributes:

<table>
  <thead>
    <tr>
      <th>Context kind</th>
      <th>Context attribute</th>
      <th>Description</th>
      <th>Example</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>ld\_application</code></td>
      <td><code>key</code></td>
      <td>Unique for this context kind. Automatically generated by the SDK.</td>
      <td>*randomly generated*</td>
    </tr>

    <tr>
      <td />

      <td><code>id</code></td>
      <td>Unique identifier of the application.</td>
      <td><code>com.launchdarkly.example</code></td>
    </tr>

    <tr>
      <td />

      <td><code>locale</code></td>
      <td>Locale of the device, in [IETF BCP 47 Language Tag](https://www.ietf.org/rfc/bcp/bcp47.txt) format.</td>
      <td><code>en-US</code></td>
    </tr>

    <tr>
      <td />

      <td><code>name</code></td>
      <td>Human-friendly name of the application.</td>
      <td><code>Example Mobile App</code></td>
    </tr>

    <tr>
      <td />

      <td><code>version</code></td>
      <td>Version of the application used for update comparison.</td>
      <td><code>5</code></td>
    </tr>

    <tr>
      <td />

      <td><code>versionName</code></td>
      <td>Human-friendly name of the version. May or may not be a semantic version.</td>
      <td><code>5</code></td>
    </tr>

    <tr>
      <td />

      <td><code>envAttributesVersion</code></td>
      <td>Version of the environment attributes schema being used. This may change in later versions of the SDK.</td>
      <td><code>1.0</code></td>
    </tr>

    <tr>
      <td><code>ld\_device</code></td>
      <td><code>key</code></td>
      <td>Unique for this context kind. Automatically generated by the SDK.</td>
      <td>*randomly generated*</td>
    </tr>

    <tr>
      <td />

      <td><code>manufacturer</code></td>
      <td>Manufacturer of the device.</td>
      <td><code>Google</code></td>
    </tr>

    <tr>
      <td />

      <td><code>model</code></td>
      <td>Model of the device.</td>
      <td><code>Pixel 6 Pro</code></td>
    </tr>

    <tr>
      <td />

      <td><code>os</code></td>
      <td>Operating system of the device. Includes properties for <code>family</code>, <code>name</code>, and <code>version</code>.</td>
      <td><ul><li><code>family</code>: <code>Android</code></li><li><code>version</code>: <code>13</code></li><li><code>name</code>: <code>Android33</code></li></ul></td>
    </tr>

    <tr>
      <td />

      <td><code>envAttributesVersion</code></td>
      <td>Version of the environment attributes schema being used. This may change in later versions of the SDK.</td>
      <td><code>1.0</code></td>
    </tr>
  </tbody>
</table>

If the SDK cannot determine the information for a particular attribute, it will not include that attribute. For example, if the SDK cannot determine the device's model, it will not include the `model` attribute.

If the SDK can determine none of the information for an entire context, it will not include that context. For example, if you run the .NET (client-side) SDK on a desktop environment, the SDK cannot reliably get the device information. In this case the `ld_device` context is omitted.

### Automatic environment attributes and application metadata configuration

If you are already setting [application metadata](/docs/sdk/features/app-config) as part of your SDK configuration, you can still use this new [environment attributes](/docs/sdk/features/environment-attributes) feature. Any application metadata that you set will override the automatically collected environment attributes.

Specifically, the `ld_application` context attributes are set based on the following priority order:

1. If you set values for application id, name, version, or version name using [application metadata configuration](/docs/sdk/features/app-config) in the SDK, then the `ld_application` context will reflect those values.
2. Otherwise, if you have set values for the application id, name, version, or version name within your mobile app, the `ld_application` context will reflect those values.
3. Otherwise, the `ld_application` context will use the LaunchDarkly SDK name and version.