Criar um plugin personalizado

De relance
Objetivo: Constrói um plugin de Proxy de Desenvolvimento personalizado
Tempo: 30 minutos
Plugins: Plugin personalizado
Pré-requisitos: Configurar Dev Proxy, .NET 10 SDK

Neste artigo, você aprenderá a criar um plug-in personalizado para o Dev Proxy. Ao criar plugins para o Dev Proxy, você pode estender sua funcionalidade e adicionar recursos personalizados para atender às suas necessidades.

Plugins HTTP vs. Plugins stdio

O Dev Proxy suporta dois tipos de plugins dependendo do tráfego que pretende interceptar:

  • Os plugins HTTP intercetam pedidos e respostas HTTP(S) entre a sua aplicação e as APIs. Herdam de BasePlugin e substituem métodos como BeforeRequestAsync e BeforeResponseAsync. Use plugins HTTP quando quiser simular erros de API, adicionar respostas simuladas, validar cabeçalhos de pedidos ou inspecionar e modificar o tráfego HTTP.

  • Os plugins Stdio interceptam mensagens enviadas por entrada/saída padrão (stdin, stdout, stderr) entre um processo pai e um processo filho. Implementam a IStdioPlugin interface (que BasePlugin também implementa) e sobrepõem métodos como BeforeStdinAsync, AfterStdoutAsync, e AfterStderrAsync. Use plugins stdio ao trabalhar com ferramentas que comunicam através de stdio, como servidores Model Context Protocol (MCP).

Uma única classe de plugin pode gerir tanto o tráfego HTTP como o stdio ao sobrepor métodos de ambos os conjuntos.

Pré-requisitos

Antes de começar a criar um plug-in personalizado, certifique-se de ter os seguintes pré-requisitos:

Criar um novo plugin

Siga as próximas etapas para criar um novo projeto:

  1. Crie um novo projeto de biblioteca de classes usando o dotnet new classlib comando.

    dotnet new classlib -n MyCustomPlugin

  2. Abra o projeto recém-criado no Visual Studio Code.

    code MyCustomPlugin

  3. Adicione o pacote Dev Proxy Abstractions NuGet ao seu projeto.

    dotnet add package DevProxy.Abstractions

  4. Exclua as bibliotecas de ligação dinâmica de dependência (DLLs) da saída da build adicionando uma ExcludeAssets tag per PackageReference no MyCustomPlugin.csproj ficheiro.

    <ExcludeAssets>runtime</ExcludeAssets>

  5. Crie uma nova classe que herda da BaseProxy classe.

    using DevProxy.Abstractions.Plugins;
using DevProxy.Abstractions.Proxy;
using Microsoft.Extensions.Logging;

namespace MyCustomPlugin;

public sealed class CatchApiCallsPlugin(
    ILogger<CatchApiCallsPlugin> logger,
    ISet<UrlToWatch> urlsToWatch) : BasePlugin(logger, urlsToWatch)
{
    public override string Name => nameof(CatchApiCallsPlugin);

    public override Task BeforeRequestAsync(ProxyRequestArgs e, CancellationToken cancellationToken)
    {
        Logger.LogTrace("{Method} called", nameof(BeforeRequestAsync));

        ArgumentNullException.ThrowIfNull(e);

        if (!e.HasRequestUrlMatch(UrlsToWatch))
        {
            Logger.LogRequest("URL not matched", MessageType.Skipped, new(e.Session));
            return Task.CompletedTask;
        }

        var headers = e.Session.HttpClient.Request.Headers;
        var header = headers.Where(h => h.Name == "Authorization").FirstOrDefault();
        if (header is null)
        {
            Logger.LogRequest($"Does not contain the Authorization header", MessageType.Warning, new LoggingContext(e.Session));
            return Task.CompletedTask;
        }

        Logger.LogTrace("Left {Name}", nameof(BeforeRequestAsync));
        return Task.CompletedTask;
    }
}

  6. Construa o seu projeto.

    dotnet build

Utilize o seu plugin personalizado

Para usar seu plug-in personalizado, você precisa adicioná-lo ao arquivo de configuração do Dev Proxy:

  1. Adicione a nova configuração do devproxyrc.json plugin no arquivo.

    Ficheiro: devproxyrc.json

    {
  "plugins": [{
    "name": "CatchApiCallsPlugin",
    "enabled": true,
    "pluginPath": "./bin/Debug/net10.0/MyCustomPlugin.dll",
  }]
}

  2. Execute o proxy de desenvolvimento.

    devproxy

O plugin de exemplo verifica todos os URLs correspondentes em busca do cabeçalho necessário Authorization. Se o cabeçalho não estiver presente, ele mostrará uma mensagem de aviso.

Adicionar configuração personalizada ao seu plugin (opcional)

Você pode estender a lógica do seu plug-in adicionando configuração personalizada:

  1. Herda da classe BasePlugin<TConfiguration>. O Dev Proxy expõe, em tempo de execução, a configuração do plug-in analisada através da propriedade Configuration.

    using DevProxy.Abstractions.Plugins;
using DevProxy.Abstractions.Proxy;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.Logging;

namespace MyCustomPlugin;

public sealed class CatchApiCallsConfiguration
{
    public string? RequiredHeader { get; set; }
}

public sealed class CatchApiCallsPlugin(
    HttpClient httpClient,
    ILogger<CatchApiCallsPlugin> logger,
    ISet<UrlToWatch> urlsToWatch,
    IProxyConfiguration proxyConfiguration,
    IConfigurationSection pluginConfigurationSection) :
    BasePlugin<CatchApiCallsConfiguration>(
        httpClient,
        logger,
        urlsToWatch,
        proxyConfiguration,
        pluginConfigurationSection)
{
    public override string Name => nameof(CatchApiCallsPlugin);

    public override Task BeforeRequestAsync(ProxyRequestArgs e, CancellationToken cancellationToken)
    {
        Logger.LogTrace("{Method} called", nameof(BeforeRequestAsync));

        ArgumentNullException.ThrowIfNull(e);

        if (!e.HasRequestUrlMatch(UrlsToWatch))
        {
            Logger.LogRequest("URL not matched", MessageType.Skipped, new(e.Session));
            return Task.CompletedTask;
        }

        // Start using your custom configuration
        var requiredHeader = Configuration.RequiredHeader ?? string.Empty;
        if (string.IsNullOrEmpty(requiredHeader))
        {
            // Required header is not set, so we don't need to do anything
            Logger.LogRequest("Required header not set", MessageType.Skipped, new LoggingContext(e.Session));
            return Task.CompletedTask;
        }

        var headers = e.Session.HttpClient.Request.Headers;
        var header = headers.Where(h => h.Name == requiredHeader).FirstOrDefault();
        if (header is null)
        {
            Logger.LogRequest($"Does not contain the {requiredHeader} header", MessageType.Warning, new LoggingContext(e.Session));
            return Task.CompletedTask;
        }

        Logger.LogTrace("Left {Name}", nameof(BeforeRequestAsync));
        return Task.CompletedTask;
    }
}

  2. Construa o seu projeto.

    dotnet build

  3. Atualize o devproxyrc.json arquivo para incluir a nova configuração.

    Ficheiro: devproxyrc.json

    {
  "$schema": "https://raw.githubusercontent.com/dotnet/dev-proxy/main/schemas/v3.0.0/rc.schema.json",
  "plugins": [{
    "name": "CatchApiCallsPlugin",
    "enabled": true,
    "pluginPath": "./bin/Debug/net10.0/MyCustomPlugin.dll",
    "configSection": "catchApiCalls"
  }],
  "catchApiCalls": {
    "requiredHeader": "Authorization"
  }
}

  4. Execute o proxy de desenvolvimento.

    devproxy

Consulte também

  • Last updated on