Skip to content

Mention TargetingContext and fix wording in Variants section of readme #330

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 16 commits into from
Jan 5, 2024
Merged

Mention TargetingContext and fix wording in Variants section of readme #330

Changes from all commits
Commits
Show all changes
16 commits
Select commit Hold shift + click to select a range
8e914b9
mention itargetingcontextaccessor for variant allocation
amerjusupovic Dec 8, 2023
b3f1874
update changes
amerjusupovic Dec 12, 2023
d429d77
add reference to ITargetingContextAccessor to readme for allocation
amerjusupovic Dec 12, 2023
040277a
Merge branch 'preview' of https://github.com/microsoft/FeatureManagem…
amerjusupovic Dec 12, 2023
3735366
update with new discussed changes, rename sections and introduce cont…
amerjusupovic Dec 15, 2023
26db004
fix wording of default
amerjusupovic Dec 15, 2023
52d7e2b
fix wording to avoid implying variants are assigned per feature
amerjusupovic Dec 15, 2023
3d9e71a
use the term assign when referring to variants returned for a user
amerjusupovic Dec 18, 2023
c226638
use assign term in more places
amerjusupovic Dec 18, 2023
df3eb50
small changes
amerjusupovic Dec 18, 2023
ed32a95
Update README.md
amerjusupovic Dec 27, 2023
90aedf3
update section titles
amerjusupovic Dec 27, 2023
77a93f1
Merge branch 'ajusupovic/update-readme-variants' of https://github.co…
amerjusupovic Dec 27, 2023
15ad38d
resolve comments
amerjusupovic Dec 27, 2023
6097fc5
fix typo
amerjusupovic Dec 27, 2023
95c2f4f
update link to allocating variants section
amerjusupovic Jan 5, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
81 changes: 54 additions & 27 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -635,7 +635,7 @@ The targeting context accessor and `TargetingFilter` are registered by calling `

#### ITargetingContextAccessor

To use the `TargetingFilter` in a web application, an implementation of `ITargetingContextAccessor` is required. This is because when a targeting evaluation is being performed information such as what user is currently being evaluated is needed. This information is known as the targeting context. Different web applications may extract this information from different places. Some common examples of where an application may pull the targeting context are the request's HTTP context or a database.
To use the `TargetingFilter` in a web application, an implementation of `ITargetingContextAccessor` is required. This is because when a targeting evaluation is being performed, information such as what user is currently being evaluated is needed. This information is known as the targeting context. Different web applications may extract this information from different places. Some common examples of where an application may pull the targeting context are the request's HTTP context or a database.

An example that extracts targeting context information from the application's HTTP context is included in the [FeatureFlagDemo](./examples/FeatureFlagDemo/HttpContextTargetingContextAccessor.cs) example project. This method relies on the use of `IHttpContextAccessor` which is discussed [here](./README.md#Using-HttpContext).

Expand Down Expand Up @@ -703,7 +703,7 @@ In the above example, the feature will be enabled for users named `Jeff` and `Al

When new features are added to an application, there may come a time when a feature has multiple different proposed design options. A common solution for deciding on a design is some form of A/B testing, which involves providing a different version of the feature to different segments of the user base and choosing a version based on user interaction. In this library, this functionality is enabled by representing different configurations of a feature with variants.

Variants enable a feature flag to become more than a simple on/off flag. A variant represents a value of a feature flag that can be a string, a number, a boolean, or even a configuration object. A feature flag that declares variants should define under what circumstances each variant should be used, which is covered in greater detail in the [Allocating a Variant](./README.md#allocating-a-variant) section.
Variants enable a feature flag to become more than a simple on/off flag. A variant represents a value of a feature flag that can be a string, a number, a boolean, or even a configuration object. A feature flag that declares variants should define under what circumstances each variant should be used, which is covered in greater detail in the [Allocating Variants](./README.md#allocating-variants) section.

``` C#
public class Variant
Expand All @@ -720,43 +720,70 @@ public class Variant
}
```

### Getting a Feature's Variant
### Getting Variants
Copy link
Member

@jimmyca15 jimmyca15 Dec 18, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it would be better if the code snippet came directly after this part "For each feature, a variant can be retrieved using the IVariantFeatureManager's GetVariantAsync method."

then after the code snippet the extra information was provided.

Copy link
Member

@jimmyca15 jimmyca15 Dec 18, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I was thinking in our doc it might be helpful to mention that .NET makes it easy to bind IconfigurationSection to a type. After all, this is how I expect most people to consume a features variants. After seeing this, I think a second code snippet could be provided. something like below

Once a variant is retrieved, the configuration of a variant can be used directly as an IConfigurationSection from the variants Configuration property. Another option is to bind the configuration to a type using .NET's configuration binding pattern.

IConfigurationSection variantConfiguration = variant.Configuration;

MyFeatureSettings settings = variant
    .Configuration
    .Bind<MyFeatureSettings>();

Copy link
Member

@zhiyuanliang-ms zhiyuanliang-ms Dec 28, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more. 

MyFeatureSettings settings = variantConfiguration.Get<MyFeatureSettings>() ?? new MyFeatureSettings();

Or

MyFeatureSettings settings = new MyFeatureSettings();
variantConfiguration.Bind(settings);


A feature's variant can be retrieved using the `IVariantFeatureManager`'s `GetVariantAsync` method.
For each feature, a variant can be retrieved using the `IVariantFeatureManager`'s `GetVariantAsync` method.

``` C#
…
IVariantFeatureManager featureManager;
…
Variant variant = await featureManager.GetVariantAsync(MyFeatureFlags.FeatureU);
Variant variant = await featureManager.GetVariantAsync(MyFeatureFlags.FeatureU, CancellationToken.None);

IConfigurationSection variantConfiguration = variant.Configuration;

// Do something with the resulting variant and its configuration
```

### Setting a Variant's Configuration
Once a variant is retrieved, the configuration of a variant can be used directly as an `IConfigurationSection` from the variant's `Configuration` property. Another option is to bind the configuration to an object using .NET's configuration binding pattern.

For each of the variants in the `Variants` property of a feature, there is a specified configuration. This can be set using either the `ConfigurationReference` or `ConfigurationValue` properties. `ConfigurationReference` is a string path that references a section of the current configuration that contains the feature flag declaration. `ConfigurationValue` is an inline configuration that can be a string, number, boolean, or configuration object. If both are specified, `ConfigurationValue` is used. If neither are specified, the returned variant's `Configuration` property will be null.
``` C#
IConfigurationSection variantConfiguration = variant.Configuration;

MyFeatureSettings settings = new MyFeatureSettings();

variantConfiguration.Bind(settings);
```
"Variants": [
{
"Name": "Big",
"ConfigurationReference": "ShoppingCart:Big"
},
{
"Name": "Small",
"ConfigurationValue": {
"Size": 300

The variant returned is dependent on the user currently being evaluated, and that information is obtained from an instance of `TargetingContext`. This context can either be passed in when calling `GetVariantAsync` or it can be automatically retrieved from an implementation of [`ITargetingContextAccessor`](#itargetingcontextaccessor) if one is registered.

### Defining Variants

Each variant has two properties: a name and a configuration. The name is used to refer to a specific variant, and the configuration is the value of that variant. The configuration can be set using either the `ConfigurationReference` or `ConfigurationValue` properties. `ConfigurationReference` is a string path that references a section of the current configuration that contains the feature flag declaration. `ConfigurationValue` is an inline configuration that can be a string, number, boolean, or configuration object. If both are specified, `ConfigurationValue` is used. If neither are specified, the returned variant's `Configuration` property will be null.

A list of all possible variants is defined for each feature under the `Variants` property.

```
{
"FeatureManagement":
{
"MyFlag":
{
"Variants": [
{
"Name": "Big",
"ConfigurationReference": "ShoppingCart:Big"
},
{
"Name": "Small",
"ConfigurationValue": {
"Size": 300
}
}
],
"EnabledFor": [
{
"Name": "AlwaysOn"
}
]
}
}
]
}
}
```

### Allocating a Variant
### Allocating Variants

The process of allocating a variant to a specific feature is determined by the `Allocation` property of the feature.
The process of allocating a feature's variants is determined by the `Allocation` property of the feature.

```
"Allocation": {
Expand Down Expand Up @@ -804,21 +831,21 @@ The `Allocation` setting of a feature flag has the following properties:
| Property | Description |
| ---------------- | ---------------- |
| `DefaultWhenDisabled` | Specifies which variant should be used when a variant is requested while the feature is considered disabled. |
| `DefaultWhenEnabled` | Specifies which variant should be used when a variant is requested while the feature is considered enabled and no variant was allocated to the user. |
| `User` | Specifies a variant and a list of users for which that variant should be used. |
| `Group` | Specifies a variant and a list of groups the current user has to be in for that variant to be used. |
| `Percentile` | Specifies a variant and a percentage range the user's calculated percentage has to fit into for that variant to be used. |
| `DefaultWhenEnabled` | Specifies which variant should be used when a variant is requested while the feature is considered enabled and no other variant was assigned to the user. |
| `User` | Specifies a variant and a list of users to whom that variant should be assigned. |
| `Group` | Specifies a variant and a list of groups the current user has to be in for that variant to be assigned. |
| `Percentile` | Specifies a variant and a percentage range the user's calculated percentage has to fit into for that variant to be assigned. |
| `Seed` | The value which percentage calculations for `Percentile` are based on. The percentage calculation for a specific user will be the same across all features if the same `Seed` value is used. If no `Seed` is specified, then a default seed is created based on the feature name. |

In the above example, if the feature is not enabled, `GetVariantAsync` would return the variant allocated by `DefaultWhenDisabled`, which is `Small` in this case.
In the above example, if the feature is not enabled, the feature manager will assign the variant marked as `DefaultWhenDisabled` to the current user, which is `Small` in this case.

If the feature is enabled, the feature manager will check the `User`, `Group`, and `Percentile` allocations in that order to allocate a variant for this feature. If the user being evaluated is named `Marsha`, in the group named `Ring1`, or the user happens to fall between the 0 and 10th percentile calculated with the given `Seed`, then the specified variant is returned for that allocation. In this case, all of these would return the `Big` variant. If none of these allocations match, the `DefaultWhenEnabled` variant is returned, which is `Small`.
If the feature is enabled, the feature manager will check the `User`, `Group`, and `Percentile` allocations in that order to assign a variant. For this particular example, if the user being evaluated is named `Marsha`, in the group named `Ring1`, or the user happens to fall between the 0 and 10th percentile, then the specified variant is assigned to the user. In this case, all of these would return the `Big` variant. If none of these allocations match, the user is assigned the `DefaultWhenEnabled` variant, which is `Small`.

Allocation logic is similar to the [Microsoft.Targeting](./README.md#MicrosoftTargeting) feature filter, but there are some parameters that are present in targeting that aren't in allocation, and vice versa. The outcomes of targeting and allocation are not related.

### Overriding Enabled State with a Variant

You can use variants to override the enabled state of a feature flag. This gives variants an opportunity to extend the evaluation of a feature flag. If a caller is checking whether a flag that has variants is enabled, then variant allocation will be performed to see if an allocated variant is set up to override the result. This is done using the optional variant property `StatusOverride`. By default, this property is set to `None`, which means the variant doesn't affect whether the flag is considered enabled or disabled. Setting `StatusOverride` to `Enabled` allows the variant, when chosen, to override a flag to be enabled. Setting `StatusOverride` to `Disabled` provides the opposite functionality, therefore disabling the flag when the variant is chosen. A feature with a `Status` of `Disabled` cannot be overridden.
You can use variants to override the enabled state of a feature flag. This gives variants an opportunity to extend the evaluation of a feature flag. If a caller is checking whether a flag that has variants is enabled, the feature manager will check if the variant assigned to the current user is set up to override the result. This is done using the optional variant property `StatusOverride`. By default, this property is set to `None`, which means the variant doesn't affect whether the flag is considered enabled or disabled. Setting `StatusOverride` to `Enabled` allows the variant, when chosen, to override a flag to be enabled. Setting `StatusOverride` to `Disabled` provides the opposite functionality, therefore disabling the flag when the variant is chosen. A feature with a `Status` of `Disabled` cannot be overridden.

If you are using a feature flag with binary variants, the `StatusOverride` property can be very helpful. It allows you to continue using APIs like `IsEnabledAsync` and `FeatureGateAttribute` in your application, all while benefiting from the new features that come with variants, such as percentile allocation and seed.

Expand Down