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

Статья
01/23/2024

Редактор файлов 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, используемый, например:
- OPTIONS
- GET
- HEAD
- POST
- PUT
- PATCH
- DELETE
- TRACE
- CONNECT
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"
}

###

Переменные

Строка, начинающаяся с @ определения переменной с помощью синтаксиса @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 file editor with environment selector highlighted. The 'dev' environment is selected.

Файл среды не должен находиться в папке проекта. 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]}}, где maxmin значения являются необязательными.

Дата и время

$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] находится в виде numbernumberunit целого числа и 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 поведения файла. Чтобы узнать, что доступно, перейдите в текстовый редактор> параметров>инструментов.> Например, параметр времени ожидания можно настроить на вкладке "Дополнительно ". Ниже приведен снимок экрана диалогового окна "Параметры" :

Options dialog showing Text Editor and Rest selection.

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

Конечные точки Обозреватель — это окно инструментов в Visual Studio 2022, которое предоставляет пользовательский интерфейс, который интегрируется с редактором .http файлов для тестирования HTTP-запросов.

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

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

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

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

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

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

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

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

###

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

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

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

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

Запросы

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

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

Комментарии

Переменные

Файлы среды

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

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

Azure Key Vault

Шифрование DPAPI

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

файлы `.env`;

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

Дата и время

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

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

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

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

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

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

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

См. также

Обратная связь

Дополнительные ресурсы

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

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

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

Запросы

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

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

Комментарии

Переменные

Файлы среды

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

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

Azure Key Vault

Шифрование DPAPI

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

файлы .env;

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

Дата и время

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

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

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

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

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

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

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

См. также

Обратная связь

Дополнительные ресурсы

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

файлы `.env`;

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

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

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