深度探索.NET Feature Management功能开关的魔法

前言

.NET Feature Management 是一个用于管理应用程序功能的库，它可以帮助开发人员在应用程序中轻松地添加、移除和管理功能。使用 Feature Management，开发人员可以根据不同用户、环境或其他条件来动态地控制应用程序中的功能。这使得开发人员可以更灵活地管理应用程序的功能，并根据需要快速调整和部署新功能。 Feature Management 还提供了一些方便的工具和 API，帮助开发人员更轻松地实现功能管理和控制。

安装

• .Net CLI

dotnet add package Microsoft.FeatureManagement.AspNetCore --version 4.0.0-preview2

• Package Manager

NuGet\Install-Package Microsoft.FeatureManagement.AspNetCore -Version 4.0.0-preview2

或者 Vs Nuget 包管理 管理工具安装等

依赖注入

.Net 功能管理器是通过框架的本机配置系统配置的，简单来说只要是.Net 的配置系统支持的数据源都可以用做功能管理(FeatureManagement)的配置源

.NET 中的配置是使用一个或多个配置提供程序执行的。 配置提供程序使用各种配置源从键值对读取配置数据：

• 设置文件，例如 appsettings.json
• 环境变量
• Azure Key Vault
• Azure 应用配置
• 命令行参数
• 已安装或已创建的自定义提供程序
• 目录文件
• 内存中的 .NET 对象
• 第三方提供程序

.NET 中的配置提供程序

依赖注入：

service.AddFeatureManagement();

默认情况下，功能管理器从 .NET appsettings.json配置数据的 FeatureManagement Section 来获取数据

  // Define feature flags in config file
  "FeatureManagement": {
    "sayHello": true, // On feature
    "todo": false // Off feature
  }

当然也可以自定义 Section

service.AddFeatureManagement(builder.Configuration.GetSection("CustomFeatureManagement"));

  // Define feature flags in config file
  "CustomFeatureManagement": {
    "sayHello": true, // On feature
    "todo": false // Off feature
  }

功能开关注册成 Scoped

AddFeatureManagement 方法将特性管理服务作为单例添加到应用程序中，但有些情况下可能需要将特性管理服务添加为Scoped(作用域服务)。例如，我们可能希望使用 Scoped 以获取上下文信息的功能过滤器。在这种情况下，应该使用 AddScopedFeatureManagement 方法, 这将确保功能管理服务(包括功能过滤器)被添加为 Scoped 服务。

//功能管理注册 Scoped 作用域
service.AddScopedFeatureManagement();

功能管理的基本形式是检查功能标志是否已启用，然后根据结果执行操作。这通过 IFeatureManager 的 IsEnabledAsync 方法来实现。

对我们上面的 FeatureManager 的配置来做一个验证

• sayhello 功能开关标志测试

app.MapGet("/sayHello", async Task<IResult> ([FromServices] IFeatureManager manager, string name) =>
{
    if (await manager.IsEnabledAsync("sayHello"))
    {
        return TypedResults.Ok($"hello {name}");
    }
    return TypedResults.NotFound();

}).WithSummary("sayHello");

调用接口查看一下结果，在配置中我们的sayHello设置为true

状态码为 200，返回信息"hello Ruipeng"，符合预期，功能开启正常。

• todo 功能开关标志测试

app.MapGet("/todo", async Task<IResult> ([FromServices] IFeatureManager manager) =>
{
    if (await manager.IsEnabledAsync("todo"))
    {
        return TypedResults.Ok($"todo is enabled !");
    }
    return TypedResults.NotFound();

}).WithSummary("todo");

调用接口查看一下结果，状态码 404，返回信息 Not Found，符合预期，功能未开启。

上面的示例简单讲解了一下功能开关的使用，接下来深入了解功能开关的配置

功能开关的定义

功能开关的标志由两部分组成：名称和用于启用功能的过滤器列表。

功能过滤器(Feature filters)定义了功能应何时启用的场景。在评估特性是开启还是关闭时，会遍历其功能过滤器列表，直到其中一个过滤器决定启用该特性。如果一个过滤器都没有标识改功能应该开启，那此功能标志是关闭的状态。

内置过滤器

• AlwaysOn: 总是开启
• PercentageFilter：根据百分比随机启用/禁用功能。这个过滤器允许您基于一个百分比值来决定功能被启用的概率，提供了一种简单而灵活的机制来控制特性的曝光范围。
• TimeWindowFilter：在预定义的时间窗口内启用特性。这个过滤器允许您指定特性的开始和结束时间，确保特性只在特定的时间段内可用。这对于限时活动或测试场景非常有用。
• TargetingFilter：（这个主要是在Azure 用为目标受众启用功能的分阶段推出针对特定用户或用户组启用特性。这个过滤器允许您根据用户属性或标识来启用特性，例如基于用户 ID、角色、地区等。此外，对于此过滤器，您还可以设置一个百分比值，以进一步控制特性在目标用户中的启用概率。

详细信息可以参考注册功能筛选器 Docs

过滤器的配置指南

需要注意的是在功能标志名称中禁止使用冒号:,这是为了遵循一定的命名规范，避免与现有的或未来的功能管理系统产生冲突或造成解析错误。在定义功能标志名称时，请确保使用合法和合适的字符组合，以确保系统的稳定性和可维护性。

功能使用 EnabledFor 属性来定义它们的功能过滤器

---

AlwaysOn 过滤器

  // Define feature flags in config file
  "FeatureManagement": {
    //始终启用该功能
    "featureAlwaysOn": {
      "EnabledFor": [
        {
          "Name": "AlwaysOn"
        }
      ]
    }
  }

app.MapGet("/featureAlwaysOn", async Task<IResult> (IFeatureManager manager) =>
{
    if (await manager.IsEnabledAsync("featureAlwaysOn"))
    {
        return TypedResults.Ok($"featureAlwaysOn is enabled !");
    }
    return TypedResults.NotFound();
}).WithSummary("featureAlwaysOn");

调用接口查看测试结果,返回 200，符合预期

---

TimeWindow 过滤器

  "FeatureManagement": {
    "featureTimeWindow": {
      "EnabledFor": [
        {
          "Name": "TimeWindow",
          "Parameters": {
            "Start": "2024-03-26 13:30:00",
            "End": "2024-03-27 13:30:00"
          }
        }
      ]
    }
  }

指定了一个名为 TimeWindow 的功能过滤器。这是一个可配置的功能过滤，具有 Parameters 属性，配置了功能活动的开始和结束时间 。

app.MapGet("/featureTimeWindow", async Task<IResult> (IFeatureManager manager) =>
{
    if (await manager.IsEnabledAsync("featureTimeWindow"))
    {
        return TypedResults.Ok($"featureTimeWindow is enabled !");
    }
    return TypedResults.NotFound();
}).WithSummary("TimeWindow 过滤器测试");

调用接口测试:返回 200 符合预期

---

Percentage 过滤器

百分比过滤器（Percentage Filter）它根据指定的百分比值随机启用或禁用某个特性。这种过滤器允许您控制特性的曝光率，以便在不同的用户群体中测试特性的效果，或者在逐步推广新特性时控制其影响范围。

  "FeatureManagement": {
    "featurePercentage": {
      "EnabledFor": [
        {
          "Name": "Percentage",
          "Parameters": {
            "Value": "50"
          }
        }
      ]
    }
  },

app.MapGet("/featurePercentage", async Task<IResult> (IFeatureManager manager) =>
{
    if (await manager.IsEnabledAsync("featurePercentage"))
    {
        return TypedResults.Ok($"featurePercentage is enabled !");
    }
    return TypedResults.NotFound();
}).WithSummary("Percentage 过滤器测试");

连续测两次

第一次测试结果: 返回 200

第二次测试结果：返回 404

通过测试结果可以看出有百分之五十的几率成功，符合预期。

RequirementType

功能标志的 RequirementType 属性用于确定在评估功能状态时，过滤器应该使用任何（Any）还是全部（All）逻辑。如果未指定 RequirementType，则默认值为 Any。

• Any 表示只需一个过滤器评估为 true，特性就会被启用。
• All 表示每个过滤器都必须评估为 true，特性才会被启用。
  
  RequirementType 为 All 会改变遍历方式。首先，如果没有过滤器，则功能将被禁用。然后，遍历特性过滤器，直到其中一个过滤器决定应将功能禁用。如果没有过滤器指示应禁用功能，则该功能将被视为已启用。

  "FeatureManagement": {
    "featureRequirementTypeAll": {
      "RequirementType": "All",
      "EnabledFor": [
        {
          "Name": "TimeWindow",
          "Parameters": {
            "Start": "2024-03-27 13:00:00",
            "End": "2024-05-01 13:00:00"
          }
        },
        {
          "Name": "Percentage",
          "Parameters": {
            "Value": "50"
          }
        }
      ]
    }
  },

app.MapGet("/featureRequirementTypeAll", async Task<IResult> (IFeatureManager manager) =>
{
    if (await manager.IsEnabledAsync("featureRequirementTypeAll"))
    {
        return TypedResults.Ok($"featureRequirementTypeAll is enabled !");
    }
    return TypedResults.NotFound();
}).WithSummary("RequirementTypeAll 多过滤器测试");

上面的实例设置为 all 之后此功能标志的过滤器列表必须全部符合要求才能调用成功。

比如上面我设置的开始日期是2024-03-27 13:00:00当前时间小于这个日期

无论调用几次还是还是 404，结果符合我们的预期。

自定义过滤器

要实现一个功能过滤器，必须要实现的是一个IFeatureFilter接口,接口包含了一个EvaluateAsync的方法。当功能标志指定启用该过滤器时，将调用 EvaluateAsync方法,如果方法返回的是true,则表示应该启用功能。

定义一个中间件接口只对某个用户组做开放，这个场景在 C 端的产品上比较常见，比如说部分功能的内测。

[FilterAlias("AuthenticatedGroup")]
public class AuthenticatedGroupFilter : IFeatureFilter, IFeatureFilterMetadata, IFilterParametersBinder
{
    public object BindParameters(IConfiguration parameters)
    {
        return parameters.Get<GroupSetting>() ?? new GroupSetting();
    }

    public Task<bool> EvaluateAsync(FeatureFilterEvaluationContext featureFilterContext)
    {
        GroupSetting filterSettings = ((GroupSetting)featureFilterContext.Settings) ?? ((GroupSetting)BindParameters(featureFilterContext.Parameters));
        // 假设您有一个方法来检查用户是否已通过身份验证
        // 例如，这可能是一个从身份验证服务或中间件中获得的属性或方法
        bool isAuthenticated = IsGroupAuthenticated(filterSettings);
        return Task.FromResult(isAuthenticated);
    }

    private bool IsGroupAuthenticated(GroupSetting groupSetting)
    {
        // 在这里编写您的身份验证检查逻辑
        // 这可能涉及到检查HTTP请求的上下文、会话状态、令牌等
        // 具体的实现将取决于您使用的身份验证机制

        // 示例：返回一个硬编码的值，表示用户是否已通过身份验证
        // 在实际应用中，您应该实现实际的检查逻辑
        return true; // 或者 false，取决于用户是否已通过身份验证
    }
}

FilterAlias是定义过滤器的别名，我们在配置文件中指定时需要用别名，IFeatureFilter接口返回的信息决定功能是否启用，IFeatureFilterMetadata是一个空的标记接口，用于评估功能状态的特征过滤器的标记接口，IFilterParametersBinder 接口用于参数绑定。

• json 配置

  "FeatureManagement": {
    "featureAuthencatedGroup": {
      "EnabledFor": [
        {
          "Name": "AuthenticatedGroup",
          "Parameters": {
            "Groups": [ "AdminGroup", "GroupOne" ]
          }
        }
      ]
    }
  }

• 依赖注入

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

调用 AddFeatureFilter 方法可把自定义的过滤器注册到功能管理器中。

app.MapGet("/featureAuthencatedGroup", async Task<IResult> (IFeatureManager manager) =>
{
    if (await manager.IsEnabledAsync("featureAuthencatedGroup"))
    {
        return TypedResults.Ok($"featureAuthencatedGroup is enabled !");
    }
    return TypedResults.NotFound();
}).WithSummary("AuthencatedGroup 自定义过滤器测试");

测试一下,返回 200 ，符合预期

一个小 tips；如果多个过滤器有同一个别名是，可以用命名空间加别名的方式来定义唯一一个过滤器，例如，Microsoft.Percentage 是一个完全限定的别名，它明确指出了 Percentage过滤器位于 Microsoft 命名空间下

自定义开启中间件

  "FeatureManagement": {
    "featureMiddleWare": {
      "EnabledFor": [
        {
          "Name": "Percentage",
          "Parameters": {
            "Value": "50"
          }
        }
      ]
    }
  }

自定义中间件

public class FeatureMiddleWare(RequestDelegate next)
{
    public async Task Invoke(HttpContext context)
    {
        Console.WriteLine("FeatureMiddleWare管道执行之前~");
        await next(context);
        Console.WriteLine("FeatureMiddleWare管道执行之后~");
    }
}

添加扩展方法

//测试中间件的功能开启
app.UseMiddlewareForFeature<FeatureMiddleWare>("featureMiddleWare");

随便调用一个接口测试一下,可以看到管道根据百分比触发成功

通过上述调用，应用程序添加了一个中间件组件，只有在特性“featureMiddleWare”被启用时才会出现在请求管道中。如果在运行时启用/禁用特性，中间件管道可以动态更改。

这是建立在基于特性对整个应用程序进行分支的更通用能力之上。

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

MinimalApis 集成

在我们的 MVC 或者 Razor Pages 中有如下方案来启用工农的开关，不过多介绍大家可以官方浏览学习。

FeatureManagement-Dotnet

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

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

在 MinimalAps 中可以利用 endpoint filter来简化公功能的开关，

• 第一步创建最小 Api 的基类，所有的 MinimalApis 过滤器都要继承它

public abstract class FeatureFlagEndpointFilter(IFeatureManager featureManager) : IEndpointFilter
{
    protected abstract string FeatureFlag { get; }

    private readonly IFeatureManager _featureManager = featureManager;

    public async ValueTask<object?> InvokeAsync(EndpointFilterInvocationContext context,
        EndpointFilterDelegate next)
    {
        var isEnabled = await _featureManager.IsEnabledAsync(FeatureFlag);
        if (!isEnabled)
        {
            return TypedResults.NotFound();
        }
        return await next(context);
    }
}

• 定义目标 Json 配置

  "FeatureManagement": {
    "featureUserApi": {
      "EnabledFor": [
        {
          "Name": "Percentage",
          "Parameters": {
            "Value": "50"
          }
        }
      ]
    }

• 定义最小 Api 过滤器

public class UserApiFeatureFilter(IFeatureManager featureManager) : FeatureFlagEndpointFilter(featureManager)
{
    protected override string FeatureFlag => "featureUserApi";
}

• 定义 Api 接口测试

//最小Api分组功能添加
{
    var userGroup = app.MapGroup("User").WithTags("User").AddEndpointFilter<UserApiFeatureFilter>(); ;

    userGroup.MapGet("/featureUserApi", IResult (IFeatureManager manager) =>
    {
        return TypedResults.Ok($"featureUserApi is enabled !");

    }).WithSummary("featureUserApi 最小Api过滤器测试");
}

调用测试，可以看出我们配置的百分比过滤器成功。

通过对 IEndpointFilter 的封装借助最小 Api 的 MapGroup 可以对一组相关的 Api 进行功能管理，简化了我们一个个 Api 注册。

最后

在本文中，我们深入探讨了.NET Feature Management 库的安装、配置和使用方法，以及如何利用功能开关来动态管理应用程序的功能。以下是关键点的总结和提炼：

• 安装与依赖注入：通过.NET CLI 或 NuGet Package Manager 安装等方式 Microsoft.FeatureManagement.AspNetCore 库，并在应用程序中添加功能管理服务的依赖注入。

• 功能定义与配置：通过.NET 的配置系统，在 appsettings.json 中定义功能标志，指定功能的启用和禁用状态，以及可选的功能过滤器配置。

• 自定义功能过滤器：实现 IFeatureFilter 接口来定义自定义功能过滤器，根据特定条件决定功能是否启用，例如基于用户组、时间窗口或百分比等条件。

• 功能开关的使用：利用 IFeatureManager 的 IsEnabledAsync 方法检查功能是否启用，根据不同的功能状态执行相应的逻辑，实现功能的动态控制。

• RequirementType 设置：可以通过 RequirementType 属性指定功能过滤器的逻辑要求，是 Any 还是 All，决定多个过滤器的组合逻辑。

• 自定义中间件的动态切换：通过自定义功能过滤器和中间件，可以根据功能状态动态调整请求管道，实现功能开关对中间件的控制。

• 最小 API 集成：在 Minimal APIs 中，利用 IEndpointFilter 接口来简化功能开关的应用，将功能管理应用到最小 API 的端点上，实现对一组相关 API 的功能管理。

通过以上总结和提炼，您可以更好地了解和应用.NET Feature Management 库，实现灵活的功能管理和动态控制应用程序的功能。

有条件的富哥可以体验一下在 Azure 应用程序配置中管理功能标志

更多详细的内容请浏览FeatureManagement-Dotnet

本文测试完整源代码