Tutorial: executar experimentos com sinalizadores de recursos variantes (versão prévia)

Artigo
05/21/2024

A execução de experimentos em seu aplicativo pode ajudar você a tomar decisões informadas para melhorar o desempenho e a experiência do usuário do aplicativo. Neste guia, você aprenderá a configurar e executar experimentos em um repositório de Configuração de Aplicativos. Você aprenderá a coletar e medir dados, usando os recursos de Configuração de Aplicativos, Application Insights (versão prévia) e Espaço de Trabalho de Experimentação Dividida (versão prévia).

Ao fazer isso, você pode tomar decisões controladas por dados para melhorar seu aplicativo.

Observação

Uma forma rápida de iniciar sua jornada de experimentação é executar a amostra de Citação do Dia do AZD. Esse repositório mostra um exemplo completo, com o provisionamento de recursos do Azure e um primeiro experimento, de como integrar a Configuração de Aplicativos do Azure aos seus aplicativos .NET para executar experimentos.

Neste tutorial, você:

Crie um sinalizador de recurso variante
Adicionar um recurso do Application Insights ao seu repositório
Adicionar um Espaço de Trabalho de Experimentação Dividida ao seu repositório
Configurar um aplicativo para executar um experimento
Habilitar a telemetria e criar um experimento no sinalizador de recurso variante
Criar métricas para o experimento
Obter resultados de experimentação

Pré-requisitos

Uma assinatura do Azure. Caso não tenha uma, crie uma gratuitamente.
Um repositório de Configuração de Aplicativos.
Um Espaço de Trabalho de Experimentação Dividida.
Um recurso do Application Insights baseado em espaço de trabalho.

Criar um sinalizadorvde recurso variante (versão prévia)

Crie um sinalizador de recurso variante chamado Greeting com duas variantes, Desativado e Ativada, conforme descrito no início rápido do Sinalizador de Recurso.

Conectar um recurso do Application Insights (versão prévia) ao repositório de configuração

Para executar um experimento, primeiro você precisa conectar um recurso do Application Insights baseado em espaço de trabalho ao repositório de Configuração de Aplicativos. Conectar esse recurso ao repositório de Configuração de Aplicativos define o repositório de configuração com a fonte de telemetria para a experimentação.

No repositório de Configuração de Aplicativos, selecione Telemetria > Application Insights (versão prévia).
Selecione o recurso do Application Insights que você deseja usar como provedor de telemetria para seus sinalizadores de recurso e aplicativo variantes e selecione Salvar. Se você não tiver um recurso do Application Insights, crie um selecionando Criar. Para obter mais informações sobre como continuar, acesse Criar um recurso baseado em espaço de trabalho. Em seguida, volte ao Application Insights (versão prévia), recarregue a lista de recursos disponíveis do Application Insights e selecione seu novo recurso do Application Insights.
Uma notificação indica que o recurso do Application Insights foi atualizado com sucesso para o repositório de Configuração de Aplicativos.

Conectar um Espaço de Trabalho de Experimentação Dividida (versão prévia) ao seu repositório

Para executar experimentos na Configuração de Aplicativos do Azure, você usará o Espaço de trabalho de Experimentação Dividida. Siga as etapas abaixo para conectar um Espaço de Trabalho de Experimentação Dividida ao seu repositório.

No repositório de Configuração de Aplicativos, selecione Experimentação>Espaço de Trabalho de Experimentação Dividida (versão prévia) no menu à esquerda.
Selecione um Espaço de Trabalho de Experimentação Dividida e clique em Salvar. Se você não tiver um Espaço de Trabalho de Experimentação Dividida, siga o início rápido do Espaço de Trabalho de Experimentação Dividida para criar um.

Observação

A fonte de dados selecionada no Espaço de Trabalho de Experimentação Dividida deve ser o mesmo recurso do Application Insights selecionado na etapa anterior.
Uma notificação indica que a operação foi bem-sucedida.

Configurar um aplicativo para executar um experimento

Agora que você conectou o recurso Application Insights (versão prévia) ao repositório de Configuração de Aplicativos, configure um aplicativo para executar o experimento (versão prévia).

Neste exemplo, você criará um aplicativo Web ASP.NET chamado Quote of the Day. Quando o aplicativo é carregado, ele exibe uma frase. Os usuários podem selecionar o botão de coração para curtir. Para melhorar o envolvimento do usuário, você quer explorar se uma mensagem de saudação personalizada aumentará o número de usuários que curtem a frase. Você cria o sinalizador de recurso Greeting na Configuração de Aplicativos do Azure com duas variantes, Desativado e Ativado. Os usuários que recebem a variante Desativado verão um título padrão. Os usuários que receberem a variante Ativado receberão uma mensagem de saudação. Você coleta e salva a telemetria das interações do usuário no Application Insights. Com o Espaço de Trabalho de Experimentação Dividida, você pode analisar a eficácia do experimento.

Criar um aplicativo e adicionar segredos do usuário

Abra um prompt de comando e execute o seguinte código. Isso cria um novo aplicativo Razor Pages no ASP.NET Core, usando autenticação de conta individual e o coloca em uma pasta de saída chamada QuoteOfTheDay.
```
dotnet new razor --auth Individual -o QuoteOfTheDay
```
No prompt de comando, navegue até a pasta QuoteOfTheDay e execute o comando a seguir para criar um segredo do usuário para o aplicativo. Esse segredo armazena a cadeia de conexão da Configuração de Aplicativos.
```
dotnet user-secrets set ConnectionStrings:AppConfiguration "<App Configuration Connection string>"
```

Crie outro segredo do usuário que contém a cadeia de conexão do Application Insights.

dotnet user-secrets set ConnectionStrings:AppInsights "<Application Insights Connection string>"

Atualize o código do aplicativo

Em QuoteOfTheDay.csproj, adicione as versões prévias mais recentes dos SDKs de Gerenciamento de Recursos e Configuração de Aplicativos como pacotes obrigatórios.

<PackageReference Include="Microsoft.Azure.AppConfiguration.AspNetCore" Version="8.0.0-preview.2" />
<PackageReference Include="Microsoft.FeatureManagement.Telemetry.ApplicationInsights" Version="4.0.0-preview3" />
<PackageReference Include="Microsoft.FeatureManagement.Telemetry.ApplicationInsights.AspNetCore" Version="4.0.0-preview3" />
<PackageReference Include="Microsoft.FeatureManagement.AspNetCore" Version="4.0.0-preview3" />

Em Program.cs, na linha var builder = WebApplication.CreateBuilder(args);, adicione o provedor de Configuração de Aplicativos, que efetua pull da configuração do Azure quando o aplicativo for iniciado. Por padrão, o método UseFeatureFlags inclui todos os sinalizadores de recursos sem rótulo e define um tempo de expiração de cache de 30 segundos.
```
builder.Configuration
    .AddAzureAppConfiguration(o =>
    {
        o.Connect(builder.Configuration.GetConnectionString("AppConfiguration"));

        o.UseFeatureFlags();
    });
```

Em Program.cs, adicione as seguintes instruções using:

using Microsoft.ApplicationInsights.AspNetCore.Extensions;
using Microsoft.ApplicationInsights.Extensibility;
using Microsoft.FeatureManagement.Telemetry.ApplicationInsights.AspNetCore;

No local em que builder.Configuration.AddAzureAppConfiguration é chamado, adicione:
```
// Add Application Insights telemetry.
builder.Services.AddApplicationInsightsTelemetry(
    new ApplicationInsightsServiceOptions
    {
        ConnectionString = builder.Configuration.GetConnectionString("AppInsights"),
        EnableAdaptiveSampling = false
    })
    .AddSingleton<ITelemetryInitializer, TargetingTelemetryInitializer>();
```
Esse snippet de código executa as ações a seguir.
- Adiciona um cliente de telemetria do Application Insights ao aplicativo.
- Adiciona um inicializador de telemetria que acrescenta informações de direcionamento à telemetria de saída.
- Desabilita a amostragem adaptável. Para obter mais informações sobre como desabilitar a amostragem adaptável, acesse Solução de problemas.

Na pasta raiz QuoteOfTheDay, crie um novo arquivo chamado ExampleTargetingContextAccessor.cs. Isso cria uma nova classe chamada ExampleTargetingContextAccessor. Cole o conteúdo abaixo no arquivo.

using Microsoft.FeatureManagement.FeatureFilters;

namespace QuoteOfTheDay
{
    public class ExampleTargetingContextAccessor : ITargetingContextAccessor
    {
        private const string TargetingContextLookup = "ExampleTargetingContextAccessor.TargetingContext";
        private readonly IHttpContextAccessor _httpContextAccessor;

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

        public ValueTask<TargetingContext> GetContextAsync()
        {
            HttpContext httpContext = _httpContextAccessor.HttpContext;
            if (httpContext.Items.TryGetValue(TargetingContextLookup, out object value))
            {
                return new ValueTask<TargetingContext>((TargetingContext)value);
            }
            List<string> groups = new List<string>();
            if (httpContext.User.Identity.Name != null)
            {
                groups.Add(httpContext.User.Identity.Name.Split("@", StringSplitOptions.None)[1]);
            }
            TargetingContext targetingContext = new TargetingContext
            {
                UserId = httpContext.User.Identity.Name ?? "guest",
                Groups = groups
            };
            httpContext.Items[TargetingContextLookup] = targetingContext;
            return new ValueTask<TargetingContext>(targetingContext);
        }
    }
}

Essa classe declara como o direcionamento do FeatureManagement obtém o contexto de um usuário. Nesse caso, ele lê httpContext.User.Identity.Name para UserId e trata o domínio do endereço de email como um Group.

Volta para Program.cs e adicione as seguintes instruções using.

using Microsoft.FeatureManagement.Telemetry;
using Microsoft.FeatureManagement;
using QuoteOfTheDay;

No local em que AddApplicationInsightsTelemetry foi chamado, adicione serviços para lidar com a Atualização de Configuração de Aplicativos, configure o Gerenciamento de Recursos, configure o Direcionamento de Gerenciamento de Recursos e habilite o Gerenciamento de Recursos para publicar eventos de telemetria.

builder.Services.AddHttpContextAccessor();

// Add Azure App Configuration and feature management services to the container.
builder.Services.AddAzureAppConfiguration()
    .AddFeatureManagement()
    .WithTargeting<ExampleTargetingContextAccessor>()
    .AddTelemetryPublisher<ApplicationInsightsTelemetryPublisher>();

Abaixo da linha var app = builder.Build();, adicione um middleware que dispara a atualização da Configuração de Aplicativos quando apropriado.
```
// Use Azure App Configuration middleware for dynamic configuration refresh.
app.UseAzureAppConfiguration();
```
Nesse caso, adicione o código a seguir para habilitar o TargetingTelemetryInitializer para ter acesso às informações de direcionamento armazenando-as no HttpContext.
```
// Add TargetingId to HttpContext for telemetry
app.UseMiddleware<TargetingHttpContextMiddleware>();
```
Em QuoteOfTheDay>Páginas>Compartilhado>_Layout.cshtml, em que QuoteOfTheDay.styles.css é adicionado, adicione a linha a seguir para adicionar o css para a versão 5.15.3 de font-awesome.
```
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.3/css/all.min.css">
```

Abra QuoteOfTheDay>Páginas>Index.cshtml.cs e substitua o conteúdo para o aplicativo de frase.

using Microsoft.ApplicationInsights;
using Microsoft.AspNetCore.Mvc;
using Microsoft.AspNetCore.Mvc.RazorPages;
using Microsoft.FeatureManagement;

namespace QuoteOfTheDay.Pages;

public class Quote
{
    public string Message { get; set; }

    public string Author { get; set; }
}

public class IndexModel(IVariantFeatureManagerSnapshot featureManager, TelemetryClient telemetryClient) : PageModel
{
    private readonly IVariantFeatureManagerSnapshot _featureManager = featureManager;
    private readonly TelemetryClient _telemetryClient = telemetryClient;

    private Quote[] _quotes = [
        new Quote()
        {
            Message = "You cannot change what you are, only what you do.",
            Author = "Philip Pullman"
        }];

    public Quote? Quote { get; set; }

    public bool ShowGreeting { get; set; }

    public async void OnGet()
    {
        Quote = _quotes[new Random().Next(_quotes.Length)];

        Variant variant = await _featureManager.GetVariantAsync("Greeting", HttpContext.RequestAborted);

        ShowGreeting = variant.Configuration.Get<bool>();
    }

    public IActionResult OnPostHeartQuoteAsync()
    {
        string? userId = User.Identity?.Name;

        if (!string.IsNullOrEmpty(userId))
        {
            // Send telemetry to Application Insights
            _telemetryClient.TrackEvent("Like");

            return new JsonResult(new { success = true });
        }
        else
        {
            return new JsonResult(new { success = false, error = "User not authenticated" });
        }
    }
}

Esse PageModel escolhe uma frase aleatória, usa GetVariantAsync para obter a variante do usuário atual e define uma variável chamada "ShowGreeting" como o valor da variante. O PageModel também manipula solicitações Post, chamando _telemetryClient.TrackEvent("Like");, que envia um evento ao Application Insights com o nome Curtir. Esse evento é automaticamente vinculado ao usuário e à variante e pode ser acompanhado por métricas.

Abra index.cshtml e substitua o conteúdo do aplicativo de frase.

@page
@model IndexModel
@{
    ViewData["Title"] = "Home page";
    ViewData["Username"] = User.Identity.Name;
}

<style>
    body {
        font-family: Arial, sans-serif;
        background-color: #f4f4f4;
        color: #333;
    }

    .quote-container {
        background-color: #fff;
        margin: 2em auto;
        padding: 2em;
        border-radius: 8px;
        max-width: 750px;
        box-shadow: 0px 4px 8px rgba(0, 0, 0, 0.2);
        display: flex;
        justify-content: space-between;
        align-items: start;
        position: relative;
    }

    .vote-container {
        position: absolute;
        top: 10px;
        right: 10px;
        display: flex;
        gap: 0em;
    }

    .vote-container .btn {
        background-color: #ffffff; /* White background */
        border-color: #ffffff; /* Light blue border */
        color: #333
    }

    .vote-container .btn:focus {
        outline: none;
        box-shadow: none;
    }

    .vote-container .btn:hover {
        background-color: #F0F0F0; /* Light gray background */
    }

    .greeting-content {
        font-family: 'Georgia', serif; /* More artistic font */
    }

    .quote-content p.quote {
        font-size: 2em; /* Bigger font size */
        font-family: 'Georgia', serif; /* More artistic font */
        font-style: italic; /* Italic font */
        color: #4EC2F7; /* Medium-light blue color */
    }
</style>

<div class="quote-container">
    <div class="quote-content">
        @if (Model.ShowGreeting)
        {
            <h3 class="greeting-content">Hi <b>@User.Identity.Name</b>, hope this makes your day!</h3>
        }
        else
        {
            <h3 class="greeting-content">Quote of the day</h3>
        }
        <br />
        <p class="quote">“@Model.Quote.Message”</p>
        <p>- <b>@Model.Quote.Author</b></p>
    </div>

    <div class="vote-container">
        <button class="btn btn-primary" onclick="heartClicked(this)">
            <i class="far fa-heart"></i> <!-- Heart icon -->
        </button>
    </div>

    <form action="/" method="post">
        @Html.AntiForgeryToken()
    </form>
</div>

<script>
    function heartClicked(button) {
        var icon = button.querySelector('i');
        icon.classList.toggle('far');
        icon.classList.toggle('fas');

        // If the quote is hearted
        if (icon.classList.contains('fas')) {
            // Send a request to the server to save the vote
            fetch('/Index?handler=HeartQuote', {
                method: 'POST',
                headers: {
                    'Content-Type': 'application/json',
                    'RequestVerificationToken': document.querySelector('input[name="__RequestVerificationToken"]').value
                }
            });
        }
    }
</script>

Esse código corresponde à interface do usuário para mostrar o QuoteOfTheDay e manipular o uso da ação do coração em uma frase. Ele usa o valor de Model.ShowGreeting mencionado anteriormente para mostrar coisas diferentes para usuários diferentes, dependendo da sua variante.

Compilar e executar o aplicativo

No prompt de comando, na pasta QuoteOfTheDay, execute: dotnet build.
Execute: dotnet run --launch-profile https.
Procure uma mensagem no formato Now listening on: https://localhost:{port} na saída do aplicativo. Navegue até o link incluído no navegador.
Depois de exibir o aplicativo em execução, selecione Registrar na parte superior direita para registrar um novo usuário.
Registrar um novo usuário chamado user@contoso.com. A senha deve ter pelo menos seis caracteres e conter um número e um caractere especial.
Selecione o link Clique aqui para validar o email depois de inserir as informações do usuário.
Registre um segundo usuário chamado userb@contoso.com, insira outra senha e valide este segundo email.

Observação

É importante para a finalidade deste tutorial usar exatamente esses nomes. Desde que o recurso tenha sido configurado conforme o esperado, os dois usuários devem ver variantes diferentes.
Selecione Logon no canto superior direito para entrar como userb (userb@contoso.com).
Depois de fazer logon, você deverá ver que userb@contoso.com vê uma mensagem especial ao exibir o aplicativo.

userb@contoso.com é o único usuário que vê a mensagem especial.

Habilitar a telemetria e criar um experimento no sinalizador de recurso variante

Habilitar a telemetria e criar um experimento no sinalizador de recurso variante seguindo as etapas a seguir:

No repositório de Configuração de Aplicativos, vá para Operação>Gerenciador de recurso.
Selecione o menu de contexto ... à direita de um sinalizador de recurso variante "Greeting" e selecione Editar.
Vá para a guia Telemetria e marque a caixa Habilitar Telemetria.
Vá para a guia Experimento, marque a caixa Criar Experimento e dê um nome ao experimento.
Selecione Examinar + atualizar e depois Atualizar.
Uma notificação indica que a operação foi bem-sucedida. Em Gerenciador de Recursos, o sinalizador de recurso variante deve ter a palavra Ativar em Experimento.

Criar métricas para o experimento

Uma métrica no Espaço de Trabalho de Experimentação Dividida é uma medida quantitativa de um evento enviado ao Application Insights. Essa métrica ajuda a avaliar o impacto de um sinalizador de recurso nos resultados e comportamento do usuário.

Ao atualizar seu aplicativo anteriormente, você adicionou _telemetryClient.TrackEvent("Like") ao código do aplicativo. Like é um evento de telemetria que representa uma ação do usuário, nesse caso, a seleção do botão de Coração. Esse evento é enviado para o recurso Application Insights, que conectará à métrica que você está prestes a criar. O aplicativo que criamos especifica apenas um evento, mas você pode ter vários eventos e, posteriormente, várias métricas. Várias métricas também podem ser baseadas em um único evento do Application Insights.

Acesso seu recurso do Espaço de Trabalho de Experimentação Dividida. Em Configuração>Métricas de Experimentação, selecione Criar.

Selecione ou insira as informações a seguir em Criar uma Métrica de Experimentação e salve com Criar.

Captura de tela do portal do Azure, criando uma métrica de experimentação.

Configuração	Valor de exemplo	Descrição
Nome	Voto de Curtida	O nome da métrica de experimentação.
Descrição	Número de pessoas que selecionam o botão de coração quando veem uma mensagem especial, versus quando não o fazem.	Descrição opcional da métrica.
Nome de evento do Application Insights	Like	O nome do evento do Application Insights. Esse nome diferencia maiúsculas de minúsculas e é o nome especificado em seu código com `_telemetryClient.TrackEvent("<Event-Name>")`.
Medir como	Count	As seguintes opções estão disponíveis: Contagem: conta o número de vezes que o evento é disparado pelos usuários. Média: calcula a média do valor do evento para seus usuários. Soma: soma os valores do evento para seus usuários. Mostra o valor somado médio. Porcentagem: calcula o percentual de usuários que dispararam o evento.
Impacto Desejado	Aumentar	Essa configuração representa a meta final ou a finalidade por trás da medição da métrica criada.

Neste tutorial, nossa hipótese é que mais usuários cliquem no botão em forma de coração quando houver uma mensagem especial ao lado de Quote of the Day. O código do aplicativo acompanha esse clique como um evento chamado Curtir. O aplicativo envia o evento Curtir como telemetria para o Application Insights e o Impacto Desejado para este experimento é ver um Aumento no número de cliques do usuário (medido como Contagem) no Voto de Curtida, para ser capaz de validar a hipótese fornecida. Se houver uma diminuição no número de cliques no botão, apesar da mensagem especial ser mostrada ao público alocado, a hipótese será invalidada para este experimento.

Depois de criada, a nova métrica é exibida no portal. Você pode editá-la ou excluí-la selecionando o menu de contexto (...) no lado direito da tela.

Obter resultados de experimentação

Para colocar seu experimento de configuração recentemente à prova e gerar resultados para você analisar, simule um pouco de tráfego para seu aplicativo e aguarde de 10 a 15 minutos.

Para ver os resultados do experimento, acesse Gerenciador de Recursos e, na lista de sinalizadores de recursos variantes, clique em …>Experimento ou selecione o link Ativo na coluna Experimento. Essa coluna não é exibida por padrão. Para mostrá-la, no Gerenciador de Recursos, selecione Gerenciar exibição>Editar Colunas>Adicionar Coluna>Experimento e Aplicar.

Na página de resultados, uma Versão do Experimento, uma Linha de base para comparar os resultados e uma variante de Comparação são selecionadas por padrão. Se necessário, altere os padrões de acordo com seu gosto e selecione Aplicar para ver o resultado do experimento.

A captura de tela acima mostra que o experimento teve o resultado desejado, com a variante Ativado para o Voto de Curtida resultando em 560,62% mais votos de curtida do que a variante Desativado.

Qualquer edição em um sinalizador de recurso variante gera uma nova versão da experimentação, que você pode selecionar para exibir seus resultados.

Observação

Para obter resultados de experimentação, você precisa de pelo menos 30 eventos por variante, mas sugerimos que você tenha mais que o tamanho mínimo de amostragem para garantir que sua experimentação esteja produzindo resultados confiáveis.

Observação

A amostragem do Application Insights é habilitada por padrão e pode afetar os resultados da experimentação. Para este tutorial, é recomendável desativar a amostragem no Application Insights. Saiba mais sobre Amostragem no Application Insights.

Próxima etapa

Experimentação

Compartilhar via

Tutorial: executar experimentos com sinalizadores de recursos variantes (versão prévia)

Pré-requisitos

Criar um sinalizadorvde recurso variante (versão prévia)

Conectar um recurso do Application Insights (versão prévia) ao repositório de configuração

Conectar um Espaço de Trabalho de Experimentação Dividida (versão prévia) ao seu repositório

Configurar um aplicativo para executar um experimento

Criar um aplicativo e adicionar segredos do usuário

Atualize o código do aplicativo

Compilar e executar o aplicativo

Habilitar a telemetria e criar um experimento no sinalizador de recurso variante

Criar métricas para o experimento

Obter resultados de experimentação

Próxima etapa

Comentários

Comentários

Recursos adicionais