Partager via

Gestion des fonctionnalités .NET

Microsoft.FeatureManagement
Microsoft.FeatureManagement.AspNetCore
Microsoft.FeatureManagement.Telemetry.ApplicationInsights

La bibliothèque de gestion des fonctionnalités .NET permet de développer et d’exposer les fonctionnalités d’application en fonction des indicateurs de fonctionnalité. Lorsqu’une nouvelle fonctionnalité est développée, de nombreuses applications ont des exigences particulières, par exemple quand la fonctionnalité doit être activée et dans quelles conditions. Cette bibliothèque permet de définir ces relations. Il s’intègre également aux modèles de code .NET courants pour rendre ces fonctionnalités possibles.

Les indicateurs de fonctionnalité permettent aux applications .NET et ASP.NET Core d’activer ou de désactiver dynamiquement les fonctionnalités. Vous pouvez utiliser des indicateurs de fonctionnalité dans des cas d’usage de base tels que des instructions conditionnelles. Vous pouvez également utiliser des indicateurs de fonctionnalité dans des scénarios plus avancés, tels que l’ajout conditionnel d’itinéraires ou de filtres MVC (model-view-controller). Les indicateurs de fonctionnalité sont basés sur le système de configuration .NET Core. N’importe quel fournisseur de configuration .NET Core est capable d’agir en tant qu’infrastructure principale pour les indicateurs de fonctionnalité.

Voici quelques-uns des avantages de l’utilisation de la bibliothèque de gestion des fonctionnalités .NET :

  • Il utilise des conventions courantes pour la gestion des fonctionnalités.
  • Il a une barrière faible à l’entrée :
    • Elle est basée sur l’interface IConfiguration .
    • Prend en charge la configuration de l’indicateur de fonctionnalité de fichier JSON.
  • Offre une gestion de la durée de vie des indicateurs de fonctionnalité.
    • Les valeurs de configuration peuvent changer en temps réel.
    • Les indicateurs de fonctionnalité peuvent être cohérents dans l’ensemble de la requête.
  • Il couvre les scénarios de base et complexes en offrant une prise en charge des fonctionnalités suivantes :
    • Activation et désactivation des fonctionnalités via un fichier de configuration déclaratif
    • Présentation de différentes variantes d’une fonctionnalité à différents utilisateurs
    • Évaluation dynamique de l’état d’une fonctionnalité en fonction d’un appel à un serveur
  • Il fournit des extensions d’API pour l’infrastructure ASP.NET Core et MVC dans les domaines suivants :
    • Routage
    • Filtres
    • Attributs d’action

La bibliothèque de gestion des fonctionnalités .NET est open source. Pour plus d’informations, consultez le dépôt GitHub FeatureManagement-Dotnet .

Indicateurs de fonctionnalités

Les indicateurs de fonctionnalité peuvent être activés ou désactivés. L’état d’un indicateur peut être rendu conditionnel à l’aide de filtres de fonctionnalités.

Filtres de fonctionnalités

Les filtres de fonctionnalités définissent un scénario pour lequel une fonctionnalité doit être activée. Pour évaluer l’état d’une fonctionnalité, sa liste de filtres de fonctionnalités est parcourue jusqu’à ce que l’un des filtres détermine que la fonctionnalité est activée. À ce stade, la recherche dans les filtres de fonctionnalités s’interrompt. Si aucun filtre de fonctionnalités n’indique que la fonctionnalité doit être activée, elle est considérée comme désactivée.

Par exemple, supposons que vous conceviez un filtre de fonctionnalités de navigateur Microsoft Edge. Si une requête HTTP provient de Microsoft Edge, votre filtre de fonctionnalités active toutes les fonctionnalités auxquelles elle est attachée.

Configuration de l’indicateur de fonctionnalité

Le système de configuration .NET Core est utilisé pour déterminer l’état des indicateurs de fonctionnalité. La base de ce système est l’interface IConfiguration . N’importe quel fournisseur pour IConfiguration peut être utilisé comme fournisseur d’état de la fonctionnalité pour la bibliothèque d’indicateurs de fonctionnalité. Ce système prend en charge les scénarios allant du fichier de configurationappsettings.json à Azure App Configuration.

Déclaration d’indicateur de fonctionnalité

La bibliothèque de gestion des fonctionnalités prend en charge le fichier de configuration appsettings.json en tant que source d’indicateur de fonctionnalité, car il s’agit d’un fournisseur pour le système .NET Core IConfiguration . Les indicateurs de fonctionnalité sont déclarés à l’aide du Microsoft Feature Management schema. Ce schéma est indépendant du langage d’origine et est pris en charge dans toutes les bibliothèques de gestion des fonctionnalités Microsoft.

Le code de l’exemple suivant déclare des indicateurs de fonctionnalité dans un fichier JSON :

{
    "Logging": {
        "LogLevel": {
            "Default": "Warning"
        }
    },

    // Define feature flags in a JSON file.
    "feature_management": {
        "feature_flags": [
            {
                "id": "FeatureT",
                "enabled": false
            },
            {
                "id": "FeatureU",
                "enabled": true,
                "conditions": {}
            },
            {
                "id": "FeatureV",
                "enabled": true,
                "conditions": {
                    "client_filters": [
                        {  
                            "name": "Microsoft.TimeWindow",
                            "parameters": {
                                "Start": "Sun, 01 Jun 2025 13:59:59 GMT",
                                "End": "Fri, 01 Aug 2025 00:00:00 GMT"
                            }
                        }
                    ]
                }
            }
        ]
    }
}

La feature_management section du document JSON est utilisée par convention pour charger les paramètres d’indicateur de fonctionnalité. Vous devez répertorier les objets d’indicateur de fonctionnalité dans le feature_flags tableau de cette section. Ce code répertorie trois indicateurs de fonctionnalité. Chaque objet d’indicateur de fonctionnalité a une id propriété et une enabled propriété.

  • La id valeur est le nom que vous utilisez pour identifier et référencer l’indicateur de fonctionnalité.
  • La propriété enabled spécifie l’état activé de l’indicateur de fonctionnalité.

Une fonctionnalité est désactivée si enabled c’est false. Si enabled est true, l’état de la fonctionnalité dépend de la propriété conditions. La conditions propriété déclare les conditions utilisées pour activer dynamiquement la fonctionnalité.

  • Si un indicateur de fonctionnalité n’a pas de conditions propriété, la fonctionnalité est activée.
  • Si un indicateur de fonctionnalité a une conditions propriété et que ses conditions sont remplies, la fonctionnalité est activée.
  • Si un indicateur de fonctionnalité a une conditions propriété et que ses conditions ne sont pas remplies, la fonctionnalité est désactivée.

Les filtres de fonctionnalités sont définis dans le client_filters tableau. Dans le code précédent, l’indicateur FeatureV de fonctionnalité a un filtre de fonctionnalité nommé Microsoft.TimeWindow. Ce filtre est un exemple de filtre de fonctionnalités configurable. Dans ce code, ce filtre a une parameters propriété. Cette propriété est utilisée pour configurer le filtre. Dans ce cas, les heures de début et de fin d’activation de la fonctionnalité sont configurées.

Avancé: Le caractère deux-points (:) est interdit dans les noms d’indicateurs de fonctionnalité.

Type d’exigence

Dans la propriété conditions, la propriété requirement_type est utilisée pour déterminer si les filtres doivent utiliser la logique Any ou All lors de l’évaluation de l’état d’une fonctionnalité. Si requirement_type n’est pas spécifié, la valeur par défaut est Any. Les requirement_type valeurs entraînent le comportement suivant :

  • Any : un seul filtre doit être évalué sur true pour que la fonctionnalité soit activée.
  • All : tous les filtres doivent être évalués sur true pour que la fonctionnalité soit activée.

Un requirement_type de All modifie la manière dont les filtres sont parcourus.

  • Si aucun filtre n’est répertorié, la fonctionnalité est désactivée.
  • Si les filtres sont répertoriés, ils sont parcourus jusqu’à ce que les conditions d’un spécifient que la fonctionnalité doit être désactivée. Si aucun filtre n’indique que la fonctionnalité doit être désactivée, elle est considérée comme activée.
{
    "id": "FeatureW",
    "enabled": true,
    "conditions": {
        "requirement_type": "All",
        "client_filters": [
            {
                "name": "Microsoft.TimeWindow",
                "parameters": {
                    "Start": "Sun, 01 Jun 2025 13:59:59 GMT",
                    "End": "Fri, 01 Aug 00:00:00 GMT"
                }
            },
            {
                "name": "Microsoft.Percentage",
                "parameters": {
                    "Value": "50"
                }
            }
        ]
    }
}

Dans cet exemple, l’indicateur de fonctionnalité FeatureW a une valeur requirement_type de All. Par conséquent, tous ses filtres doivent être évalués à true pour que la fonctionnalité soit activée. Dans ce cas, la fonctionnalité est activée pour 50 % des utilisateurs pendant la fenêtre de temps spécifiée.

Gestion de plusieurs sources de configuration

À compter de la version 4.3.0, vous pouvez opter pour la fusion personnalisée pour les indicateurs de fonctionnalités de schéma Microsoft (la section feature_management). Lorsque le même ID d’indicateur de fonctionnalité apparaît dans plusieurs sources de configuration, une instance de la classe intégrée ConfigurationFeatureDefinitionProvider fusionne ces définitions en fonction de l’ordre d’inscription du fournisseur de configuration. En cas de conflit, la dernière définition de l’indicateur de fonctionnalité est utilisée. Ce comportement diffère de la fusion basée sur l’index de tableau par défaut dans .NET.

Le code suivant active la fusion de configuration d’indicateurs de fonctionnalité personnalisée via l’injection de dépendances :

IConfiguration configuration = new ConfigurationBuilder()
    .AddJsonFile("appsettings.json")
    .AddJsonFile("appsettings.prod.json")
    .Build();

services.AddSingleton(configuration);
services.AddFeatureManagement();
services.Configure<ConfigurationFeatureDefinitionProviderOptions>(o =>
{
        o.CustomConfigurationMergingEnabled = true;
});

Vous pouvez également activer la fusion personnalisée lorsque vous construisez une instance de ConfigurationFeatureDefinitionProvider:

var featureManager = new FeatureManager(
    new ConfigurationFeatureDefinitionProvider(
            configuration,
            new ConfigurationFeatureDefinitionProviderOptions
            {
                    CustomConfigurationMergingEnabled = true
            }));

Exemple de comportement :

// appsettings.json
{
    "feature_management": {
        "feature_flags": [
            { "id": "FeatureA", "enabled": true },
            { "id": "FeatureB", "enabled": false }
        ]
    }
}

// appsettings.prod.json (added later in ConfigurationBuilder)
{
    "feature_management": {
        "feature_flags": [
            { "id": "FeatureB", "enabled": true }
        ]
    }
}

Lorsque vous activez la fusion personnalisée, FeatureA reste activé et FeatureB est résolu en activé, car la dernière déclaration est utilisée. Lorsque vous utilisez la fusion .NET par défaut, où la fusion personnalisée est désactivée, les tableaux sont fusionnés par index. Cette approche peut produire des résultats inattendus si les sources ne s’alignent pas par position.

Schéma de gestion des fonctionnalités .NET

Dans les versions précédentes de la bibliothèque de gestion des fonctionnalités, le schéma principal était le schéma de gestion des fonctionnalités .NET.

À compter de la version 4.0.0 de la bibliothèque, les nouvelles fonctionnalités, notamment les variantes et les données de télémétrie, ne sont pas prises en charge dans le schéma de gestion des fonctionnalités .NET.

Remarque

Si la configuration de l’indicateur de fonctionnalité inclut une déclaration répertoriée à la fois dans les sections feature_management et FeatureManagement, celle de la section feature_management est adoptée.

Consommation

Dans une implémentation de base, la gestion des fonctionnalités vérifie si un indicateur de fonctionnalité est activé. Ensuite, il effectue des actions en fonction du résultat. Cette vérification est effectuée via la IsEnabledAsync méthode de IVariantFeatureManager.

…
IVariantFeatureManager featureManager;
…
if (await featureManager.IsEnabledAsync("FeatureX"))
{
    // Do something.
}

Inscription du service

Le gestionnaire de fonctionnalités s’appuie sur l’injection de dépendances .NET Core. Comme le montre le code suivant, vous pouvez utiliser des conventions standard pour inscrire des services de gestion des fonctionnalités :

using Microsoft.FeatureManagement;

public class Startup
{
    public void ConfigureServices(IServiceCollection services)
    {
        services.AddFeatureManagement();
    }
}

Par défaut, le gestionnaire de fonctionnalités récupère la configuration de l’indicateur de fonctionnalité à partir de la section feature_management ou FeatureManagement des données de configuration .NET Core. Si aucune des sections n’existe, la configuration est considérée comme vide.

Remarque

Vous pouvez également spécifier que la configuration de l’indicateur de fonctionnalité doit être récupérée à partir d’une autre section de configuration en passant la section à AddFeatureManagement. L’exemple suivant spécifie que le gestionnaire de fonctionnalités doit lire à partir d’une section appelée MyFeatureFlags à la place :

services.AddFeatureManagement(configuration.GetSection("MyFeatureFlags"));

Injection de dépendances

Lorsque vous utilisez la bibliothèque de gestion des fonctionnalités avec MVC, vous pouvez obtenir l'objet qui implémente IVariantFeatureManager, à l'aide de l'injection de dépendances.

public class HomeController : Controller
{
    private readonly IVariantFeatureManager _featureManager;
    
    public HomeController(IVariantFeatureManager featureManager)
    {
        _featureManager = featureManager;
    }
}

Services de gestion des fonctionnalités à portée définie

La AddFeatureManagement méthode ajoute des services de gestion des fonctionnalités en tant que singletons au sein d’une application. Certains scénarios nécessitent l’ajout de services de gestion des fonctionnalités en tant que services délimités à la place. Par exemple, vous pouvez utiliser des filtres de fonctionnalités qui consomment des services délimités pour obtenir des informations contextuelles. Dans ce cas, vous devez utiliser la AddScopedFeatureManagement méthode. Cette méthode garantit que les services de gestion des fonctionnalités, y compris les filtres de fonctionnalités, sont ajoutés en tant que services délimités.

services.AddScopedFeatureManagement();

Intégration ASP.NET Core

La bibliothèque de gestion des fonctionnalités fournit des fonctionnalités dans ASP.NET Core et MVC pour activer des scénarios d’indicateurs de fonctionnalité courants dans les applications web. Ces fonctionnalités sont disponibles en référençant le package NuGet Microsoft.FeatureManagement.AspNetCore.

Contrôleurs et actions

Un contrôleur et des actions MVC peuvent exiger qu’une fonctionnalité donnée, ou l’une des listes de fonctionnalités, soit activée pour s’exécuter. Vous pouvez répondre à cette exigence à l’aide d’un FeatureGateAttribute objet. La classe FeatureGateAttribute est définie dans l’espace de noms Microsoft.FeatureManagement.Mvc.

[FeatureGate("FeatureX")]
public class HomeController : Controller
{
    …
}

Dans l’exemple précédent, la HomeController classe est contrôlée par FeatureX. Les actions HomeController peuvent s’exécuter uniquement si la FeatureX fonctionnalité est activée.

[FeatureGate("FeatureX")]
public IActionResult Index()
{
    return View();
}

Dans l’exemple précédent, l’action Index MVC ne peut s’exécuter que si la FeatureX fonctionnalité est activée.

Gestion des actions désactivées

Lorsqu’un contrôleur ou une action MVC est bloqué, car aucune des fonctionnalités spécifiées n’est activée, une implémentation enregistrée est appelée IDisabledFeaturesHandler. Par défaut, un gestionnaire minimaliste est inscrit qui retourne une erreur HTTP 404. Vous pouvez remplacer ce gestionnaire à l’aide IFeatureManagementBuilder de l’inscription d’indicateurs de fonctionnalité.

public interface IDisabledFeaturesHandler
{
    Task HandleDisabledFeatures(IEnumerable<string> features, ActionExecutingContext context);
}

Affichage

Dans les vues MVC, vous pouvez utiliser <feature> des balises pour afficher le contenu de manière conditionnelle. Vous pouvez baser les conditions de rendu si une fonctionnalité est activée ou si une variante spécifique d’une fonctionnalité est affectée. Pour plus d’informations, consultez Variantes, plus loin dans cet article.

<feature name="FeatureX">
  <p>This content appears only when 'FeatureX' is enabled.</p>
</feature>

<feature name="FeatureX" variant="Alpha">
  <p>This content appears only when variant 'Alpha' of 'FeatureX' is assigned.</p>
</feature>

Vous pouvez également nier l’évaluation de l’assistant de balisage si vous souhaitez afficher du contenu lorsqu’une fonctionnalité ou un ensemble de fonctionnalités sont désactivées. Si vous spécifiez negate="true", comme dans les exemples suivants, le contenu est affiché uniquement lorsqu’il FeatureX est désactivé.

<feature negate="true" name="FeatureX">
  <p>This content appears only when 'FeatureX' is disabled.</p>
</feature>

<feature negate="true" name="FeatureX" variant="Alpha">
  <p>This content appears only when variant 'Alpha' of 'FeatureX' isn't assigned.</p>
</feature>

Vous pouvez utiliser la <feature> balise pour référencer plusieurs fonctionnalités. Pour ce faire, spécifiez une liste séparée par des virgules des fonctionnalités dans l’attribut name .

<feature name="FeatureX,FeatureY">
  <p>This content appears only when 'FeatureX' and 'FeatureY' are enabled.</p>
</feature>

Par défaut, toutes les fonctionnalités répertoriées doivent être activées pour que la balise de fonctionnalité soit rendue. Vous pouvez remplacer ce comportement en ajoutant l’attribut requirement , comme l’illustre l’exemple suivant.

<feature name="FeatureX,FeatureY" requirement="Any">
  <p>This content appears only when 'FeatureX,' 'FeatureY,' or both are enabled.</p>
</feature>

Vous pouvez également utiliser la <feature> balise pour référencer plusieurs variantes. Pour ce faire, utilisez une requirement valeur de Any et spécifiez une liste de variantes séparées par des virgules dans l’attribut variant .

<feature name="FeatureX" variant="Alpha,Beta" requirement="Any">
  <p>This content appears only when variant 'Alpha' or 'Beta' of 'FeatureX' is assigned.</p>
</feature>

Remarque

  • Si vous spécifiez une variante, vous ne devez spécifier qu’une seule fonctionnalité.
  • Si vous spécifiez plusieurs variantes et utilisez une valeur de requirementAnd, une erreur est générée. Vous ne pouvez pas affecter plusieurs variantes.

La balise <feature> nécessite un tag helper pour fonctionner. Pour utiliser la balise, ajoutez l’assistant de balise de gestion des fonctionnalités au fichier _ViewImports.cshtml.

@addTagHelper *, Microsoft.FeatureManagement.AspNetCore

Filtres MVC

Vous pouvez configurer des filtres d’action MVC que vous appliquez de manière conditionnelle en fonction de l’état d’une fonctionnalité. Pour configurer ces filtres, vous les inscrivez en tenant compte des fonctionnalités. Le pipeline de gestion des fonctionnalités prend en charge les filtres d’action MVC asynchrones qui implémentent l’interface IAsyncActionFilter .

services.AddMvc(o => 
{
    o.Filters.AddForFeature<SomeMvcFilter>("FeatureX");
});

Le code précédent inscrit un filtre MVC nommé SomeMvcFilter. Ce filtre est déclenché uniquement dans le pipeline MVC s’il FeatureX est activé.

Pages Razor

Les pages Razor MVC peuvent exiger qu’une fonctionnalité donnée, ou l’une des listes de fonctionnalités, soit activée pour s’exécuter. Vous pouvez ajouter cette exigence à l’aide d’un FeatureGateAttribute objet. La classe FeatureGateAttribute est définie dans l’espace de noms Microsoft.FeatureManagement.Mvc.

[FeatureGate("FeatureX")]
public class IndexModel : PageModel
{
    public void OnGet()
    {
    }
}

Le code précédent configure une page Razor qui nécessite l’activation FeatureX . Si la fonctionnalité n’est pas activée, la page génère un résultat HTTP 404 (NotFound).

Lorsque vous utilisez un FeatureGateAttribute objet sur des pages Razor, vous devez placer FeatureGateAttribute sur le type de gestionnaire de pages. Vous ne pouvez pas le placer sur des méthodes de gestionnaire individuelles.

Création d’application

Vous pouvez utiliser la bibliothèque de gestion des fonctionnalités pour ajouter des branches d’application et des intergiciels qui s’exécutent de manière conditionnelle en fonction de l’état d’une fonctionnalité.

app.UseMiddlewareForFeature<ThirdPartyMiddleware>("FeatureX");

Dans le code précédent, l’application ajoute un composant middleware qui apparaît dans le pipeline de requête uniquement si la FeatureX fonctionnalité est activée. Si la fonctionnalité est activée ou désactivée pendant l’exécution, le pipeline d’intergiciels peut être modifié dynamiquement.

Comme le montre le code suivant, cette fonctionnalité s’appuie sur la fonctionnalité la plus générique pour brancher l’ensemble de l’application en fonction d’une fonctionnalité.

app.UseForFeature(featureName, appBuilder => 
{
    appBuilder.UseMiddleware<T>();
});

Implémenter un filtre de fonctionnalités

La création d’un filtre de fonctionnalités permet d’activer des fonctionnalités en fonction des critères que vous définissez. Pour implémenter un filtre de fonctionnalités, vous devez implémenter l’interface IFeatureFilter . IFeatureFilter a une méthode unique nommée EvaluateAsync. Lorsqu’une fonctionnalité spécifie qu’elle peut être activée pour un filtre de fonctionnalités, la méthode EvaluateAsync est appelée. Si EvaluateAsync renvoie true, la fonctionnalité doit être activée.

Le code suivant montre comment ajouter un filtre de fonctionnalités personnalisé appelé MyCriteriaFilter.

services.AddFeatureManagement()
        .AddFeatureFilter<MyCriteriaFilter>();

Vous pouvez inscrire un filtre de fonctionnalités en appelant AddFeatureFilter<T> sur l’implémentation IFeatureManagementBuilder que AddFeatureManagement retourne. Le filtre de fonctionnalités a accès aux services de la collection de services que vous utilisez pour ajouter des indicateurs de fonctionnalité. Vous pouvez utiliser l’injection de dépendances pour récupérer ces services.

Remarque

Lorsque vous référencez des filtres dans les paramètres d’indicateur de fonctionnalité (par exemple, appsettings.json), vous devez omettre la Filter partie du nom de type. Pour plus d’informations, consultez l’attribut d’alias de filtre, plus loin dans cet article.

Filtres de fonctionnalités paramétrables

Certains filtres de fonctionnalités nécessitent des paramètres pour déterminer si une fonctionnalité doit être activée. Par exemple, il est possible qu’un filtre de fonctionnalités de navigateur active une fonctionnalité pour un certain ensemble de navigateurs. Vous pouvez activer une fonctionnalité dans les navigateurs Microsoft Edge et Chrome, mais pas dans Firefox.

Pour implémenter ce filtrage, vous pouvez concevoir un filtre de fonctionnalités pour s’attendre à des paramètres. Vous spécifiez ces paramètres dans la configuration des fonctionnalités. Dans le code, vous y accédez via le paramètre FeatureFilterEvaluationContext de IFeatureFilter.EvaluateAsync.

public class FeatureFilterEvaluationContext
{
    /// <summary>
    /// The name of the feature being evaluated
    /// </summary>
    public string FeatureName { get; set; }

    /// <summary>
    /// The settings provided for the feature filter to use when evaluating whether the feature should be enabled
    /// </summary>
    public IConfiguration Parameters { get; set; }
}

La FeatureFilterEvaluationContext classe a une propriété nommée Parameters. Les paramètres de cette propriété représentent une configuration brute que le filtre de fonctionnalités peut utiliser lors de l’évaluation de l’activation de la fonctionnalité. Dans l’exemple de filtre de fonctionnalité du navigateur, le filtre peut utiliser la Parameters propriété pour extraire un ensemble de navigateurs autorisés spécifiés pour la fonctionnalité. Le filtre peut ensuite vérifier si la requête provient de l’un de ces navigateurs.

[FilterAlias("Browser")]
public class BrowserFilter : IFeatureFilter
{
    …

    public Task<bool> EvaluateAsync(FeatureFilterEvaluationContext context)
    {
        BrowserFilterSettings settings = context.Parameters.Get<BrowserFilterSettings>() ?? new BrowserFilterSettings();

        //
        // Use the settings to check whether the request is from a browser in BrowserFilterSettings.AllowedBrowsers.
    }
}

Attribut d’alias de filtre

Lorsque vous inscrivez un filtre de fonctionnalité pour un indicateur de fonctionnalité, l’alias que vous utilisez dans la configuration est le nom du type de filtre de fonctionnalité avec le Filter suffixe, le cas échéant, supprimé. Par exemple, vous devez faire référence à MyCriteriaFilter en tant que MyCriteria dans la configuration.

{
    "id": "MyFeature",
    "enabled": true,
    "conditions": {
        "client_filters": [
            {
                "name": "MyCriteria"
            }
        ]
    }
}

Vous pouvez remplacer ce nom à l’aide de la FilterAliasAttribute classe. Pour déclarer un nom à utiliser dans la configuration pour référencer un filtre de fonctionnalités dans un indicateur de fonctionnalité, vous pouvez décorer le filtre de fonctionnalités avec cet attribut.

Filtres de fonctionnalités manquants

Supposons que vous configurez une fonctionnalité pour qu’elle soit activée pour un filtre de fonctionnalité spécifique. Si ce filtre de fonction n’est pas inscrit, une exception est levée lorsque la fonctionnalité est évaluée. Comme le montre le code suivant, vous pouvez désactiver l’exception à l’aide des options de gestion des fonctionnalités.

services.Configure<FeatureManagementOptions>(options =>
{
    options.IgnoreMissingFeatureFilters = true;
});

Utiliser HttpContext

Les filtres de fonctionnalités peuvent évaluer si une fonctionnalité doit être activée en fonction des propriétés d’une requête HTTP. Cette vérification est effectuée en inspectant le contexte HTTP. Comme le montre le code suivant, un filtre de fonctionnalités peut obtenir une référence au contexte HTTP à l’aide de l’injection de dépendances pour obtenir une implémentation de IHttpContextAccessor.

public class BrowserFilter : IFeatureFilter
{
    private readonly IHttpContextAccessor _httpContextAccessor;

    public BrowserFilter(IHttpContextAccessor httpContextAccessor)
    {
        _httpContextAccessor = httpContextAccessor ?? throw new ArgumentNullException(nameof(httpContextAccessor));
    }
}

Vous devez ajouter l’implémentation IHttpContextAccessor au conteneur d’injection de dépendances au démarrage pour qu’il soit disponible. Vous pouvez utiliser la méthode suivante pour inscrire l’implémentation dans les IServiceCollection services.

public void ConfigureServices(IServiceCollection services)
{
    …
    services.AddHttpContextAccessor();
    …
}

Avancé:IHttpContextAccessor et HttpContext ne doivent pas être utilisés dans les composants Razor des applications Blazor côté serveur. L’approche recommandée pour passer le contexte HTTP dans les applications Blazor consiste à copier les données dans un service étendu. Pour les applications Blazor, vous devez utiliser AddScopedFeatureManagement pour inscrire des services de gestion des fonctionnalités. Pour plus d’informations, consultez les services de gestion des fonctionnalités délimités, plus haut dans cet article.

Fournir un contexte pour l’évaluation des fonctionnalités

Dans les applications console, il n’existe aucun contexte ambiant tel que HttpContext, que les filtres de fonctionnalités peuvent exploiter pour vérifier si une fonctionnalité doit être activée. Dans ce cas, les applications doivent fournir un objet qui représente un contexte au système de gestion des fonctionnalités à utiliser par les filtres de fonctionnalités. Vous pouvez utiliser IVariantFeatureManager.IsEnabledAsync<TContext>(string featureName, TContext appContext) pour fournir ce contexte. Pour évaluer l’état d’une fonctionnalité, les filtres de fonctionnalités peuvent utiliser l’objet appContext que vous fournissez au gestionnaire de fonctionnalités.

MyAppContext context = new MyAppContext
{
    AccountId = current.Id
};

if (await featureManager.IsEnabledAsync(feature, context))
{
…
}

Filtres de fonctionnalités contextuelles

Les filtres de fonctionnalités contextuels implémentent l’interface IContextualFeatureFilter<TContext>. Ces filtres de fonctionnalités spéciaux peuvent tirer parti du contexte passé lorsque IVariantFeatureManager.IsEnabledAsync<TContext> est appelé. Le TContext paramètre de type décrit IContextualFeatureFilter<TContext> le type de contexte que le filtre peut gérer. Lorsque vous développez un filtre de fonctionnalités contextuelles, vous pouvez établir les conditions requises pour l’utilisation du filtre en spécifiant un type de contexte.

Étant donné que chaque type est un descendant de la Object classe, un filtre qui implémente IContextualFeatureFilter<object> peut être appelé pour n’importe quel contexte fourni. Le code suivant fournit un exemple de filtre de fonctionnalité contextuelle spécifique. Dans ce code, une fonctionnalité est activée si un compte se trouve dans une liste configurée de comptes activés.

public interface IAccountContext
{
    string AccountId { get; set; }
}

[FilterAlias("AccountId")]
class AccountIdFilter : IContextualFeatureFilter<IAccountContext>
{
    public Task<bool> EvaluateAsync(FeatureFilterEvaluationContext featureEvaluationContext, IAccountContext accountId)
    {
        //
        // Evaluate whether the feature should be on by using the IAccountContext that's provided.
    }
}

La AccountIdFilter classe nécessite un objet qui implémente IAccountContext pour être en mesure d’évaluer l’état d’une fonctionnalité. Lorsque vous utilisez ce filtre de fonctionnalités, l’appelant doit s’assurer que l’objet transmis implémente IAccountContext.

Remarque

Une seule interface de filtre de fonctionnalités peut être implémentée par un type unique. La tentative d’ajout d’un filtre de fonctionnalités qui implémente plusieurs interfaces de filtre de fonctionnalités entraîne une ArgumentException exception.

Utiliser des filtres contextuels et non contextuels avec le même alias

Filtres qui implémentent IFeatureFilter et IContextualFeatureFilter peuvent partager le même alias. Plus précisément, vous pouvez avoir un alias de filtre partagé par zéro ou une implémentation IFeatureFilter et zéro ou des implémentations NIContextualFeatureFilter<ContextType> s’il existe au plus un filtre applicable pour ContextType.

Pour comprendre le processus de sélection d’un filtre lorsque des filtres contextuels et non contextuels du même nom sont inscrits dans une application, considérez l’exemple suivant.

Trois filtres partagent l’alias SharedFilterName :

  • Un filtre non contextuel appelé FilterA
  • Filtre contextuel appelé FilterB qui accepte un TypeB contexte
  • Filtre contextuel appelé FilterC qui accepte un TypeC contexte

Un indicateur de fonctionnalité appelé MyFeature utilise le SharedFilterName filtre de fonctionnalités dans sa configuration.

Si les trois filtres sont inscrits :

  • Lorsque vous appelez IsEnabledAsync("MyFeature"), le FilterA filtre est utilisé pour évaluer l’indicateur de fonctionnalité.
  • Quand vous appelez IsEnabledAsync("MyFeature", context):
    • Si le type est contextTypeB, FilterB est utilisé.
    • Si le type est contextTypeC, FilterC est utilisé.
    • Si le type est contextTypeF, FilterA est utilisé.

Filtres de fonctionnalités intégrés

Il existe quelques filtres de fonctionnalités fournis avec le Microsoft.FeatureManagement package : PercentageFilter, , TimeWindowFilterContextualTargetingFilter, et TargetingFilter. Tous les filtres à l’exception du filtre spécifié TargetingFilter sont ajoutés automatiquement lorsque vous utilisez la méthode AddFeatureManagement pour enregistrer la gestion des fonctionnalités. TargetingFilter est ajouté à l’aide de la WithTargeting méthode. Pour plus d’informations, consultez Ciblage, plus loin dans cet article.

Chacun des filtres de fonctionnalités intégrés a ses propres paramètres. Les sections suivantes décrivent ces filtres de fonctionnalités et fournissent des exemples.

Microsoft.Percentage

Le Microsoft.Percentage filtre permet d’activer une fonctionnalité en fonction d’un pourcentage défini.

{
    "id": "EnhancedPipeline",
    "enabled": true,
    "conditions": {
        "client_filters": [
            {
                "name": "Microsoft.Percentage",
                "parameters": {
                    "Value": 50
                }
            }
        ]
    }
}

Microsoft.TimeWindow

Le Microsoft.TimeWindow filtre permet d’activer une fonctionnalité en fonction d’une fenêtre de temps.

  • Si vous spécifiez uniquement une End valeur, la fonctionnalité est considérée comme activée jusqu’à ce moment.
  • Si spécifiez une seule valeur Start, la fonctionnalité est considérée comme activée sur tous les points après cette heure.
{
    "id": "EnhancedPipeline",
    "enabled": true,
    "conditions": {
        "client_filters": [
            {
                "name": "Microsoft.TimeWindow",
                "parameters": {
                    "Start": "Sun, 01 Jun 2025 13:59:59 GMT",
                    "End": "Fri, 01 Aug 2025 00:00:00 GMT"
                }
            }
        ]
    }
}

Vous pouvez configurer le filtre pour appliquer une fenêtre de temps périodique. Cette fonctionnalité peut être utile lorsque vous devez activer une fonctionnalité pendant une période de faible trafic ou de trafic élevé d’un jour ou d’un certain jour d’une semaine. Pour étendre une fenêtre de temps individuelle à une fenêtre de temps périodique, vous utilisez un Recurrence paramètre pour spécifier une règle de périodicité.

Remarque

Pour utiliser la périodicité, vous devez spécifier Start et End valeurs. En cas de périodicité, la partie date de la valeur End ne spécifie pas de date de fin pour que le filtre soit considéré comme actif. Au lieu de cela, le filtre utilise la date de fin, par rapport à la date de début, pour définir la durée de la fenêtre d’heure qui se répète.

{
    "id": "EnhancedPipeline",
    "enabled": true,
    "conditions": {
        "client_filters": [
            {
                "name": "Microsoft.TimeWindow",
                "parameters": {
                    "Start": "Fri, 22 Mar 2024 20:00:00 GMT",
                    "End": "Sat, 23 Mar 2024 02:00:00 GMT",
                    "Recurrence": {
                        "Pattern": {
                            "Type": "Daily",
                            "Interval": 1
                        },
                        "Range": {
                            "Type": "NoEnd"
                        }
                    }
                }
            }
        ]
    }
}

Les Recurrence paramètres sont constitués de deux parties :

  • Les Pattern paramètres spécifient la fréquence à laquelle la fenêtre de temps se répète.
  • Les Range paramètres spécifient la durée pendant laquelle le modèle de périodicité se répète.

Modèle de périodicité

Il existe deux types de modèles de périodicité possibles : Daily et Weekly. Par exemple, une fenêtre de temps peut se répéter tous les jours, tous les trois jours, tous les lundis ou tous les autres vendredis.

Selon le type, certains champs des Pattern paramètres sont obligatoires, facultatifs ou ignorés.

  • Daily

    Le modèle de périodicité quotidienne entraîne la répétition de la fenêtre de temps en fonction d’un nombre spécifié de jours entre chaque occurrence.

    Propriété Pertinence Description
    Type Obligatoire Type de modèle de périodicité. Cette propriété doit être définie sur Daily.
    Interval Facultatif Nombre de jours entre chaque occurrence. La valeur par défaut est 1.

  • Weekly

    Le modèle de périodicité hebdomadaire entraîne la répétition de la fenêtre de temps le ou les mêmes jours de la semaine. Toutefois, vous pouvez spécifier le nombre de semaines entre chaque ensemble d’occurrences.

    Propriété Pertinence Description
    Type Obligatoire Type de modèle de périodicité. Cette propriété doit être définie sur Weekly.
    DaysOfWeek Obligatoire Les jours de la semaine sur lesquels l’événement se produit.
    Interval Facultatif Nombre de semaines entre chaque ensemble d’occurrences. La valeur par défaut est 1.
    FirstDayOfWeek Facultatif Jour à utiliser comme premier jour de la semaine. La valeur par défaut est Sunday.

    L’exemple suivant répète la fenêtre de temps tous les autres lundi et mardi :

    "Pattern": {
    "Type": "Weekly",
    "Interval": 2,
    "DaysOfWeek": ["Monday", "Tuesday"]
}

Remarque

La Start valeur doit être une première occurrence valide qui correspond au modèle de périodicité. En outre, la durée de la fenêtre de temps ne peut pas être plus longue que la fréquence à laquelle elle se produit. Par exemple, une fenêtre de temps de 25 heures ne peut pas se reproduire tous les jours.

Plage de périodicité

Il existe trois types de plages de périodicité possibles : NoEnd, EndDateet Numbered.

  • NoEnd

    La plage NoEnd entraîne une périodicité indéfinie.

    Propriété Pertinence Description
    Type Obligatoire Type de plage de périodicité. Cette propriété doit être définie sur NoEnd.

  • EndDate

    La plage EndDate entraîne l’exécution de la fenêtre de temps tous les jours qui correspondent au modèle applicable jusqu’à la date de fin.

    Propriété Pertinence Description
    Type Obligatoire Type de plage de périodicité. Cette propriété doit être définie sur EndDate.
    EndDate Obligatoire Date et heure d’arrêt de l’application du modèle. Si l’heure de début de la dernière occurrence tombe avant la date de fin, l’heure de fin de cette occurrence peut s’étendre au-delà de celle-ci.

    Dans l’exemple suivant, la fenêtre de temps se répète tous les jours jusqu’au dernier événement le 1er avril 2024.

    "Start": "Fri, 22 Mar 2024 18:00:00 GMT",
"End": "Fri, 22 Mar 2024 20:00:00 GMT",
"Recurrence":{
    "Pattern": {
        "Type": "Daily",
        "Interval": 1
    },
    "Range": {
        "Type": "EndDate",
        "EndDate": "Mon, 1 Apr 2024 20:00:00 GMT"
    }
}

  • Numbered

    La plage Numbered provoque l'occurrence d'une fenêtre de temps un nombre de fois spécifié.

    Propriété Pertinence Description
    Type Obligatoire Type de plage de périodicité. Cette propriété doit être définie sur Numbered.
    NumberOfOccurrences Obligatoire Nombre d’occurrences.

    Dans l’exemple suivant, la fenêtre de temps se répète le lundi et le mardi pour un total de trois occurrences, qui se produisent à la date suivante :

    • Lundi 1er avril
    • Mardi 2 avril
    • Lundi 8 avril
    "Start": "Mon, 1 Apr 2024 18:00:00 GMT",
"End": "Mon, 1 Apr 2024 20:00:00 GMT",
"Recurrence":{
    "Pattern": {
        "Type": "Weekly",
        "Interval": 1,
        "DaysOfWeek": ["Monday", "Tuesday"]
    },
    "Range": {
        "Type": "Numbered",
        "NumberOfOccurrences": 3
    }
}

Pour créer une règle de récurrence, vous devez spécifier les paramètres Pattern et Range. N’importe quel type de modèle peut fonctionner avec n’importe quel type de plage.

Avancé : le décalage de fuseau horaire de la propriété Start est appliqué aux paramètres de périodicité.

Microsoft.Targeting

Le Microsoft.Targeting filtre permet d’activer une fonctionnalité pour un public cible. Pour obtenir une explication détaillée du ciblage, consultez Ciblage, plus loin dans cet article.

Les paramètres de filtre incluent un Audience objet qui décrit qui a accès à la fonctionnalité. Dans l’objet Audience , vous pouvez spécifier des utilisateurs, des groupes, des utilisateurs exclus et des groupes, ainsi qu’un pourcentage par défaut de la base d’utilisateurs.

Pour chaque objet de groupe que vous répertoriez dans la Groups section, vous devez également spécifier le pourcentage des membres du groupe qui doivent avoir accès.

Pour chaque utilisateur, la fonctionnalité est évaluée de la façon suivante :

  • Si l’utilisateur est exclu, la fonctionnalité est désactivée pour l’utilisateur. Vous pouvez exclure l’utilisateur par :

    • Énumération de leurs noms sous Users dans la section Exclusion.
    • Énumération d’un groupe auquel ils appartiennent sous Groups dans la section Exclusion.

  • Si l’utilisateur n’est pas exclu, la fonctionnalité est activée si l’une des conditions suivantes est remplie :

    • L’utilisateur est répertorié dans la Users section.
    • L'utilisateur fait partie du pourcentage inclus dans l'un des déploiements de groupe.
    • L’utilisateur tombe dans le pourcentage de déploiement par défaut.

  • Si aucun des cas précédents ne s’applique, la fonctionnalité est désactivée pour l’utilisateur. Par exemple, si l’utilisateur n’est pas dans un pourcentage inclus, la fonctionnalité est désactivée.

{
    "id": "EnhancedPipeline",
    "enabled": true,
    "conditions": {
        "client_filters": [
            {
                "name": "Microsoft.Targeting",
                "parameters": {
                    "Audience": {
                        "Users": [
                            "Jeff",
                            "Alicia"
                        ],
                        "Groups": [
                            {
                                "Name": "Ring0",
                                "RolloutPercentage": 100
                            },
                            {
                                "Name": "Ring1",
                                "RolloutPercentage": 50
                            }
                        ],
                        "DefaultRolloutPercentage": 20,
                        "Exclusion": {
                            "Users": [
                                "Ross"
                            ],
                            "Groups": [
                                "Ring2"
                            ]
                        }
                    }
                }
            }
        ]
    }
}

Espaces de noms d'alias pour le filtrage des fonctionnalités

Tous les alias de filtre de fonctionnalités intégrés se trouvent dans l’espace de noms du filtre de fonctionnalités Microsoft. L’utilisation de cet espace de noms empêche les conflits avec d’autres filtres de fonctionnalités qui partagent le même alias. Les segments d'un espace de noms du filtre de fonctionnalité sont séparés par le caractère .. Vous pouvez référencer un filtre de fonctionnalités par son alias complet, tel que Microsoft.Percentage. Vous pouvez également référencer le dernier segment, tel que Percentage.

Ciblage

Le ciblage est une stratégie de gestion des fonctionnalités que vous pouvez utiliser pour déployer progressivement de nouvelles fonctionnalités sur votre base d’utilisateurs. La stratégie repose sur le concept de ciblage d’un ensemble d’utilisateurs appelé public cible. Un public est constitué d’utilisateurs, de groupes, d’utilisateurs exclus et de groupes spécifiques et d’un pourcentage désigné de la base d’utilisateurs entière. Les groupes inclus dans le public peuvent être divisés en pourcentages de leurs membres totaux.

Les étapes suivantes illustrent un exemple de déploiement progressif pour une nouvelle fonctionnalité appelée Bêta :

  1. Les utilisateurs individuels Jeff et Alicia ont accès à la fonctionnalité Bêta.
  2. Un autre utilisateur, Mark, demande à participer et est inclus.
  3. Vingt pour cent des utilisateurs du groupe Ring1 sont inclus dans la fonctionnalité Bêta.
  4. Le nombre d’utilisateurs Ring1 inclus est passé à 100 %.
  5. Cinq pour cent de la base d’utilisateurs sont inclus dans la fonctionnalité Bêta.
  6. Le pourcentage de déploiement est porté à 100 % pour finaliser le déploiement de la fonctionnalité.

La bibliothèque prend en charge cette stratégie pour déployer une fonctionnalité via le filtre de fonctionnalité intégré Microsoft.Targeting .

Ciblage dans une application web

Pour obtenir un exemple d’application web qui utilise le filtre de fonctionnalités de ciblage, consultez l’exemple de projet FeatureFlagDemo .

Pour commencer à utiliser TargetingFilter dans une application, vous devez l’ajouter à la collection de services de l’application comme n’importe quel autre filtre de fonctionnalités. Contrairement à d’autres filtres intégrés, TargetingFilter s’appuie sur un autre service à ajouter à la collection de services de l’application. Ce service est une ITargetingContextAccessor implémentation.

La bibliothèque Microsoft.FeatureManagement.AspNetCore fournit une implémentation par défaut de ITargetingContextAccessor qui extrait les informations de ciblage à partir de la valeur d’une requête HttpContext. Vous pouvez utiliser l’accesseur de contexte de ciblage par défaut lorsque vous configurez le ciblage en tirant parti de la surcharge non générique WithTargeting sur IFeatureManagementBuilder.

Pour inscrire l’accesseur de contexte de ciblage par défaut et TargetingFilter, vous appelez WithTargeting sur IFeatureManagementBuilder.

services.AddFeatureManagement()
        .WithTargeting();

Vous pouvez également inscrire une implémentation personnalisée pour ITargetingContextAccessor et TargetingFilter en appelant WithTargeting<T>. Le code suivant configure la gestion des fonctionnalités dans une application web pour utiliser TargetingFilter avec une implémentation de ITargetingContextAccessor appelée ExampleTargetingContextAccessor.

services.AddFeatureManagement()
        .WithTargeting<ExampleTargetingContextAccessor>();

ITargetingContextAccessor

Pour utiliser TargetingFilter dans une application web, une implémentation de ITargetingContextAccessor est requise. Le raisonnement derrière cette exigence est que des informations contextuelles, telles que des informations sur l’utilisateur, sont nécessaires pour cibler des évaluations. Ces informations sont stockées dans des instances de la TargetingContext classe. Différentes applications extraient ces informations à partir de différents emplacements, tels que le contexte HTTP d’une requête ou une base de données.

Pour un exemple qui extrait des informations de contexte de ciblage à partir du contexte HTTP d'une application, consultez le DefaultHttpTargetingContextAccessor dans le paquet Microsoft.FeatureManagement.AspNetCore. Il extrait les informations suivantes :

  • Ciblage d’informations à partir de la propriété HttpContext.User
  • UserId informations du Identity.Name champ
  • Groups information provenant des réclamations de type Role

Cette implémentation s’appuie sur l’utilisation de IHttpContextAccessor. Pour plus d’informations sur IHttpContextAccessor, consultez Utiliser HttpContext, plus haut dans cet article.

Ciblage dans une application console

Le filtre de ciblage s’appuie sur un contexte de ciblage pour évaluer si une fonctionnalité doit être activée. Ce contexte de ciblage contient des informations telles que l’utilisateur en cours d’évaluation et les groupes auxquels appartient l’utilisateur. Dans les applications console, il n’existe généralement aucun contexte ambiant disponible pour transmettre ces informations au filtre de ciblage. Par conséquent, vous devez le transmettre directement lorsque vous appelez FeatureManager.IsEnabledAsync. Ce type de contexte est pris en charge en utilisant ContextualTargetingFilter. Les applications qui doivent envoyer le contexte de ciblage au gestionnaire de fonctionnalités doivent utiliser ContextualTargetingFilter au lieu de TargetingFilter.

Étant donné que ContextualTargetingFilter implémente IContextualTargetingFilter<ITargetingContext>, vous devez passer une implémentation de ITargetingContext à IVariantFeatureManager.IsEnabledAsync pour qu'elle puisse évaluer et activer une fonctionnalité.

IVariantFeatureManager fm;
…
// The userId and groups variables are defined earlier in the application.
TargetingContext targetingContext = new TargetingContext
{
   UserId = userId,
   Groups = groups
};

await fm.IsEnabledAsync(featureName, targetingContext);

ContextualTargetingFilter utilise l’alias Microsoft.Targetingde filtre de fonctionnalités. Par conséquent, la configuration de ce filtre est cohérente avec les informations de Microsoft.Targeting, plus haut dans cet article.

Pour obtenir un exemple qui utilise ContextualTargetingFilter dans une application console, consultez l’exemple de projet TargetingConsoleApp .

Options de ciblage pour l'évaluation

Des options sont disponibles pour personnaliser la façon dont l’évaluation du ciblage est effectuée sur toutes les fonctionnalités. Vous pouvez configurer ces options lorsque vous configurez la gestion des fonctionnalités.

services.Configure<TargetingEvaluationOptions>(options =>
{
    options.IgnoreCase = true;
});

Exclusion de ciblage

Lorsque vous définissez une audience, vous pouvez exclure des utilisateurs et des groupes de l’audience. Cette fonctionnalité est utile lorsque vous déployez une fonctionnalité sur un groupe d’utilisateurs, mais vous devez exclure quelques utilisateurs ou groupes du déploiement. Pour spécifier des utilisateurs et des groupes à exclure, vous utilisez la Exclusion propriété d’une audience.

"Audience": {
    "Users": [
        "Jeff",
        "Alicia"
    ],
    "Groups": [
        {
            "Name": "Ring0",
            "RolloutPercentage": 100
        }
    ],
    "DefaultRolloutPercentage": 0,
    "Exclusion": {
        "Users": [
            "Mark"
        ]
    }
}

Le code précédent active une fonctionnalité pour les utilisateurs nommés Jeff et Alicia. La fonctionnalité est également activée pour les utilisateurs du groupe nommé Ring0. Toutefois, la fonctionnalité est désactivée pour l’utilisateur nommé Mark, même si cet utilisateur se trouve dans le Ring0 groupe. Les exclusions sont prioritaires sur le reste du filtre de ciblage.

Variantes

Parfois, lorsque vous ajoutez une nouvelle fonctionnalité à une application, la fonctionnalité propose plusieurs options de conception proposées. Les tests A/B offrent une solution courante pour décider d’une conception. Les tests A/B impliquent de fournir une version différente de la fonctionnalité à différents segments de la base utilisateur, puis de choisir une version en fonction de l’interaction utilisateur. Dans la bibliothèque de gestion des fonctionnalités .NET, vous pouvez implémenter des tests A/B à l’aide de variantes pour représenter différentes configurations d’une fonctionnalité.

Les variantes permettent à un indicateur de fonctionnalité de devenir plus qu’un indicateur de base activé/désactivé. Une variante représente une valeur d’un indicateur de fonctionnalité qui peut être une chaîne, un nombre, un booléen ou même un objet de configuration. Un indicateur de fonctionnalité qui déclare des variantes doit définir les circonstances dans lesquelles chaque variante doit être utilisée. Pour plus d’informations, consultez Allouer des variantes, plus loin dans cet article.

public class Variant
{
    /// <summary>
    /// The name of the variant
    /// </summary>
    public string Name { get; set; }

    /// <summary>
    /// The configuration of the variant
    /// </summary>
    public IConfigurationSection Configuration { get; set; }
}

Récupérer des variantes

Pour chaque fonctionnalité, vous pouvez récupérer une variante à l’aide de la GetVariantAsync méthode de l’interface IVariantFeatureManager .

…
IVariantFeatureManager featureManager;
…
Variant variant = await featureManager.GetVariantAsync("MyVariantFeatureFlag", CancellationToken.None);

IConfigurationSection variantConfiguration = variant.Configuration;

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

Après avoir récupéré une variante, vous pouvez utiliser sa configuration directement comme implémentation du IConfigurationSection, depuis la propriété Configuration de la variante. Une autre option consiste à lier la configuration à un objet à l’aide du modèle de liaison de configuration .NET.

IConfigurationSection variantConfiguration = variant.Configuration;

MyFeatureSettings settings = new MyFeatureSettings();

variantConfiguration.Bind(settings);

La variante retournée dépend de l’utilisateur qui est évalué. Vous pouvez obtenir des informations sur l’utilisateur à partir d’une instance de TargetingContext. Vous pouvez passer ce contexte lorsque vous appelez GetVariantAsync. Ou il peut être récupéré automatiquement à partir d’une implémentation de ITargetingContextAccessor si l’un d’eux est inscrit.

Déclaration d’indicateur de fonctionnalité de variante

Par rapport aux indicateurs de fonctionnalité standard, les indicateurs de fonctionnalité variant ont deux propriétés supplémentaires : variants et allocation. La variants propriété est un tableau qui contient les variantes définies pour la fonctionnalité. La propriété allocation définit la façon dont ces variantes doivent être allouées pour la fonctionnalité. Tout comme la déclaration d’indicateurs de fonctionnalité standard, vous pouvez configurer des indicateurs de fonctionnalité de variante dans un fichier JSON. Le code suivant est un exemple d’indicateur de fonctionnalité variant :

{
    "feature_management": {
        "feature_flags": [
            {
                "id": "MyVariantFeatureFlag",
                "enabled": true,
                "allocation": {
                    "default_when_enabled": "Small",
                    "group": [
                        {
                            "variant": "Big",
                            "groups": [
                                "Ring1"
                            ]
                        }
                    ]
                },
                "variants": [
                    { 
                        "name": "Big"
                    },  
                    { 
                        "name": "Small"
                    } 
                ]
            }
        ]
    }
}

Définir des variantes

Chaque variante a deux propriétés : un nom et une configuration. Le nom est utilisé pour faire référence à une variante spécifique, et la configuration est la valeur de cette variante. Vous pouvez utiliser la configuration_value propriété pour spécifier la configuration. La configuration_value propriété est une configuration inline qui peut être une chaîne, un nombre, un booléen ou un objet de configuration. Si vous ne configurez pas la propriété configuration_value, la propriété Configuration de la variante retournée est null.

Pour spécifier toutes les variantes possibles d’une fonctionnalité, vous les répertoriez sous la variants propriété.

{
    "feature_management": {
        "feature_flags": [
            {
                "id": "MyVariantFeatureFlag",
                "variants": [
                    { 
                        "name": "Big", 
                        "configuration_value": {
                            "Size": 500
                        }
                    },  
                    { 
                        "name": "Small", 
                        "configuration_value": {
                            "Size": 300
                        }
                    } 
                ]
            }
        ]
    }
}

Allouer des variantes

Pour allouer les variantes d’une fonctionnalité, vous utilisez la allocation propriété de la fonctionnalité.

"allocation": { 
    "default_when_enabled": "Small", 
    "default_when_disabled": "Small",  
    "user": [ 
        { 
            "variant": "Big", 
            "users": [ 
                "Marsha" 
            ] 
        } 
    ], 
    "group": [ 
        { 
            "variant": "Big", 
            "groups": [ 
                "Ring1" 
            ] 
        } 
    ],
    "percentile": [ 
        { 
            "variant": "Big", 
            "from": 0, 
            "to": 10 
        } 
    ], 
    "seed": "13973240" 
},
"variants": [
    { 
        "name": "Big", 
        "configuration_value": "500px"
    },  
    { 
        "name": "Small", 
        "configuration_value": "300px"
    } 
]

Le allocation paramètre a les propriétés suivantes :

Propriété Description
default_when_disabled Variante à utiliser lorsqu’une variante est demandée pendant que la fonctionnalité est considérée comme désactivée.
default_when_enabled Variante à utiliser lorsqu’une variante est demandée pendant que la fonctionnalité est considérée comme activée et qu’aucune autre variante n’est affectée à l’utilisateur.
user Variante et liste d’utilisateurs auxquels attribuer la variante.
group Variante et liste de groupes. La variante est attribuée si l’utilisateur actuel se trouve dans au moins un des groupes.
percentile Une variante et une plage de pourcentage dans laquelle le pourcentage calculé de l'utilisateur doit entrer pour que la variante soit affectée.
seed Valeur sur laquelle les calculs percentile de pourcentage sont basés. Le calcul de pourcentage pour un utilisateur spécifique est le même pour toutes les fonctionnalités si la même seed valeur est utilisée. Si aucune valeur n’est seed spécifiée, une valeur initiale par défaut est créée en fonction du nom de la fonctionnalité.

Si une fonctionnalité n’est pas activée, le gestionnaire de fonctionnalités affecte la variante spécifiée pour default_when_disabled l’utilisateur actuel. Dans l’exemple précédent, cette fonctionnalité est appelée Small.

Si la fonctionnalité est activée, le gestionnaire de fonctionnalités vérifie les allocations user, group et percentile dans cet ordre pour affecter une variante. Dans l’exemple précédent, la variante spécifiée est Bigaffectée à l’utilisateur dans les cas suivants :

  • L’utilisateur en cours d’évaluation est nommé Marsha.
  • L’utilisateur se trouve dans le Ring1 groupe.
  • L’utilisateur se trouve entre le zéroème et le dixième centile.

Si aucune de ces allocations ne correspond, la default_when_enabled variante est affectée à l’utilisateur. Dans l’exemple, cette variante est Small.

La logique d’allocation est similaire à la logique que vous utilisez pour le filtre de fonctionnalités Microsoft.Targeting . Mais il existe certains paramètres présents dans le ciblage qui ne sont pas dans l’allocation, et inversement. Les résultats du ciblage et de l’allocation ne sont pas liés.

Remarque

Pour allouer des variantes de fonctionnalité, vous devez enregistrer ITargetingContextAccessor en appelant la méthode WithTargeting<T>.

Remplacer l’état activé à l’aide d’une variante

Vous pouvez utiliser des variantes pour remplacer l’état activé d’un indicateur de fonctionnalité. Lorsque vous tirez parti de cette fonctionnalité, vous pouvez étendre l’évaluation d’un indicateur de fonctionnalité. Pendant l’appel à IsEnabledAsync un indicateur avec des variantes, le gestionnaire de fonctionnalités vérifie si la variante affectée à l’utilisateur actuel est configurée pour remplacer le résultat.

Vous pouvez implémenter le remplacement en utilisant la propriété status_override de variante facultative. Cette propriété peut avoir les valeurs suivantes :

  • None: la variante n’affecte pas si l’indicateur est considéré comme activé ou désactivé. None est la valeur par défaut.
  • Enabled: lorsque la variante est choisie, l’indicateur de fonctionnalité est évalué comme activé.
  • Disabled: lorsque la variante est choisie, l’indicateur de fonctionnalité est évalué comme désactivé.

Vous ne pouvez pas remplacer une fonctionnalité qui a un état enabled de false.

Si vous utilisez un indicateur de fonctionnalité avec des variantes binaires, la status_override propriété peut être utile. Vous pouvez continuer à utiliser des API telles que IsEnabledAsync et FeatureGateAttribute dans votre application. Toutefois, vous pouvez également tirer parti des fonctionnalités fournies avec des variantes, telles que l’allocation de centile et l’utilisation d’une valeur de départ pour les calculs de pourcentage.

{
    "id": "MyVariantFeatureFlag",
    "enabled": true,
    "allocation": {
        "percentile": [
            {
                "variant": "On",
                "from": 10,
                "to": 20
            }
        ],
        "default_when_enabled":  "Off",
        "seed": "Enhanced-Feature-Group"
    },
    "variants": [
        {
            "name": "On"
        },
        {
            "name": "Off",
            "status_override": "Disabled"
        }
    ]
}

Dans l’exemple précédent, la fonctionnalité est toujours activée. Si l’utilisateur actuel se trouve dans la plage de centile calculée de 10 à 20, la On variante est retournée. Sinon, la Off variante est retournée et, étant donné que la status_override valeur est Disabled, la fonctionnalité est considérée comme désactivée.

Variantes dans l’injection de dépendances

Vous pouvez utiliser des indicateurs de fonctionnalité variants avec l’injection de dépendances pour exposer différentes implémentations d’un service à différents utilisateurs. L’interface IVariantServiceProvider<TService> offre un moyen d’accomplir cette combinaison.

IVariantServiceProvider<IAlgorithm> algorithmServiceProvider;
...

IAlgorithm forecastAlgorithm = await algorithmServiceProvider.GetServiceAsync(cancellationToken);

Dans le code précédent, l’implémentation IVariantServiceProvider<IAlgorithm> récupère une implémentation de IAlgorithm depuis le conteneur d'injection de dépendances. L’implémentation choisie dépend des éléments suivants :

  • Indicateur de fonctionnalité auprès lequel le IAlgorithm service est inscrit.
  • La variante allouée pour cette fonctionnalité.

L’implémentation IVariantServiceProvider<T> est mise à la disposition de l’application en appelant IFeatureManagementBuilder.WithVariantService<T>(string featureName), comme l’illustre l’exemple suivant. L’appel dans ce code rend IVariantServiceProvider<IAlgorithm> disponible dans la collection de services.

services.AddFeatureManagement() 
        .WithVariantService<IAlgorithm>("ForecastAlgorithm");

Vous devez ajouter chaque implémentation de IAlgorithm manière distincte par le biais d’une méthode d’ajout telle que services.AddSingleton<IAlgorithm, SomeImplementation>(). L’implémentation de IAlgorithm que IVariantServiceProvider utilise dépend de l’indicateur de fonctionnalité de variante ForecastAlgorithm. Si aucune implémentation de IAlgorithm n'est ajoutée à la collection de services, IVariantServiceProvider<IAlgorithm>.GetServiceAsync() retourne une tâche avec un résultat de null.

{
    // The example variant feature flag
    "id": "ForecastAlgorithm",
    "enabled": true,
    "variants": [
        { 
            "Name": "AlgorithmBeta" 
        },
        ...
    ] 
}

Attribut d’alias de service variant

Le fournisseur de services variant utilise les noms de types d’implémentations pour correspondre à la variante allouée. Si un service variant est décoré avec VariantServiceAliasAttribute, le nom déclaré dans cet attribut doit être utilisé dans la configuration pour référencer ce service variant.

[VariantServiceAlias("Beta")]
public class AlgorithmBeta : IAlgorithm
{
    ...
}

Télémétrie

Lorsque vous déployez un changement d’indicateur de fonctionnalité, il est souvent important d’analyser son effet sur une application. Par exemple, voici quelques questions qui peuvent survenir :

  • Les indicateurs sont-ils activés et désactivés comme prévu ?
  • Les utilisateurs ciblés ont-ils accès à une certaine fonctionnalité comme prévu ?
  • Quelle variante un utilisateur particulier voit-il ?

L’émission et l’analyse des événements d’évaluation des indicateurs de caractéristiques peuvent vous aider à répondre à ces types de questions. La bibliothèque de gestion des fonctionnalités .NET utilise l’API System.Diagnostics.Activity pour produire des données de télémétrie de suivi pendant l’évaluation de l’indicateur de fonctionnalité.

Activation de la télémétrie

Par défaut, les indicateurs de fonctionnalité n’émettent pas de données de télémétrie. Pour publier des données de télémétrie pour un indicateur de fonctionnalité donné, l’indicateur doit déclarer qu’il est activé pour l’émission de télémétrie.

Pour les indicateurs de fonctionnalité définis dans appsettings.json, vous pouvez activer la télémétrie à l’aide de la telemetry propriété.

{
    "feature_management": {
        "feature_flags": [
            {
                "id": "MyFeatureFlag",
                "enabled": true,
                "telemetry": {
                    "enabled": true
                }
            }
        ]
    }
}

Le code précédent d’un fichier appsettings.json définit un indicateur de fonctionnalité nommé MyFeatureFlag activé pour la télémétrie. L’état de télémétrie est indiqué par l’objet telemetry qui définit enabled à true. La valeur de la propriété enabled doit être true pour publier des données de télémétrie pour l’indicateur.

La section telemetry d’un indicateur de fonctionnalité a les propriétés suivantes :

Propriété Description
enabled Valeur booléenne qui spécifie si la télémétrie doit être publiée pour l’indicateur de fonctionnalité.
metadata Collection de paires clé-valeur, modélisées en tant que dictionnaire, que vous pouvez utiliser pour attacher des métadonnées personnalisées sur l’indicateur de fonctionnalité aux événements d’évaluation.

Remarque

Lorsque vous utilisez le fournisseur de configuration .NET avec Azure App Configuration, des métadonnées de télémétrie supplémentaires sont ajoutées à l’évaluation des indicateurs de fonctionnalité lorsque la télémétrie est activée.

Publication de la télémétrie personnalisée

Le gestionnaire de fonctionnalités possède sa propre ActivitySource instance nommée Microsoft.FeatureManagement. Si la télémétrie est activée pour un indicateur de fonctionnalité :

  • Lorsqu’une évaluation de l’indicateur de fonctionnalité démarre, le gestionnaire de fonctionnalités démarre une instance de Activity.
  • Une fois l’évaluation de l’indicateur de fonctionnalité terminée, le gestionnaire de fonctionnalités ajoute une ActivityEvent instance nommée FeatureFlag à l’activité actuelle.

L’événement FeatureFlag comporte des balises qui incluent les informations relatives à l’évaluation de l’indicateur de fonctionnalité. Les balises utilisent les champs définis dans le schéma FeatureEvaluationEvent .

Remarque

Toutes les paires clé-valeur spécifiées dans la telemetry.metadata propriété de l’indicateur de fonctionnalité sont également incluses dans les balises.

Pour activer la publication de télémétrie personnalisée, vous pouvez créer une instance de ActivityListener et écouter la source d’activité Microsoft.FeatureManagement. Le code suivant vous montre comment écouter la source d’activité de gestion des fonctionnalités et ajouter un rappel lorsqu’une fonctionnalité est évaluée.

ActivitySource.AddActivityListener(new ActivityListener()
{
    ShouldListenTo = (activitySource) => activitySource.Name == "Microsoft.FeatureManagement",
    Sample = (ref ActivityCreationOptions<ActivityContext> options) => ActivitySamplingResult.AllData,
    ActivityStopped = (activity) =>
    {
        ActivityEvent? evaluationEvent = activity.Events.FirstOrDefault((activityEvent) => activityEvent.Name == "FeatureFlag");

        if (evaluationEvent.HasValue && evaluationEvent.Value.Tags.Any())
        {
            // Do something.
        }
    }
});

Pour plus d’informations, consultez Collecter une trace distribuée.

Application Insights Telemetry

Le package Microsoft.FeatureManagement.Telemetry.ApplicationInsights fournit un éditeur de données de télémétrie intégré qui envoie des données d’évaluation des indicateurs de fonctionnalité à Application Insights. Le Microsoft.FeatureManagement.Telemetry.ApplicationInsights package fournit également un initialiseur de télémétrie qui balise automatiquement tous les événements TargetingId afin que les événements puissent être liés aux évaluations d’indicateurs. Pour tirer parti de cette fonctionnalité, ajoutez une référence au package et inscrivez les données de télémétrie Application Insights. Le code suivant montre un exemple :

builder.services
    .AddFeatureManagement()
    .AddApplicationInsightsTelemetry();

Remarque

Pour vous assurer que la télémétrie Application Insights fonctionne comme prévu, vous devez utiliser la TargetingHttpContextMiddleware classe.

Pour activer la persistance du contexte de ciblage dans l’activité actuelle, vous pouvez utiliser la TargetingHttpContextMiddleware classe.

app.UseMiddleware<TargetingHttpContextMiddleware>();

Pour obtenir un exemple de son utilisation, consultez l’exemple VariantAndTelemetryDemo .

Configuration requise

L’éditeur de télémétrie fourni par le Microsoft.FeatureManagement.Telemetry.ApplicationInsights package nécessite la configuration et l’inscription d’Application Insights en tant que service d’application. Pour obtenir un exemple de code, consultez l’exemple d’application VariantAndTelemetryDemo .

Mise en cache

L’état de la fonctionnalité est fourni par le système IConfiguration. Les fournisseurs de configuration sont censés gérer toute mise en cache et mise à jour dynamique. Le gestionnaire de fonctionnalités demande IConfiguration la dernière valeur de l’état d’une fonctionnalité chaque fois qu’elle évalue si une fonctionnalité est activée.

Instantané

Certains scénarios nécessitent que l’état d’une fonctionnalité reste cohérent pendant la durée de vie d’une demande. Les valeurs retournées à partir d’une implémentation standard IVariantFeatureManager peuvent changer si la IConfiguration source à partir de laquelle elle extrait est mise à jour pendant la demande.

Vous pouvez empêcher ce comportement à l’aide de IVariantFeatureManagerSnapshot. Vous pouvez récupérer IVariantFeatureManagerSnapshot de la même manière que IVariantFeatureManager. IVariantFeatureManagerSnapshot implémente l’interface IVariantFeatureManager , mais IVariantFeatureManagerSnapshot met en cache le premier état évalué d’une fonctionnalité pendant une demande. Il retourne cet état pendant la durée de vie de la fonctionnalité.

Fournisseurs de fonctionnalités personnalisés

Lorsque vous implémentez un fournisseur de fonctionnalités personnalisé, vous pouvez extraire des indicateurs de fonctionnalités à partir de sources telles qu’une base de données ou un service de gestion des fonctionnalités. Le fournisseur de fonctionnalités par défaut extrait les indicateurs de fonctionnalité du système de configuration .NET Core. Ce système prend en charge la définition de fonctionnalités dans un fichier appsettings.json ou dans des fournisseurs de configuration tels qu’Azure App Configuration. Vous pouvez personnaliser ce comportement pour contrôler où les définitions de fonctionnalités sont lues.

Pour personnaliser le chargement des définitions de fonctionnalités, vous devez implémenter l’interface IFeatureDefinitionProvider .

public interface IFeatureDefinitionProvider
{
    Task<FeatureDefinition> GetFeatureDefinitionAsync(string featureName);

    IAsyncEnumerable<FeatureDefinition> GetAllFeatureDefinitionsAsync();
}

Pour utiliser une implémentation de IFeatureDefinitionProvider, vous devez l’ajouter à la collection de services avant d’ajouter la gestion des fonctionnalités. L'exemple suivant ajoute une implémentation de IFeatureDefinitionProvider appelée InMemoryFeatureDefinitionProvider.

services.AddSingleton<IFeatureDefinitionProvider, InMemoryFeatureDefinitionProvider>()
        .AddFeatureManagement()

Étapes suivantes

Pour savoir comment utiliser des indicateurs de fonctionnalité dans vos applications, consultez les guides de démarrage rapide suivants :

ASP.NET Core

Aspirer

Application console .NET/.NET Framework

Service en arrière-plan .NET

Pour savoir comment utiliser des filtres de fonctionnalités, consultez les didacticiels suivants :

Activer des fonctionnalités conditionnelles avec des filtres de fonctionnalités

Activer des fonctionnalités selon une planification

Déployer des fonctionnalités pour des publics ciblés

  • Last updated on