Uso de archivos .http en Visual Studio 2022

  • Artículo

El editor de archivos de Visual Studio 2022.http proporciona una manera cómoda de probar proyectos de ASP.NET Core, especialmente las aplicaciones de API. El editor proporciona una interfaz de usuario que:

  • Crea y actualiza archivos .http.
  • Envía solicitudes HTTP especificadas en archivos .http.
  • Muestra las respuestas.

Este artículo contiene documentación para lo siguiente:

El formato de archivo .http y el editor se han inspirado en la extensión REST Client de Visual Studio Code. El editor .http de Visual Studio 2022 reconoce .rest como una extensión de archivo alternativa para el mismo formato de archivo.

Requisitos previos

Sintaxis del archivo .http

En las secciones siguientes se explica la sintaxis del archivo .http.

Requests

El formato de una solicitud HTTP es HTTPMethod URL HTTPVersion, todo en una línea, donde:

  • HTTPMethod es el método HTTP que se va a usar, por ejemplo:
  • URL es la dirección URL a la que se va a enviar la solicitud. La dirección URL puede incluir parámetros de cadena de consulta. La dirección URL no tiene que apuntar a un proyecto web local. Puede apuntar a cualquier dirección URL a la que Visual Studio pueda acceder.
  • HTTPVersion es opcional y especifica la versión HTTP que se debe usar, es decir, HTTP/1.1, HTTP/2 o HTTP/3.

Un archivo puede contener varias solicitudes si se usan líneas con ### como delimitadores. En el ejemplo siguiente se muestran tres solicitudes en un archivo que ilustra esta sintaxis:

GET https://localhost:7220/weatherforecast

###

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

###

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

###

Encabezados de solicitud

Para agregar uno o varios encabezados, agregue cada uno en su propia línea inmediatamente después de la línea de solicitud. No incluya ninguna línea en blanco entre la línea de solicitud y el primer encabezado, ni entre las líneas de encabezado posteriores. El formato es HeaderName: Value, como se muestra en los ejemplos siguientes:

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

Al llamar a una API que se autentica con encabezados, no confirme ningún secreto en un repositorio de código fuente. Consulte los métodos admitidos para almacenar secretos más adelante en este artículo, como secretos de usuario de ASP.NET Core, Azure Key Vault y el cifrado DPAPI.

Cuerpo de la solicitud

Agregue el cuerpo de la solicitud después de una línea en blanco, como se muestra en el ejemplo siguiente:

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"
}

###

Comentarios

Las líneas que comienzan por # o // son comentarios. Estas líneas se omiten cuando Visual Studio envía solicitudes HTTP.

variables

Una línea que comienza por @ define una variable mediante la sintaxis @VariableName=Value.

Se puede hacer referencia a variables en las solicitudes definidas más adelante en el archivo. Para hacer referencia a ellas, sus nombres se encapsulan entre llaves dobles, {{ y }}. En el ejemplo siguiente se muestran dos variables definidas y usadas en una solicitud:

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

Las variables se pueden definir mediante valores de otras variables definidas anteriormente en el archivo. En el ejemplo siguiente, en la solicitud se usa una variable, en lugar de las dos que se muestran en el ejemplo anterior:

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

Archivos de ambiente

Para proporcionar a las variables diferentes valores en distintos entornos, cree un archivo llamado http-client.env.json. Busque el archivo en el mismo directorio que el archivo .http o en uno de sus directorios primarios. Este es un ejemplo de un archivo de entorno:

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

El archivo de entorno es un archivo JSON que contiene uno o varios entornos con nombre, como "dev" y "remote" en el ejemplo anterior. Cada entorno con nombre contiene una o varias variables, como HostAddress en el ejemplo anterior. Se hace referencia a las variables de un archivo de entorno de la misma manera que a otras variables, como se muestra en el ejemplo siguiente:

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

El valor que se usa para la variable al enviar una solicitud viene determinado por una lista desplegable del selector de entorno en la esquina superior derecha del editor de archivos .http. En la captura de pantalla siguiente se muestra el selector:

.http file editor with environment selector highlighted. The 'dev' environment is selected.

No es necesario que el archivo de entorno esté en la carpeta del proyecto. Visual Studio busca un archivo de entorno en la carpeta donde existe el archivo .http. Si no está en esa carpeta, Visual Studio examina los directorios primarios para encontrarlo. Cuando se encuentra un archivo llamado http-client.env.json, finaliza la búsqueda. Se usa el archivo hallado más cerca del archivo .http.

Después de crear o editar un archivo .http, es posible que tenga que cerrar y volver a abrir el proyecto para ver los cambios reflejados en el selector de entorno. Presione F6 para seleccionar el selector de entorno.

Visual Studio muestra advertencias en las situaciones siguientes:

  • El archivo .http hace referencia a una variable que no se define en el archivo .http o en el archivo de entorno.
  • El archivo de entorno contiene una variable a la que no se hace referencia en el archivo .http.

Una variable definida en un archivo de entorno puede ser igual que una definida en el archivo .http, o puede ser diferente. Si se define una variable tanto en el archivo .http como en el archivo de entorno, el valor del archivo .http reemplaza el valor del archivo de entorno.

Archivos de entorno específicos del usuario

Un valor específico del usuario es cualquier valor con el que un desarrollador individual quiere probar y que no desea compartir con el equipo. Dado que el archivo http-client.env.json está registrado en el control de código fuente de forma predeterminada, no sería adecuado agregar valores específicos del usuario a este archivo. En su lugar, colóquelos en un archivo llamado http-client.env.json.user ubicado en la misma carpeta que el archivo http-client.env.json. Los archivos que finalizan con .user deben excluirse del control de código fuente de forma predeterminada al usar características de control de código fuente de Visual Studio.

Cuando se carga el archivo http-client.env.json, Visual Studio busca un archivo http-client.env.json.user del mismo nivel. Si una variable se define en un entorno tanto en el archivo http-client.env.json como en el archivo http-client.env.json.user, gana el valor del archivo http-client.env.json.user.

Este es un escenario de ejemplo que muestra cómo funciona un archivo de entorno específico del usuario. Supongamos que el archivo .http tiene el siguiente contenido:

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

Supongamos también que en el archivo http-client.env.json se incluye el siguiente contenido:

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

Y, además, supongamos que hay un archivo de entorno específico del usuario en el que se incluye el siguiente contenido:

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

Cuando el usuario selecciona el entorno "dev", la solicitud se envía a https://localhost:7128/swagger/index.html porque el valor Path del archivo http-client.env.json.user reemplaza el valor del archivo http-client.env.json.

Con los mismos archivos de entorno, supongamos que las variables se definen en el archivo .http:

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

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

En este escenario, la solicitud de entorno "dev" se envía a https://contoso.com/weatherforecast porque las definiciones de variables de los archivos .http reemplazan las definiciones de los archivos de entorno.

Secretos de usuario de ASP.NET Core

Para obtener un valor de los secretos de usuario, use un archivo de entorno que se encuentre en la misma carpeta que el proyecto de ASP.NET Core. En el archivo de entorno, defina una variable que tenga las propiedades provider y secretName. Establezca el valor provider en AspnetUserSecrets y secretName en el nombre del secreto de usuario deseado. Por ejemplo, el siguiente archivo de entorno define una variable llamada ApiKeyDev que obtiene su valor del secreto de usuario config:ApiKeyDev:

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

Para usar esta variable en el archivo .http, haga referencia a ella como variable estándar. Por ejemplo:

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

Cuando se envía la solicitud, el valor del secreto ApiKeyDev se encuentra en el encabezado X-API-KEY.

Al escribir en el archivo http, el editor muestra una lista de finalización para el nombre de la variable, pero no muestra su valor.

Azure Key Vault

Azure Key Vault es una de las diversas soluciones de administración de claves de Azure que se pueden usar para la administración de secretos. De los tres almacenes de secretos que se admiten actualmente para los archivos .http, Key Vault es la mejor opción para compartir secretos entre distintos usuarios. Las otras dos opciones, secretos de usuario de ASP.NET y cifrado DPAPI, no se comparten fácilmente.

Para usar un valor de Azure Key Vault, debe haber iniciado sesión en Visual Studio con una cuenta que tenga acceso a la instancia de Key Vault deseada. Defina una variable en un archivo de entorno con los metadatos para acceder al secreto. La variable lleva por nombre AKVSecret en el siguiente ejemplo:

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

La variable AKVSecret extrae su valor de Azure Key Vault. Las siguientes propiedades se definen en AKVSecret:

Nombre Descripción
proveedor Para Key Vault, use AzureKeyVault siempre.
secretName Nombre del secreto que se va a extraer.
resourceId Identificador de recurso de Azure para que acceda la instancia de Key Vault específica.

El valor de la propiedad resourceId se puede encontrar en Azure Portal. Vaya a Configuración > Propiedades para encontrarlo. Para secretName, use el nombre del secreto que aparece en la página Secretos de Azure Portal.

Por ejemplo, el archivo .http siguiente tiene una solicitud que usa este valor del secreto.

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

Cifrado DPAPI

En Windows, hay una API de protección de datos (DPAPI) que se puede usar para cifrar datos confidenciales. Cuando DPAPI se usa para cifrar los datos, los valores cifrados siempre son específicos de la máquina y también son específicos del usuario en los archivos .http. Estos valores no se pueden compartir con otros usuarios.

Para cifrar un valor, use la siguiente aplicación de consola:

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);

La aplicación de consola anterior hace referencia al paquete NuGet System.Security.Cryptography.ProtectedData. Para permitir que el valor cifrado funcione en el archivo .http, cifre con el ámbito establecido en DataProtectionScope.CurrentUser. El valor cifrado es una cadena codificada en base64 que se puede copiar y pegar en el archivo de entorno.

En el archivo de entorno, cree una variable que tenga las propiedades provider y value. Establezca provider en Encrypted y value en el valor cifrado. Por ejemplo, el siguiente archivo de entorno define una variable llamada dpapiValue que obtiene su valor de una cadena cifrada con DPAPI.

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

Con el archivo de entorno anterior, dpapiValue se puede usar en el archivo .http como cualquier otra variable. Por ejemplo:

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

Cuando se envía esta solicitud, X-DPAPI-Secret tiene el valor del secreto descifrado.

Variables de entorno

Para obtener el valor de una variable de entorno, use $processEnv. En el ejemplo siguiente se coloca el valor de la variable de entorno USERNAME en el encabezado X-UserName.

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

Si intenta usar $processEnv para acceder a una variable de entorno que no existe, se mostrará un mensaje de error en el editor de archivos .http.

archivos .env

Para obtener el valor de una variable que se define en un archivo .env, use $dotenv. El archivo .env debe estar en la carpeta del proyecto. El formato de $dotenv es igual que el de $processEnv. Por ejemplo, si el archivo .env tiene este contenido:

USERNAME=userFromDotenv

Y el archivo .http tiene este contenido:

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

El encabezado X-UserName tendrá "userFromDotenv".

Cuando $dotenv se escribe en el editor, muestra finalizaciones para las variables definidas en el archivo .env.

Nota:

Es posible que los archivos .env no se excluyan del control de código fuente de forma predeterminada, por lo que debe tener cuidado de no registrar ningún valor del secreto.

Enteros aleatorios

Para generar un entero aleatorio, use $randomInt. La sintaxis es {{$randomInt [min max]}} donde los valores min y max son opcionales.

Fechas y horas

  • $datetime genera una cadena datetime en UTC. La sintaxis es {{$datetime [format] [offset option]}} donde las opciones de formato y desplazamiento son opcionales.
  • $localDatetime genera una cadena datetime en la zona horaria local. La sintaxis es {{$localDatetime [format] [offset option]}} donde las opciones de formato y desplazamiento son opcionales.
  • $timeStamp genera una timestamp en UTC. La timestamp es el número de segundos desde la época unix en hora UTC. La sintaxis es {{$timestamp [offset option]}} donde la opción de desplazamiento es opcional.

La opción [format] es una de rfc1123, iso8601 o un formato personalizado entre comillas. Por ejemplo:

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}}

Estos son algunos valores de muestra que generan los ejemplos 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"
  }
}

La sintaxis [offset option] está en forma de numberunit donde number es un entero y unit es uno de los siguientes valores:

unit Explicación
ms Milisegundos
s Segundos
m Minutos
h horas
d Días
w Semanas
M Meses
y Años

Por ejemplo:

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}}

Estos son algunos valores de muestra que generan los ejemplos 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"
  }
}

En algunos de los ejemplos anteriores se usa el sitio web de código abierto gratuito <httpbin.org>. Se trata de un sitio web de terceros no afiliado a Microsoft. En estos ejemplos, devuelve un cuerpo de respuesta con los encabezados que se enviaron en la solicitud. Para obtener información sobre otras formas de usar este recurso para pruebas de API, consulte la página principal del sitio httpbin.org.

Sintaxis no admitida

El editor de archivos .http de Visual Studio 2022 no tiene todas las características que tiene la extensión REST Client de Visual Studio Code. En la lista siguiente se incluyen algunas de las características más significativas disponibles solo en la extensión Visual Studio Code:

  • Línea de solicitud que abarca más de una línea
  • Solicitudes con nombre
  • Especificar la ruta de acceso del archivo como cuerpo de la solicitud
  • Formato mixto para el cuerpo cuando se usan datos de varias partes o formularios
  • Solicitudes de GraphQL
  • Solicitud cURL
  • Copiar y pegar como cURL
  • Historial de solicitudes
  • Guardar el cuerpo de la respuesta en el archivo
  • Autenticación basada en certificados
  • Solicitud de variables
  • Personalización de la vista previa de respuesta
  • Configuración de cada solicitud

Creación de un archivo .http

  • En el Explorador de soluciones, haga clic con el botón derecho en un proyecto de ASP.NET Core.

  • En el menú contextual, seleccione Agregar>Nuevo elemento.

  • En el cuadro de diálogo Agregar nuevo elemento, seleccione ASP.NET Core>General.

  • Seleccione Archivo HTTP y después Agregar.

    Add New Item dialog showing HTTP File type selected.

Envíe una solicitud HTTP

  • Agregue al menos una solicitud a un archivo .http y guárdelo.

  • Si la dirección URL de la solicitud apunta a localhost y al puerto del proyecto, ejecute el proyecto antes de intentar enviarle una solicitud.

  • Seleccione el vínculo Send Request o Debug situado directamente encima de la solicitud que se va a enviar.

    La solicitud se envía a la dirección URL especificada y la respuesta aparece en un panel independiente a la derecha de la ventana del editor.

    .http file editor window with 'run' button highlighted and showing the response pane.

Opciones de archivos .http

Se pueden configurar algunos aspectos del comportamiento de los archivos .http. Para ver lo que está disponible, vaya a Herramientas>Opciones>Editor de texto>Rest. Por ejemplo, la opción de tiempo de espera se puede configurar en la pestaña Avanzada. Esta es una captura de pantalla del cuadro de diálogo Opciones:

Options dialog showing Text Editor and Rest selection.

Uso del Explorador de puntos de conexión

El Explorador de puntos de conexión es una ventana de herramientas de Visual Studio 2022 que proporciona una interfaz de usuario que se integra con el editor de archivos .http para probar solicitudes HTTP.

Apertura del Explorador de puntos de conexión

Seleccione Ver>Otras ventanas>Explorador de puntos de conexión.

Adición de una solicitud a un archivo .http

Haga clic con el botón derecho en una solicitud en el Explorador de puntos de conexión y seleccione Generar solicitud.

Endpoints Explorer window showing request context menu with 'Generate Request' menu selection highlighted.

  • Si existiera un archivo .http con el nombre del proyecto como nombre de archivo, la solicitud se agregará a ese archivo.
  • En caso contrario, se creará un archivo .http con el nombre del proyecto como nombre de archivo y la solicitud se agregará a ese archivo.

En la captura de pantalla anterior se muestran los puntos de conexión definidos por la plantilla de proyecto de API mínima. En el ejemplo siguiente se muestra la solicitud que se genera para el punto de conexión seleccionado:

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

###

Envíe la solicitud como se ha descrito antes en este artículo.

Consulte también