Использование HTTP-файлов в Visual Studio 2022

  • Статья

Редактор файлов Visual Studio 2022 .http предоставляет удобный способ тестирования проектов ASP.NET Core, особенно приложений API. Редактор предоставляет пользовательский интерфейс, который:

  • Создает и обновляет .http файлы.
  • Отправляет HTTP-запросы, указанные в .http файлах.
  • Отображает ответы.

В этой статье содержится документация по следующим причинам:

Формат .http файла и редактор были вдохновлены расширением клиента Visual Studio CodeREST. Редактор Visual Studio 2022 .http распознает .rest как альтернативное расширение файла для того же формата файла.

Необходимые компоненты

.http Синтаксис файла

В следующих разделах объясняется .http синтаксис файла.

Запросы

Формат HTTP-запроса — HTTPMethod URL HTTPVersionэто все в одной строке, где:

  • HTTPMethod — это метод HTTP, используемый, например:
  • URL — ЭТО URL-адрес для отправки запроса. URL-адрес может включать параметры строки запроса. URL-адрес не должен указывать на локальный веб-проект. Он может указать любой URL-адрес, к которому может получить доступ Visual Studio.
  • HTTPVersionявляется необязательным и указывает http-версию, которая должна использоваться, то есть , HTTP/1.1HTTP/2или HTTP/3.

Файл может содержать несколько запросов с помощью строк с ### разделителями. В следующем примере с тремя запросами в файле показан следующий синтаксис:

GET https://localhost:7220/weatherforecast

###

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

###

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

###

Заголовки запросов

Чтобы добавить один или несколько заголовков, добавьте каждый заголовок в собственную строку сразу после строки запроса. Не включать пустые строки между строкой запроса и первым заголовком или между последующими строками заголовков. Формат представлен HeaderName: Value, как показано в следующих примерах:

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

###

Внимание

При вызове API, выполняющего проверку подлинности с заголовками, не фиксируйте секреты в репозитории исходного кода. См. поддерживаемые методы хранения секретов далее в этой статье, такие как ASP.NET секреты пользователей Core, шифрование Azure Key Vault и DPAPI.

Текст запроса

Добавьте текст запроса после пустой строки, как показано в следующем примере:

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

###

Комментарии

Строки, начинающиеся с любого или # // являются комментариями. Эти строки игнорируются при отправке HTTP-запросов Visual Studio.

Переменные

Строка, начинающаяся с @ определения переменной с помощью синтаксиса @VariableName=Value.

На переменные можно ссылаться в запросах, определенных позже в файле. Они ссылаются, упаковав их имена в двойные фигурные скобки, {{ и }}. В следующем примере показаны две переменные, определенные и используемые в запросе:

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

Переменные можно определить с помощью значений других переменных, которые были определены ранее в файле. В следующем примере используется одна переменная в запросе вместо двух, показанных в предыдущем примере:

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

Файлы среды

Чтобы дать переменным разные значения в разных средах, создайте файл с именем http-client.env.json. Найдите файл в том же каталоге, что .http и файл или в одном из родительских каталогов. Ниже приведен пример файла среды:

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

Файл среды — это JSON-файл, содержащий одну или несколько именованных сред, например "dev" и "remote" в предыдущем примере. Каждая именованной среда содержит одну или несколько переменных, например HostAddress в предыдущем примере. Переменные из файла среды ссылаются так же, как и на другие переменные, как показано в следующем примере:

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

Значение, используемое для переменной при отправке запроса, определяется раскрывающимся списком селектора среды в правом верхнем углу редактора .http файлов. На следующем снимка экрана показан селектор:

Редактор HTTP-файлов с выделенным селектором среды. Выбрана среда разработки.

Файл среды не должен находиться в папке проекта. Visual Studio ищет файл среды в папке, в которой .http существует файл. Если он не находится в этой папке, Visual Studio просматривает родительские каталоги, чтобы найти его. Когда найден файл с именем http-client.env.json , поиск заканчивается. Используется файл, ближайший к файлу .http .

После создания или редактирования .http файла может потребоваться закрыть и повторно открыть проект, чтобы увидеть изменения, отраженные в селекторе среды. Нажмите клавишу F6 , чтобы выбрать селектор среды.

Visual Studio отображает предупреждения в следующих ситуациях:

  • Файл .http ссылается на переменную, которая не определена в .http файле или в файле среды.
  • Файл среды содержит переменную, на которую не ссылается .http файл.

Переменная, определенная в файле среды, может быть той же, что .http и в файле, или может отличаться. Если переменная определена как в файле, так .http и в файле среды, значение в .http файле переопределяет значение в файле среды.

Файлы среды для конкретного пользователя

Определенное пользователем значение — это любое значение, которое отдельный разработчик хочет протестировать, но не хочет поделиться с командой. http-client.env.json Так как файл по умолчанию установлен в систему управления версиями, он не подходит для добавления в этот файл определенных пользователем значений. Вместо этого поместите их в файл с именем http-client.env.json.user , расположенным в той же папке, что http-client.env.json и файл. Файлы, которые заканчиваются .user , должны быть исключены из системы управления версиями по умолчанию при использовании функций управления версиями Visual Studio.

http-client.env.json При загрузке файла Visual Studio ищет одноуровневый http-client.env.json.user файл. Если переменная определена в среде как в файле, так http-client.env.json и http-client.env.json.user в файле, значение в http-client.env.json.user файле выигрывает.

Ниже приведен пример сценария, в котором показано, как работает файл среды для конкретного пользователя. Предположим, что .http файл содержит следующее содержимое:

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

И предположим, что http-client.env.json файл содержит следующее содержимое:

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

И предположим, что есть файл среды для конкретного пользователя, содержащий следующее содержимое:

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

Когда пользователь выбирает среду разработки, запрос отправляется https://localhost:7128/swagger/index.html , так как Path значение в http-client.env.json.user файле переопределяет значение из http-client.env.json файла.

С теми же файлами среды предположим, что переменные определены в .http файле:

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

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

В этом сценарии запрос среды разработки отправляется https://contoso.com/weatherforecast , так как определения переменных в .http файлах переопределяют определения файлов среды.

секреты пользователей ASP.NET Core

Чтобы получить значение из секретов пользователя, используйте файл среды, расположенный в той же папке, что и проект ASP.NET Core. В файле среды определите переменную, которая имеет provider и secretName свойства. provider Задайте значение AspnetUserSecrets и задайте secretName имя требуемого секрета пользователя. Например, следующий файл среды определяет переменную с именем ApiKeyDev , которая получает значение из секрета config:ApiKeyDev пользователя:

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

Чтобы использовать эту переменную в .http файле, сослаться на нее как на стандартную переменную. Например:

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

При отправке запроса значение ApiKeyDev секрета находится в заголовке X-API-KEY.

При вводе http в файл редактор отображает список завершения для имени переменной, но не отображает его значение.

Azure Key Vault

Azure Key Vault — это одно из нескольких решений по управлению ключами в Azure, которые можно использовать для управления секретами. Из трех хранилищ секретов, поддерживаемых в настоящее время для .http файлов, Key Vault является лучшим выбором для совместного доступа к секретам для разных пользователей. Другие два варианта — ASP.NET секреты пользователей и шифрование DPAPI — это не просто общий доступ.

Чтобы использовать значение из Azure Key Vault, необходимо войти в Visual Studio с учетной записью, которая имеет доступ к нужному Хранилищу ключей. Определите переменную в файле среды с метаданными для доступа к секрету. Переменная называется AKVSecret в следующем примере:

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

Переменная AKVSecret извлекает значение из Azure Key Vault. Для следующих свойств определены AKVSecretследующие свойства:

Имя Описание
поставщик Для Key Vault всегда используйте AzureKeyVault.
secretName; Имя секрета для извлечения.
resourceId Идентификатор ресурса Azure для доступа к конкретному хранилищу ключей.

Значение свойства resourceId можно найти в портал Azure. Перейдите к свойствам > параметров , чтобы найти его. Для secretNameэтого используйте имя секрета, отображаемого на странице секретов в портал Azure.

Например, следующий .http файл содержит запрос, использующий это значение секрета.

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

Шифрование DPAPI

В Windows существует API защиты данных (DPAPI), который можно использовать для шифрования конфиденциальных данных. Если DPAPI используется для шифрования данных, зашифрованные значения всегда зависят от компьютера, и они также зависят от пользователя в .http файлах. Эти значения нельзя предоставить другим пользователям.

Чтобы зашифровать значение, используйте следующее консольное приложение:

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

Предыдущее консольное приложение ссылается на пакет NuGet System.Security.Cryptography.ProtectedData . Чтобы включить зашифрованное значение для работы в .http файле, зашифруйте область с заданным значением DataProtectionScope.CurrentUser. Зашифрованное значение — это строка в кодировке Base64, которую можно скопировать и вставить в файл среды.

В файле среды создайте переменную, которая имеет provider и value свойства. EncryptedЗадайте provider значение ,и задайте value зашифрованное значение. Например, следующий файл среды определяет переменную с именем dpapiValue , которая получает значение из строки, зашифрованной с помощью DPAPI.

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

С помощью предыдущего файла dpapiValue среды можно использовать в .http файле, как и любую другую переменную. Например:

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

При отправке этого запроса X-DPAPI-Secret имеет расшифрованное значение секрета.

Переменные среды

Чтобы получить значение переменной среды, используйте $processEnv. В следующем примере значение переменной среды USERNAME помещает в заголовок X-UserName.

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

Если вы пытаетесь получить $processEnv доступ к переменной среды, которая не существует, .http редактор файлов отображает сообщение об ошибке.

файлы .env;

Чтобы получить значение переменной, определенной .env в файле, используйте $dotenv. Файл .env должен находиться в папке проекта. Формат для $dotenv этого совпадает $processEnvс форматом. Например, если .env файл содержит это содержимое:

USERNAME=userFromDotenv

Файл содержит следующее содержимое .http :

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

Заголовок X-UserName будет иметь "userFromDotenv".

При $dotenv вводе в редактор отображается завершение переменных, определенных в .env файле.

Примечание.

.env Файлы могут не быть исключены из системы управления версиями по умолчанию, поэтому будьте осторожны, чтобы избежать проверки значений секретов.

Случайные целые числа

Чтобы создать случайное целое число, используйте $randomInt. Синтаксис заключается в том{{$randomInt [min max]}}, где max min значения являются необязательными.

Дата и время

  • $datetime создает datetime строку в формате UTC. Синтаксис заключается в {{$datetime [format] [offset option]}} том, что параметры формата и смещения являются необязательными.
  • $localDatetimedatetime создает строку в локальном часовом поясе. Синтаксис заключается в {{$localDatetime [format] [offset option]}} том, что параметры формата и смещения являются необязательными.
  • $timeStamp создает объект timestamp в формате UTC. Количество timestamp секунд с эпохи Unix в формате UTC. Синтаксис заключается в {{$timestamp [offset option]}} том, что параметр смещения является необязательным.

Параметр [format] является одним из rfc1123вариантов или iso8601настраиваемым форматом в кавычках. Например:

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

Ниже приведены некоторые примеры значений, которые создаются в предыдущих примерах:

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

Синтаксис [offset option] находится в виде number number unit целого числа и unit является одним из следующих значений:

unit Описание
ms Миллисекунды
s сек.
m Минуты
h часов
d Днях
w Неделянедели
M Месяцы
y Годы

Например:

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

Ниже приведены некоторые примеры значений, которые создаются в предыдущих примерах:

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

В некоторых из предыдущих примеров используется бесплатный веб-сайт <с открытым исходным кодом httpbin.org>. Это сторонний веб-сайт, не связанный с корпорацией Майкрософт. В этих примерах возвращается текст ответа с заголовками, отправленными в запросе. Сведения о других способах использования этого ресурса для тестирования API см. на странице сайта httpbin.orghome.

Неподдерживаемый синтаксис

В редакторе файлов Visual Studio 2022 .http нет всех функций, которые имеет расширение клиента Visual Studio CodeREST. В следующем списке перечислены некоторые из более важных функций, доступных только в расширении Visual Studio Code:

  • Строка запроса, которая охватывает несколько строк
  • Именованные запросы
  • Укажите путь к файлу в виде текста запроса
  • Смешанный формат для текста при использовании многопартийных или форм-данных
  • Запросы GraphQL
  • Запрос cURL
  • Копирование и вставка как cURL
  • Журнал запросов
  • Сохранение текста ответа в файл
  • Проверка подлинности на основе сертификата
  • Переменные запроса
  • Настройка предварительной версии ответа
  • Параметры для каждого запроса

Создание файла .http

  • В Обозреватель решений щелкните правой кнопкой мыши проект ASP.NET Core.

  • В контекстном меню выберите "Добавить>новый элемент".

  • В диалоговом окне "Добавить новый элемент" выберите ASP.NET Core>General.

  • Выберите HTTP-файл и нажмите кнопку "Добавить".

    Диалоговое окно добавления нового элемента с выбранным типом HTTP-файла.

Отправка HTTP-запроса

  • Добавьте хотя бы один запрос в .http файл и сохраните файл.

  • Если URL-адрес запроса указывает на localhost и порт проекта, запустите проект перед отправкой запроса в него.

  • Выберите или Debug ссылкуSend Request, которая находится непосредственно над отправленным запросом.

    Запрос отправляется по указанному URL-адресу, а ответ отображается в отдельной области справа от окна редактора.

    Окно редактора http-файлов с выделенной кнопкой

.http Параметры файла

Можно настроить некоторые аспекты .http поведения файла. Чтобы узнать, что доступно, перейдите в текстовый редактор>Rest параметров>инструментов.> Например, параметр времени ожидания можно настроить на вкладке "Дополнительно ". Ниже приведен снимок экрана диалогового окна "Параметры" :

Диалоговое окно

Использование обозревателя конечных точек

Обозреватель конечных точек — это окно инструментов, показывающее все конечные точки, которые определяет веб-API. Средство позволяет отправлять запросы конечным точкам с помощью .http файла.

Начальный набор конечных точек, отображаемых в обозревателе конечных точек, обнаруживается статически. Существуют некоторые конечные точки, которые не могут быть обнаружены статически. Например, конечные точки, определенные в проекте библиотеки классов, не могут быть обнаружены до тех пор, пока среда выполнения не будет обнаружена. При запуске или отладке веб-API Visual Studio версии 17.11 Preview обнаруживает конечные точки динамически во время выполнения и добавляет их в обозреватель конечных точек.

Открытие обозревателя конечных точек

Выберите "Просмотреть>другие конечные точки Windows".>

Добавление запроса в .http файл

Щелкните правой кнопкой мыши запрос в обозревателе конечных точек и выберите "Создать запрос".

Окно обозревателя конечных точек с выделенным меню контекстного меню запроса с выделенным меню

  • .http Если файл с именем проекта в качестве имени файла существует, запрос добавляется в этот файл.
  • .http В противном случае файл создается с именем проекта в качестве имени файла, а запрос добавляется в этот файл.

На предыдущем снимке экрана показаны конечные точки, определенные минимальным шаблоном проекта API. В следующем примере показан запрос, созданный для выбранной конечной точки:

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

###

Отправьте запрос, как описано ранее в этой статье.

См. также