Использование HTTP-файлов в Visual Studio 2022
Редактор файлов Visual Studio 2022.http
предоставляет удобный способ тестирования проектов ASP.NET Core, особенно приложений API. Редактор предоставляет пользовательский интерфейс, который:
- Создает и обновляет
.http
файлы. - Отправляет HTTP-запросы, указанные в
.http
файлах. - Отображает ответы.
В этой статье содержится документация по следующим причинам:
- Синтаксис
.http
файла. .http
Создание файла.- Как отправить запрос из
.http
файла. - Где найти
.http
параметры файла, которые можно настроить.. - Создание запросов в
.http
файлах с помощью Обозреватель конечных точек Visual Studio 2022.
Формат .http
файла и редактор были вдохновлены расширением клиента Visual Studio CodeREST. Редактор Visual Studio 2022 .http
распознает .rest
как альтернативное расширение файла для того же формата файла.
Необходимые компоненты
- Visual Studio 2022 версии 17.8 или более поздней версии с установленной рабочей нагрузкой ASP.NET и веб-разработки .
.http
Синтаксис файла
В следующих разделах объясняется .http
синтаксис файла.
Запросы
Формат HTTP-запроса — HTTPMethod URL HTTPVersion
это все в одной строке, где:
HTTPMethod
— это метод HTTP, используемый, например:URL
— ЭТО URL-адрес для отправки запроса. URL-адрес может включать параметры строки запроса. URL-адрес не должен указывать на локальный веб-проект. Он может указать любой URL-адрес, к которому может получить доступ Visual Studio.HTTPVersion
является необязательным и указывает http-версию, которая должна использоваться, то есть ,HTTP/1.1
HTTP/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
файлов. На следующем снимка экрана показан селектор:
Файл среды не должен находиться в папке проекта. 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]}}
том, что параметры формата и смещения являются необязательными.$localDatetime
datetime
создает строку в локальном часовом поясе. Синтаксис заключается в{{$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.org.
Неподдерживаемый синтаксис
В редакторе файлов Visual Studio 2022 .http
нет всех функций, которые имеет расширение клиента Visual Studio CodeREST. В следующем списке перечислены некоторые из более важных функций, доступных только в расширении Visual Studio Code:
- Строка запроса, которая охватывает несколько строк
- Именованные запросы
- Укажите путь к файлу в виде текста запроса
- Смешанный формат для текста при использовании многопартийных или форм-данных
- Запросы GraphQL
- Запрос cURL
- Копирование и вставка как cURL
- Журнал запросов
- Сохранение текста ответа в файл
- Проверка подлинности на основе сертификата
- Переменные запроса
- Настройка предварительной версии ответа
- Параметры для каждого запроса
Создание файла .http
В Обозреватель решений щелкните правой кнопкой мыши проект ASP.NET Core.
В контекстном меню выберите "Добавить>новый элемент".
В диалоговом окне "Добавить новый элемент" выберите ASP.NET Core>General.
Выберите HTTP-файл и нажмите кнопку "Добавить".
Отправка HTTP-запроса
Добавьте хотя бы один запрос в
.http
файл и сохраните файл.Если URL-адрес запроса указывает на localhost и порт проекта, запустите проект перед отправкой запроса в него.
Выберите или
Debug
ссылкуSend Request
, которая находится непосредственно над отправленным запросом.Запрос отправляется по указанному URL-адресу, а ответ отображается в отдельной области справа от окна редактора.
.http
Параметры файла
Можно настроить некоторые аспекты .http
поведения файла. Чтобы узнать, что доступно, перейдите в текстовый редактор> параметров>инструментов.> Например, параметр времени ожидания можно настроить на вкладке "Дополнительно ". Ниже приведен снимок экрана диалогового окна "Параметры" :
Использование конечных точек Обозреватель
Конечные точки Обозреватель — это окно инструментов в Visual Studio 2022, которое предоставляет пользовательский интерфейс, который интегрируется с редактором .http
файлов для тестирования HTTP-запросов.
Открытие конечных точек Обозреватель
Выберите "Просмотреть>другие конечные точки Windows>" Обозреватель.
Добавление запроса в .http
файл
Щелкните правой кнопкой мыши запрос в конечных точках Обозреватель и выберите "Создать запрос".
.http
Если файл с именем проекта в качестве имени файла существует, запрос добавляется в этот файл..http
В противном случае файл создается с именем проекта в качестве имени файла, а запрос добавляется в этот файл.
На предыдущем снимке экрана показаны конечные точки, определенные минимальным шаблоном проекта API. В следующем примере показан запрос, созданный для выбранной конечной точки:
GET {{WebApplication1_HostAddress}}/weatherforecast/
Accept: application/json
###
Отправьте запрос, как описано ранее в этой статье.
См. также
ASP.NET Core
Обратная связь
https://aka.ms/ContentUserFeedback.
Ожидается в ближайшее время: в течение 2024 года мы постепенно откажемся от GitHub Issues как механизма обратной связи для контента и заменим его новой системой обратной связи. Дополнительные сведения см. в разделеОтправить и просмотреть отзыв по