Usar o Proxy de Desenvolvimento com aplicativos .NET Aspire

.NET Aspire é uma stack opinativa e pronta para nuvem para criar aplicativos distribuídos observáveis e prontos para produção. Ele é criado com base no .NET e fornece uma plataforma moderna, rápida e escalonável para a criação de aplicativos Web.

Para usar o Proxy de Desenvolvimento com seu aplicativo .NET Aspire, use o pacote NuGet DevProxy.Hosting. O pacote fornece extensões Dev Proxy .NET Aspire para integrar convenientemente o Proxy de Desenvolvimento ao seu aplicativo .NET Aspire.

Instalar o pacote NuGet de extensões Aspire do Proxy de Desenvolvimento .NET

Para instalar o pacote NuGet de extensões do Dev Proxy .NET Aspire, execute o seguinte comando na pasta raiz do seu aplicativo .NET Aspire:

dotnet add package DevProxy.Hosting

Usando o pacote de extensões Dev Proxy .NET Aspire, você pode integrar Dev Proxy a partir do executável instalado localmente ou de um Docker container.

Integrar o Dev Proxy a partir do executável instalado localmente

Se você tiver o Proxy de Desenvolvimento instalado localmente, a maneira mais conveniente de integrá-lo ao aplicativo .NET Aspire é referenciar o executável local. O trecho de código a seguir mostra como integrar o Dev Proxy com o aplicativo inicial .NET Aspire, usando o executável instalado localmente.

Importante

Ao configurar o Proxy de Desenvolvimento para usar o executável local, verifique se o executável está disponível em todos os computadores em que você executa seu aplicativo. Se você quiser usar o Proxy de Desenvolvimento em um ambiente em contêineres, considere usar o contêiner do Docker.

using DevProxy.Hosting;

var builder = DistributedApplication
    .CreateBuilder(args);

// Add an API service to the application
var apiService = builder.AddProject<Projects.AspireStarterApp_ApiService>("apiservice")
    .WithHttpsHealthCheck("/health");

var devProxy = builder.AddDevProxyExecutable("devproxy")
    .WithConfigFile(".devproxy/config/devproxy.json")
    .WithUrlsToWatch(() => [$"{apiService.GetEndpoint("https").Url}/*"]);

// Add a web frontend project and configure it to use Dev Proxy
builder.AddProject<Projects.AspireStarterApp_Web>("webfrontend")
    .WithExternalHttpEndpoints()
    .WithHttpsHealthCheck("/health")
    .WithEnvironment("HTTPS_PROXY", devProxy.GetEndpoint(DevProxyResource.ProxyEndpointName))
    .WithReference(apiService)
    .WaitFor(apiService)
    .WaitFor(devProxy);

// Build and run the application
builder.Build().Run();

Primeiro, usando as extensões Dev Proxy .NET Aspire, você adiciona um serviço de Proxy de Desenvolvimento ao seu aplicativo. O AddDevProxyExecutable método especifica o nome do executável do Proxy de Desenvolvimento. Usando o WithConfigFile método, especifique o caminho para o arquivo de configuração do Proxy de Desenvolvimento. Usando o método WithUrlsToWatch, você especifica a lista de URLs para monitorar. Neste exemplo, você deseja que o Proxy de Desenvolvimento intercepte as solicitações que o aplicativo Web faz ao serviço de API.

Importante

Observe que o WithUrlsToWatch método aceita uma função que retorna uma lista de URLs a serem observadas. Isso ocorre porque o ponto de extremidade de serviço de API não está disponível quando você configura o Proxy de Desenvolvimento, portanto, não é possível passar a URL diretamente. Em vez disso, você usa uma expressão lambda que retorna a URL do serviço de API quando ela está disponível.

Em seguida, no aplicativo Web, você usa a HTTPS_PROXY variável de ambiente para configurar o aplicativo Web para usar o Proxy de Desenvolvimento. Usando o método WaitFor, você instrui o aplicativo web a aguardar o Proxy de Dev estar disponível antes de começar.

Integrar o Dev Proxy a partir de um contêiner do Docker

Como alternativa, você pode integrar o Proxy de Desenvolvimento ao aplicativo .NET Aspire de um contêiner do Docker. Usar a imagem do Docker do Proxy de Desenvolvimento é conveniente, pois o .NET Aspire faz o download automático da imagem se ela não estiver disponível localmente. A desvantagem é que há mais algumas etapas para configurar o Proxy de Desenvolvimento em seu aplicativo.

O trecho de código a seguir mostra como integrar o Dev Proxy de um contêiner do Docker com o aplicativo inicial .NET Aspire.

using DevProxy.Hosting;

var builder = DistributedApplication
    .CreateBuilder(args);

// Add an API service to the application
var apiService = builder.AddProject<Projects.AspireStarterApp_ApiService>("apiservice")
    .WithHttpsHealthCheck("/health");

// Add Dev Proxy as a container resource
var devProxy = builder.AddDevProxyContainer("devproxy")
    // specify the Dev Proxy configuration file; relative to the config folder
    .WithConfigFile("./devproxy.json")
    // mount the local folder with PFX certificate for intercepting HTTPS traffic
    .WithCertFolder(".devproxy/cert")
    // mount the local folder with Dev Proxy configuration
    .WithConfigFolder(".devproxy/config")
    // let Dev Proxy intercept requests to the API service
    .WithUrlsToWatch(() => [$"{apiService.GetEndpoint("https").Url}/*"]);

// Add a web frontend project and configure it to use Dev Proxy
builder.AddProject<Projects.AspireStarterApp_Web>("webfrontend")
    .WithExternalHttpEndpoints()
    .WithHttpsHealthCheck("/health")
    // set the HTTPS_PROXY environment variable to the Dev Proxy endpoint
    .WithEnvironment("HTTPS_PROXY", devProxy.GetEndpoint(DevProxyResource.ProxyEndpointName))
    .WithReference(apiService)
    .WaitFor(apiService)
    .WaitFor(devProxy);

// Build and run the application
builder.Build().Run();

As etapas básicas são as mesmas que ao usar o executável instalado localmente. A principal diferença é como você especifica o arquivo de configuração e o certificado para interceptar o tráfego HTTPS.

Ao integrar o Proxy de Desenvolvimento de um contêiner do Docker, você precisa montar as pastas locais com o arquivo de configuração e o certificado no contêiner. Neste exemplo, em sua solução .NET Aspire, você tem a seguinte estrutura de pastas:

AspireStarterApp
├── .devproxy
│   ├── cert
│   │   └── rootCert.pfx
│   └── config
│       └── devproxy.json
├── Projects
│   ├── AspireStarterApp_ApiService
│   └── AspireStarterApp_Web
└── AspireStarterApp.sln

A cert pasta contém o certificado PFX (Troca de Informações Pessoais) que o Proxy de Desenvolvimento usa para interceptar o tráfego HTTPS.

Importante

Você deve confiar no certificado na cert pasta em seu computador ou as solicitações para o serviço de API falharão. Além disso, para que o Proxy de Desenvolvimento carregue o certificado, ele deve estar no formato PFX, deve ser nomeado rootCert.pfxe não deve ser protegido com uma senha.

A pasta config contém o arquivo de configuração do Proxy de Desenvolvimento e outros arquivos do Proxy de Desenvolvimento, como simulações ou erros.

Como você está montando os arquivos de certificado e de configuração para separar volumes no contêiner, eles devem ser armazenados em pastas separadas.

Usar o Dev Proxy com o aplicativo inicial .NET Aspire

Depois de iniciar o aplicativo, o Dev Proxy aparece como um recurso no aplicativo.

Quando você usa o aplicativo Web para que ele faça solicitações para o serviço de API, o Proxy de Desenvolvimento intercepta as solicitações e manipula de acordo com sua configuração. Você pode ver a saída do Proxy de Desenvolvimento na seção Console do painel do .NET Aspire.