Usar arquivos .http no Visual Studio 2022

O editor de arquivos Visual Studio 2022 .http fornece uma maneira conveniente de testar projetos ASP.NET Core, especialmente aplicativos de API. O editor fornece uma interface do usuário que:

• Cria e atualiza arquivos .http.
• Envia solicitações HTTP especificadas em arquivos .http.
• Exibe as respostas.

Esse artigo contém a documentação para:

• A sintaxe do arquivo.http.
• Como criar um arquivo .http.
• Como enviar uma solicitação de um arquivo .http.
• Onde localizar as opções de arquivo .http que podem ser configuradas..
• Como criar solicitações em arquivos .http usando o Gerenciador de pontos de extremidade do Visual Studio 2022.

O formato de arquivo .http e o editor foram inspirados na RESTExtensão cliente do Visual Studio Code. O editor de .http do Visual Studio 2022 reconhece .rest como uma extensão de arquivo alternativa para o mesmo formato de arquivo.

Pré-requisitos

• Visual Studio 2022 versão 17.8 ou posterior com a carga de trabalho de ASP.NET e desenvolvimento Web instalada.

A sintaxe do arquivo .http

As seções a seguir explicam a sintaxe do arquivo .http.

Requests

O formato de uma solicitação HTTP é HTTPMethod URL HTTPVersion, tudo em uma linha, em que:

• HTTPMethod é o método HTTP a ser usado, por exemplo:
  • OPTIONS
  • GET
  • HEAD
  • POST
  • PUT
  • PATCH
  • DELETE
  • TRACE
  • CONNECT
• URL é a URL para qual enviar a solicitação. A URL pode incluir parâmetros de cadeia de caracteres de consulta. A URL não precisa apontar para um projeto Web local. Ela pode apontar para qualquer URL que o Visual Studio possa acessar.
• HTTPVersion é opcional e especifica a versão HTTP que deve ser usada, ou seja, HTTP/1.1, HTTP/2ou HTTP/3.

Um arquivo pode conter várias solicitações usando linhas com ### como delimitadores. O exemplo a seguir, que mostra três solicitações em um arquivo, ilustra essa sintaxe:

GET https://localhost:7220/weatherforecast

###

GET https://localhost:7220/weatherforecast?date=2023-05-11&location=98006

###

GET https://localhost:7220/weatherforecast HTTP/3

###

Cabeçalhos da solicitação

Para adicionar um ou mais cabeçalhos, adicione cada cabeçalho em sua própria linha imediatamente após a linha de solicitação. Não inclua nenhuma linha em branco entre a linha de solicitação e o primeiro cabeçalho ou entre as linhas de cabeçalho subsequentes. O formato é HeaderName: Value, conforme mostrado no exemplo a seguir:

GET https://localhost:7220/weatherforecast
Date: Wed, 27 Apr 2023 07:28:00 GMT

###

GET https://localhost:7220/weatherforecast
Cache-Control: max-age=604800
Age: 100

###

Importante

Ao chamar uma API que se autentica com cabeçalhos, não confirme nenhum segredo em um repositório de código-fonte. Confira os métodos com suporte para armazenar segredos posteriormente neste artigo, como Segredos do usuário do ASP.NET Core, Azure Key Vault e criptografia DPAPI.

Corpo da solicitação

Adicione o corpo da solicitação após uma linha em branco, conforme mostrado no exemplo a seguir:

POST https://localhost:7220/weatherforecast
Content-Type: application/json
Accept-Language: en-US,en;q=0.5

{
    "date": "2023-05-10",
    "temperatureC": 30,
    "summary": "Warm"
}

###

Comentários

Linhas que começam com # ou // são comentários. Essas linhas são ignoradas quando o Visual Studio envia solicitações HTTP.

Variáveis

Uma linha que começa com @ define uma variável por meio da sintaxe @VariableName=Value.

As variáveis podem ser referenciadas em solicitações definidas posteriormente no arquivo. Eles são referenciados encapsulando seus nomes em chaves duplas, {{ e }}. O exemplo a seguir mostra duas variáveis definidas e usadas em uma solicitação:

@hostname=localhost
@port=44320
GET https://{{hostname}}:{{port}}/weatherforecast

As variáveis podem ser definidas usando valores de outras variáveis que foram definidas anteriormente no arquivo. O exemplo a seguir usa uma variável na solicitação em vez das duas mostradas no exemplo anterior:

@hostname=localhost
@port=44320
@host={{hostname}}:{{port}}
GET https://{{host}}/api/search/tool

Arquivos de ambiente

Para fornecer a variáveis valores diferentes em ambientes diferentes, crie um arquivo chamado http-client.env.json. Localize o arquivo no mesmo diretório que o arquivo .http ou em um de seus diretórios pai. Veja a seguir um exemplo de um arquivo de ambiente:

{
  "dev": {
    "HostAddress": "https://localhost:44320"
  },
  "remote": {
    "HostAddress": "https://contoso.com"
  }
}

O arquivo de ambiente é um arquivo JSON que contém um ou mais ambientes nomeados, como "dev" e "remote" no exemplo anterior. Cada ambiente nomeado contém uma ou mais variáveis, como HostAddress no exemplo anterior. Variáveis de um arquivo de ambiente são referenciadas da mesma maneira que outras variáveis, conforme mostrado no exemplo a seguir:

GET {{HostAddress}}/api/search/tool

O valor usado para a variável ao enviar uma solicitação é determinado por uma lista suspensa do seletor de ambiente no canto superior direito do editor de arquivos .http. A captura de tela a seguir mostra o seletor:

O arquivo de ambiente não precisa estar na pasta do projeto. O Visual Studio procura um arquivo de ambiente na pasta em que o arquivo .http existe. Se não estiver nessa pasta, o Visual Studio examinará os diretórios pai para encontrá-lo. Quando um arquivo denominado http-client.env.json é encontrado, a pesquisa termina. O arquivo encontrado mais próximo do arquivo .http é usado.

Depois de criar ou editar um arquivo .http, talvez seja necessário fechar e reabrir o projeto para ver as alterações refletidas no seletor de ambiente. Pressione F6 para selecionar o seletor de ambiente.

O Visual Studio exibe avisos nas seguintes situações:

• O arquivo .http faz referência a uma variável que não está definida no arquivo .http ou no arquivo de ambiente.
• O arquivo de ambiente contém uma variável que não é referenciada no arquivo .http.

Uma variável definida em um arquivo de ambiente pode ser a mesma definida no arquivo .http ou pode ser diferente. Se uma variável for definida no arquivo .http e no arquivo de ambiente, o valor no arquivo .http substituirá o valor no arquivo de ambiente.

Arquivos de ambiente específicos do usuário

Um valor específico do usuário é qualquer valor com o qual um desenvolvedor individual deseja testar, mas que não deseja compartilhar com a equipe. Como é feito check-in do arquivo http-client.env.json no controle do código-fonte por padrão, não seria apropriado adicionar valores específicos do usuário a esse arquivo. Em vez disso, coloque-os em um arquivo nomeado http-client.env.json.user localizado na mesma pasta que o arquivo http-client.env.json. Os arquivos que terminam com .user devem ser excluídos do controle do código-fonte por padrão ao usar os recursos de controle do código-fonte do Visual Studio.

Quando o arquivo http-client.env.json é carregado, o Visual Studio procura um arquivo irmão http-client.env.json.user. Se uma variável for definida em um ambiente no arquivo http-client.env.json e no arquivo http-client.env.json.user, o valor no arquivo http-client.env.json.user ganhará.

Veja a seguir um cenário de exemplo que mostra como um arquivo de ambiente específico do usuário funciona. Suponha que o arquivo .http contenha o seguinte conteúdo:

GET {{HostAddress}}/{{Path}}
Accept: application/json

E suponha que o arquivo http-client.env.json contenha o seguinte conteúdo:

{
  "dev": {
    "HostAddress": "https://localhost:7128",
    "Path": "/weatherforecast"
  },
  "remote": {
    "HostAddress": "https://contoso.com",
    "Path": "/weatherforecast"
  }
}

E suponha que haja um arquivo de ambiente específico do usuário que contenha o seguinte conteúdo:

{
  "dev": {
    "Path": "/swagger/index.html"
  }
}

Quando o usuário seleciona o ambiente de "desenvolvimento", a solicitação é enviada para https://localhost:7128/swagger/index.html porque o valor Path no arquivo http-client.env.json.user substitui o valor no arquivo http-client.env.json.

Com os mesmos arquivos de ambiente, suponha que as variáveis sejam definidas no arquivo .http:

@HostAddress=https://contoso.com
@Path=/weatherforecast

GET {{HostAddress}}/{{Path}}
Accept: application/json

Nesse cenário, a solicitação de ambiente "dev" é enviada para https://contoso.com/weatherforecast porque definições de variável em arquivos .http substituem definições de arquivo de ambiente.

Segredos do usuário do ASP.NET Core

Para obter um valor de segredos do usuário, use um arquivo de ambiente localizado na mesma pasta que o projeto do ASP.NET Core. No arquivo de ambiente, defina uma variável que tenha as propriedades provider e secretName. Defina o valor provider como AspnetUserSecrets e defina secretName como o nome do segredo do usuário desejado. Por exemplo, o arquivo de ambiente a seguir define uma variável denominada ApiKeyDev que obtém seu valor do segredo do usuário config:ApiKeyDev:

{
  "dev": {
    "ApiKeyDev": {
      "provider": "AspnetUserSecrets",
      "secretName": "config:ApiKeyDev"
    }
  }
}

Para usar essa variável no arquivo .http, faça referência a ela como uma variável padrão. Por exemplo:

GET {{HostAddress}}{{Path}}
X-API-KEY: {{ApiKeyDev}}

Quando a solicitação é enviada, o valor do segredo ApiKeyDev está no cabeçalho X-API-KEY.

Conforme você digita no arquivo http, o editor mostra uma lista de conclusão para o nome da variável, mas não mostra seu valor.

Azure Key Vault

O Azure Key Vault é uma das várias soluções de gerenciamento de chaves no Azure que podem ser usadas para gerenciamento de segredos. Dos três repositórios de segredos atualmente compatíveis com arquivos .http, o Key Vault é a melhor opção para compartilhar segredos entre diferentes usuários. As outras duas opções, Segredos do usuário do ASP.NET e Criptografia DPAPI, não são facilmente compartilhadas.

Para usar um valor do Azure Key Vault, você deve estar conectado ao Visual Studio com uma conta que tenha acesso ao Key Vault desejado. Defina uma variável em um arquivo de ambiente com os metadados para acessar o segredo. A variável é nomeada AKVSecret no exemplo a seguir:

{
  "dev": {
    "AKVSecret": {
      "provider": "AzureKeyVault",
      "secretName": "SecretInKeyVault",
      "resourceId": "/subscriptions/3a914c59-8175a9e0e540/resourceGroups/my-key-vault-rg/providers/Microsoft.KeyVault/vaults/my-key-vault-01182024"
    }
  }
}

A variável AKVSecret extrai o seu valor do Azure Key Vault. As seguintes propriedades são definidas em AKVSecret:

Nome	Descrição
provedor	Para o Key Vault, sempre use AzureKeyVault.
secretName	Nome do segredo a ser extraído.
resourceId	ID de recurso do Azure para o Key Vault específico a ser acessado.

O valor da propriedade resourceId pode ser encontrado no portal do Azure. Vá para Configurações > Propriedades para encontrá-lo. Para secretName, use o nome do segredo que aparece na página Segredos no portal do Azure.

Por exemplo, o arquivo .http a seguir tem uma solicitação que usa esse valor secreto.

GET {{HostAddress}}{{Path}}
X-AKV-SECRET: {{akvSecret}}

Criptografia DPAPI

No Windows, há uma API de Proteção de Dados (DPAPI) que pode ser usada para criptografar dados confidenciais. Quando a API de Proteção de Dados é usada para criptografar dados, os valores criptografados são sempre específicos do computador e também são específicos ao usuário em arquivos .http. Esses valores não podem ser compartilhados com outros usuários.

Para criptografar um valor, use o seguinte aplicativo de console:

using System.Security.Cryptography;
using System.Text;

string stringToEncrypt = "Hello, World!";
byte[] encBytes = ProtectedData.Protect(Encoding.Unicode.GetBytes(stringToEncrypt), optionalEntropy: null, scope: DataProtectionScope.CurrentUser);
string base64 = Convert.ToBase64String(encBytes);
Console.WriteLine(base64);

O aplicativo de console anterior faz referência ao pacote NuGet System.Security.Cryptography.ProtectedData. Para habilitar o valor criptografado para funcionar no arquivo .http, criptografe com o escopo definido como DataProtectionScope.CurrentUser. O valor criptografado é uma cadeia de caracteres codificada em base64 que pode ser copiada e colada no arquivo de ambiente.

No arquivo de ambiente, crie uma variável que tenha as propriedades provider e value. Defina provider como Encrypted, e defina value como o valor criptografado. Por exemplo, o arquivo de ambiente a seguir define uma variável nomeada dpapiValue que obtém seu valor de uma cadeia de caracteres que foi criptografada com DPAPI.

{
  "dev": {
    "dpapiValue": {
      "provider": "Encrypted",
      "value": "AQAAANCMnd8BFdERjHoAwE/Cl+sBAAAA5qwfg4+Bhk2nsy6ujgg3GAAAAAACAAAAAAAQZgAAAAEAACAAAAAqNXhXc098k1TtKmaI4cUAbJVALMVP1zOR7mhC1RBJegAAAAAOgAAAAAIAACAAAABKu4E9WC/zX5LYZZhOS2pukxMTF9R4yS+XA9HoYF98GzAAAAAzFXatt461ZnVeUWgOV8M/DkqNviWUUjexAXOF/JfpJMw/CdsizQyESus2QjsCtZlAAAAAL7ns3u9mEk6wSMIn+KNsW/vdAw51OaI+HPVrt5vFvXRilTtvGbU/JnxsoIHj0Z7OOxlwOSg1Qdn60zEqmlFJBg=="
    }
  }
}

Com o arquivo de ambiente anterior, dpapiValue pode ser usado no arquivo .http como qualquer outra variável. Por exemplo:

GET {{HostAddress}}{{Path}}
X-DPAPI-Secret: {{dpapiSecret}}

Quando essa solicitação é enviada, X-DPAPI-Secret tem o valor de segredo descriptografado.

Variáveis de ambiente

Para obter o valor de uma variável de ambiente, use $processEnv. O exemplo a seguir coloca o valor da variável de ambiente USERNAME no cabeçalho X-UserName.

GET {{HostAddress}}{{Path}}
X-UserName: {{$processEnv USERNAME}}

Se você tentar usar $processEnv para acessar uma variável de ambiente que não existe, o editor de arquivos .http exibirá uma mensagem de erro.

arquivos .env

Para obter o valor de uma variável definida em um arquivo .env, use $dotenv. O arquivo .env deve estar na pasta do projeto. O formato para $dotenv é o mesmo que o formato para $processEnv. Por exemplo, se o arquivo .env tiver este conteúdo:

USERNAME=userFromDotenv

E o arquivo .http tiver este conteúdo:

GET {{HostAddress}}{{Path}}
X-UserName: {{$dotEnv USERNAME}}

O cabeçalho X-UserName terá "userFromDotenv".

Quando $dotenv é inserido no editor, ele mostra as conclusões das variáveis definidas no arquivo .env.

Observação

Arquivos .env podem não ser excluídos do controle do código-fonte por padrão, portanto, tenha cuidado para evitar o check-in de valores secretos.

Inteiros aleatórios

Para gerar um inteiro aleatório, use $randomInt. A sintaxe é {{$randomInt [min max]}}, em que os valores min e max são opcionais.

Datas e horas

• $datetime gera uma cadeia de caracteres datetime em UTC. A sintaxe é {{$datetime [format] [offset option]}}, em que as opções de formato e deslocamento são opcionais.
• $localDatetime gera uma cadeia de caracteres datetime no fuso horário local. A sintaxe é {{$localDatetime [format] [offset option]}}, em que as opções de formato e deslocamento são opcionais.
• $timeStamp gera um timestamp em UTC. O timestamp é o número de segundos desde a Época Unix no horário UTC. A sintaxe é {{$timestamp [offset option]}}, em que a opção de deslocamento é opcional.

A opção [format] é um rfc1123, iso8601, ou um formato personalizado entre aspas. Por exemplo:

GET https://httpbin.org/headers
X-CUSTOM: {{$datetime "dd-MM-yyyy"}}
X-ISO8601: {{$datetime iso8601}}
X-ISO8601L: {{$localDatetime iso8601}}
X-RFC1123: {{$datetime rfc1123}}
X-RFC1123L: {{$localDatetime rfc1123}}

Veja a seguir alguns valores de exemplo gerados pelos exemplos anteriores:

{
  "headers": {
    "X-Custom": "17-01-2024",
    "X-Iso8601": "2024-01-17T22:59:55.5345770+00:00",
    "X-Iso8601L": "2024-01-17T14:59:55.5345770-08:00",
    "X-Rfc1123": "Wed, 17 Jan 2024 22:59:55 GMT",
    "X-Rfc1123L": "Wed, 17 Jan 2024 14:59:55 -08"
  }
}

A sintaxe [offset option] está no formato number unit onde number é um número inteiro e unit é um dos seguintes valores:

unit	Explicação
ms	Milissegundos
s	Segundos
m	Minutos
h	Horário
d	Days (dias)
w	Weeks
M	Months
y	Anos

Por exemplo:

GET https://httpbin.org/headers
X-Custom-Minus-1-Year: {{$datetime "dd-MM-yyyy" -1 y}}
X-RFC1123-Plus-1-Day: {{$datetime rfc1123 1 d}} 
X-Timestamp-Plus-1-Year: {{$timestamp 1 y}}

Veja a seguir alguns valores de exemplo gerados pelos exemplos anteriores:

{
  "headers": {
    "X-Custom-Minus-1-Year": "17-01-2023",
    "X-Rfc1123-Plus-1-Day": "Thu, 18 Jan 2024 23:02:48 GMT",
    "X-Timestamp-Plus-1-Year": "1737154968"
  }
}

Alguns dos exemplos anteriores usam o site de código aberto gratuito <httpbin.org>. Este é um site de terceiros não afiliado à Microsoft. Nesses exemplos, ele retorna um corpo de resposta com os cabeçalhos que foram enviados na solicitação. Para obter informações sobre outras maneiras de usar este recurso para testes de API, consulte a home page do site httpbin.org.

Sintaxe incompatível

O editor de arquivos .http do Visual Studio 2022 não tem todos os recursos que a Extensão clienteREST do Visual Studio Code tem. A lista a seguir inclui alguns dos recursos mais significativos disponíveis apenas na extensão do Visual Studio Code:

• Linha de solicitação que abrange mais de uma linha
• Solicitações nomeadas
• Especificar o caminho do arquivo como corpo da solicitação
• Formato misto para corpo ao usar multipart/form-data
• GraphQL solicitações
• Solicitação do cURL
• Copiar/colar como cURL
• Histórico de solicitação
• Salvar corpo da resposta no arquivo
• Autenticação baseada em certificado
• Variáveis de prompt
• Personalizar a visualização da resposta
• Configurações por solicitação

Criar um arquivo .http

• Em Gerenciador de Soluções, clique com o botão direito do mouse em um projeto do ASP.NET Core.

• No menu de contexto, selecione Adicionar>Novo item .

• Na caixa de diálogo Adicionar Novo Item, selecione ASP.NET Core>Geral.

• Selecione o Arquivo HTTP File e, em seguida, Adicionar.

  

Enviar uma solicitação HTTP

• Adicione pelo menos uma solicitação a um arquivo .http e salve o arquivo.

• Se a URL de solicitação apontar para localhost e a porta do projeto, execute o projeto antes de tentar enviar uma solicitação para ele.

• Selecione o link Send Request ou Debug diretamente acima da solicitação a ser enviada.

  A solicitação é enviada para a URL especificada e a resposta aparece em um painel separado à direita da janela do editor.

  

Opções do arquivo .http

Alguns aspectos do comportamento do arquivo .http podem ser configurados. Para ver o que está disponível, acesse Ferramentas>Opções>Editor de texto>Rest. Por exemplo, a configuração de tempo limite pode ser configurada na guia Avançado. Veja a seguir uma captura de tela da caixa de diálogo Opções:

Como usar o Gerenciador de Pontos de Extremidade

O Gerenciador de Pontos de Extremidade é uma janela de ferramentas que mostra todos os pontos de extremidade definidos por uma API Web. A ferramenta permite que você envie solicitações para os pontos de extremidade usando um arquivo .http.

O conjunto inicial de pontos de extremidade exibidos pelo Explorador de Pontos de Extremidade é descoberto estaticamente. Há alguns pontos de extremidade que não podem ser descobertos estaticamente. Por exemplo, os pontos de extremidade definidos em um projeto de biblioteca de classes não podem ser descobertos até o runtime. Quando você executa ou depura uma API Web, o Visual Studio versão 17.11 Preview também descobre pontos de extremidade dinamicamente em tempo de execução e os adiciona ao Endpoints Explorer.

Como abrir o Gerenciador de Pontos de Extremidade

Selecione Exibir>Outras Janelas>Gerenciador de Pontos de Extremidade.

Adicione uma solicitação para um arquivo .http

Clique com o botão direito do mouse em uma solicitação em Gerenciador de Pontos de Extremidade e selecione Gerar Solicitação.

• Se houver um arquivo .http com o nome do projeto igual ao nome do arquivo, a solicitação será adicionada a esse arquivo.
• Caso contrário, um arquivo .http é criado com o nome do projeto igual ao nome do arquivo e a solicitação será adicionada a esse arquivo.

A captura de tela anterior mostra os pontos de extremidade definidos pelo modelo de projeto de API mínima. O exemplo a seguir mostra a solicitação gerada para o ponto de extremidade selecionado:

GET {{WebApplication1_HostAddress}}/weatherforecast/
Accept: application/json

###

Envie a solicitação conforme descrito anteriormente nesse artigo.

Confira também

• A janela do gerenciador de pontos de extremidade reconhece apenas cadeias de caracteres literais para rotas
• Desenvolvimento de API Web no Visual Studio 2022
• Extensão do cliente REST do Visual Studio Code