Tutorial: Usar sinalizadores de recursos em um aplicativo ASP.NET Core

Artigo
02/28/2024

As bibliotecas de gerenciamento de recursos do .NET fornecem suporte idiomático para a implementação de sinalizadores de recursos em um aplicativo .NET ou ASP.NET Core. Essas bibliotecas permitem que você adicione declarativamente sinalizadores de recursos ao seu código para que você não precise escrever código manualmente para habilitar ou desabilitar recursos com if instruções.

As bibliotecas de gerenciamento de recursos também gerenciam ciclos de vida de sinalizadores de recursos nos bastidores. Por exemplo, as bibliotecas atualizam e armazenam em cache estados de sinalização, ou garantem que um estado de bandeira seja imutável durante uma chamada de solicitação. Além disso, a biblioteca ASP.NET Core oferece integrações prontas para uso, incluindo ações do controlador MVC, visualizações, rotas e middleware.

Para obter a documentação de referência da API de gerenciamento de recursos ASP.NET Core, consulte Microsoft.FeatureManagement Namespace.

Neste tutorial, vai aprender a:

Adicione sinalizadores de recursos em partes importantes do seu aplicativo para controlar a disponibilidade do recurso.
Integre com a Configuração do Aplicativo quando estiver usando-o para gerenciar sinalizadores de recursos.

Pré-requisitos

O Guia de início rápido Adicionar sinalizadores de recursos a um aplicativo ASP.NET Core mostra um exemplo simples de como usar sinalizadores de recursos em um aplicativo ASP.NET Core. Este tutorial mostra opções de configuração adicionais e recursos das bibliotecas de gerenciamento de recursos. Você pode usar o aplicativo de exemplo criado no início rápido para experimentar o código de exemplo mostrado neste tutorial.

Configurar o gerenciamento de recursos

Para acessar o gerenciador de recursos .NET, seu aplicativo deve ter referências aos Microsoft.Azure.AppConfiguration.AspNetCore pacotes NuGet e Microsoft.FeatureManagement.AspNetCore NuGet.

O gerenciador de recursos .NET é configurado a partir do sistema de configuração nativo da estrutura. Como resultado, você pode definir as configurações do sinalizador de recursos do seu aplicativo usando qualquer fonte de configuração suportada pelo .NET, incluindo o arquivo local appsettings.json ou as variáveis de ambiente.

Por padrão, o gerenciador de recursos recupera a configuração do sinalizador de recursos da "FeatureManagement" seção dos dados de configuração do .NET. Para usar o local de configuração padrão, chame o método AddFeatureManagement do IServiceCollection passado para o método ConfigureServices da classe Startup .

using Microsoft.FeatureManagement;

builder.Services.AddFeatureManagement();

Você pode especificar que a configuração de gerenciamento de recursos deve ser recuperada de uma seção de configuração diferente chamando Configuration.GetSection e passando o nome da seção desejada. O exemplo a seguir diz ao gerenciador de recursos para ler a partir de uma seção diferente chamada "MyFeatureFlags" em vez disso:

using Microsoft.FeatureManagement;

builder.Services.AddFeatureManagement(Configuration.GetSection("MyFeatureFlags"));

Se você usar filtros em seus sinalizadores de recurso, deverá incluir o namespace Microsoft.FeatureManagement.FeatureFilters e adicionar uma chamada a AddFeatureFilter especificando o nome do tipo do filtro que deseja usar como o tipo genérico do método. Para obter mais informações sobre como usar filtros de recursos para habilitar e desabilitar dinamicamente a funcionalidade, consulte Habilitar a distribuição em estágios de recursos para públicos-alvo.

O exemplo a seguir mostra como usar um filtro de recurso interno chamado PercentageFilter:

using Microsoft.FeatureManagement;

builder.Services.AddFeatureManagement()
    .AddFeatureFilter<PercentageFilter>();

Em vez de codificar os sinalizadores de recursos em seu aplicativo, recomendamos que você mantenha os sinalizadores de recursos fora do aplicativo e os gerencie separadamente. Isso permite que você modifique os estados de bandeira a qualquer momento e que essas alterações entrem em vigor no aplicativo imediatamente. O serviço de Configuração de Aplicativo do Azure fornece uma interface do usuário de portal dedicada para gerenciar todos os seus sinalizadores de recursos. O serviço de Configuração de Aplicativo do Azure também fornece os sinalizadores de recurso para seu aplicativo diretamente por meio de suas bibliotecas de cliente .NET.

A maneira mais fácil de conectar seu aplicativo ASP.NET Core à Configuração do Aplicativo é por meio do provedor de configuração incluído no Microsoft.Azure.AppConfiguration.AspNetCore pacote NuGet. Depois de incluir uma referência ao pacote, siga estas etapas para usar este pacote NuGet.

Abra Program.cs arquivo e adicione o código a seguir.

using Microsoft.Extensions.Configuration.AzureAppConfiguration;

var builder = WebApplication.CreateBuilder(args);

builder.Configuration.AddAzureAppConfiguration(options =>
    options.Connect(
        builder.Configuration["ConnectionStrings:AppConfig"])
        .UseFeatureFlags());

Atualize as configurações de middleware e serviço para seu aplicativo usando o código a seguir.

Dentro da program.cs classe, registre os serviços de Configuração de Aplicativo do Azure e o builder middleware nos objetos e app :
```
builder.Services.AddAzureAppConfiguration();

app.UseAzureAppConfiguration();
```

Em um cenário típico, você atualizará os valores do sinalizador de recursos periodicamente à medida que implanta e habilita diferentes recursos do seu aplicativo. Por padrão, os valores do sinalizador de recurso são armazenados em cache por um período de 30 segundos, portanto, uma operação de atualização acionada quando o middleware recebe uma solicitação não atualizaria o valor até que o valor armazenado em cache expire. O código a seguir mostra como alterar o tempo de expiração do cache ou o intervalo de sondagem para 5 minutos definindo o CacheExpirationInterval na chamada para UseFeatureFlags.

config.AddAzureAppConfiguration(options =>
    options.Connect(
        builder.Configuration["ConnectionStrings:AppConfig"])
            .UseFeatureFlags(featureFlagOptions => {
                featureFlagOptions.CacheExpirationInterval = TimeSpan.FromMinutes(5);
    }));

Declaração de sinalizador de recurso

Cada declaração de sinalizador de recurso tem duas partes: um nome e uma lista de um ou mais filtros que são usados para avaliar se o estado de um recurso está ativado (ou seja, quando seu valor é True). Um filtro define um critério para quando um recurso deve ser ativado.

Quando um sinalizador de recurso tem vários filtros, a lista de filtros é percorrida em ordem até que um dos filtros determine que o recurso deve ser habilitado. Nesse ponto, o sinalizador de recurso está ativado e todos os resultados restantes do filtro são ignorados. Se nenhum filtro indicar que o recurso deve ser habilitado, o sinalizador de recurso estará desativado.

O gerenciador de recursos suporta appsettings.json como uma fonte de configuração para sinalizadores de recursos. O exemplo a seguir mostra como configurar sinalizadores de recurso em um arquivo JSON:

{"FeatureManagement": {
        "FeatureA": true, // Feature flag set to on
        "FeatureB": false, // Feature flag set to off
        "FeatureC": {
            "EnabledFor": [
                {
                    "Name": "Percentage",
                    "Parameters": {
                        "Value": 50
                    }
                }
            ]
        }
    }
}

Por convenção, a FeatureManagement seção deste documento JSON é usada para configurações de sinalizador de recurso. O exemplo anterior mostra três sinalizadores de recursos com seus filtros definidos na EnabledFor propriedade:

FeatureA está ligado.
FeatureB está desligado.
FeatureC Especifica um filtro nomeado Percentage com uma Parameters propriedade. Percentage é um filtro configurável. Neste exemplo, Percentage especifica uma probabilidade de 50% para o FeatureC sinalizador estar ativado. Para obter um guia prático sobre como usar filtros de recursos, consulte Usar filtros de recursos para habilitar sinalizadores de recursos condicionais.

Use a injeção de dependência para acessar o IFeatureManager

Para algumas operações, como verificar manualmente os valores do sinalizador de recurso, você precisa obter uma instância de IFeatureManager. No ASP.NET Core MVC, você pode acessar o gerenciador IFeatureManager de recursos por meio da injeção de dependência. No exemplo a seguir, um argumento de tipo IFeatureManager é adicionado à assinatura do construtor de um controlador. O tempo de execução resolve automaticamente a referência e fornece uma implementação da interface ao chamar o construtor. Se você estiver usando um modelo de aplicativo no qual o controlador já tem um ou mais argumentos de injeção de dependência no construtor, como ILogger, você pode apenas adicionar IFeatureManager como um argumento adicional:

using Microsoft.FeatureManagement;

public class HomeController : Controller
{
    private readonly IFeatureManager _featureManager;

    public HomeController(ILogger<HomeController> logger, IFeatureManager featureManager)
    {
        _featureManager = featureManager;
    }
}

Referências de sinalizadores de recursos

Defina sinalizadores de recursos como variáveis de cadeia de caracteres para fazer referência a eles a partir do código:

public static class MyFeatureFlags
{
    public const string FeatureA = "FeatureA";
    public const string FeatureB = "FeatureB";
    public const string FeatureC = "FeatureC";
}

Verificações de sinalizadores de recursos

Um padrão comum de gerenciamento de recursos é verificar se um sinalizador de recurso está definido como ativado e, em caso afirmativo, executar uma seção de código. Por exemplo:

IFeatureManager featureManager;
...
if (await featureManager.IsEnabledAsync(MyFeatureFlags.FeatureA))
{
    // Run the following code
}

Ações do controlador

Com controladores MVC, você pode usar o FeatureGate atributo para controlar se uma classe de controlador inteira ou uma ação específica está habilitada. O controlador a seguir HomeController requer FeatureA estar ligado antes que qualquer ação contida na classe controller possa ser executada:

using Microsoft.FeatureManagement.Mvc;

[FeatureGate(MyFeatureFlags.FeatureA)]
public class HomeController : Controller
{
    ...
}

A seguinte Index ação requer FeatureA estar ativada antes de poder ser executada:

using Microsoft.FeatureManagement.Mvc;

[FeatureGate(MyFeatureFlags.FeatureA)]
public IActionResult Index()
{
    return View();
}

Quando um controlador ou ação MVC é bloqueado porque o sinalizador de recurso de controle está desativado, uma interface IDisabledFeaturesHandler registrada é chamada. A interface padrão IDisabledFeaturesHandler retorna um código de status 404 para o cliente sem corpo de resposta.

Visualizações MVC

Abra _ViewImports.cshtml no diretório Views e adicione o auxiliar de tag do gerenciador de recursos:

@addTagHelper *, Microsoft.FeatureManagement.AspNetCore

Nas exibições MVC, você pode usar uma <feature> tag para renderizar conteúdo com base em se um sinalizador de recurso está habilitado:

<feature name="FeatureA">
    <p>This can only be seen if 'FeatureA' is enabled.</p>
</feature>

Para exibir conteúdo alternativo quando os requisitos não são atendidos, o negate atributo pode ser usado.

<feature name="FeatureA" negate="true">
    <p>This will be shown if 'FeatureA' is disabled.</p>
</feature>

A tag de recurso <feature> também pode ser usada para mostrar conteúdo se algum ou todos os recursos de uma lista estiverem habilitados.

<feature name="FeatureA, FeatureB" requirement="All">
    <p>This can only be seen if 'FeatureA' and 'FeatureB' are enabled.</p>
</feature>
<feature name="FeatureA, FeatureB" requirement="Any">
    <p>This can be seen if 'FeatureA', 'FeatureB', or both are enabled.</p>
</feature>

Filtros MVC

Você pode configurar filtros MVC para que eles sejam ativados com base no estado de um sinalizador de recurso. Esse recurso é limitado a filtros que implementam IAsyncActionFilter. O código a seguir adiciona um filtro MVC chamado ThirdPartyActionFilter. Esse filtro é acionado dentro do pipeline MVC somente se FeatureA estiver habilitado.

using Microsoft.FeatureManagement.FeatureFilters;

IConfiguration Configuration { get; set;}

public void ConfigureServices(IServiceCollection services)
{
    services.AddMvc(options => {
        options.Filters.AddForFeature<ThirdPartyActionFilter>(MyFeatureFlags.FeatureA);
    });
}

Middleware

Você também pode usar sinalizadores de recursos para adicionar condicionalmente ramificações de aplicativos e middleware. O código a seguir insere um componente de middleware no pipeline de solicitação somente quando FeatureA está habilitado:

app.UseMiddlewareForFeature<ThirdPartyMiddleware>(MyFeatureFlags.FeatureA);

Esse código se baseia no recurso mais genérico de ramificar todo o aplicativo com base em um sinalizador de recurso:

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

Próximos passos

Neste tutorial, você aprendeu como implementar sinalizadores de recursos em seu aplicativo ASP.NET Core usando as Microsoft.FeatureManagement bibliotecas. Para obter mais informações sobre o suporte ao gerenciamento de recursos no ASP.NET Core e na Configuração do Aplicativo, consulte os seguintes recursos: