Visual Studio 2022 で .http ファイルを使う

[アーティクル]
11/06/2024

Visual Studio 2022 の .http ファイルエディターは、ASP.NET Core プロジェクト (特に API アプリ) をテストするための便利な方法です。エディターには、次のような UI が用意されています。

.http ファイルを作成および更新する。
.http ファイルで指定した HTTP 要求を送信する。
応答を表示する。

この記事には、以下に関するドキュメントが含まれています。

.http ファイルの構文。
.http ファイルを作成する方法。
.http ファイルから要求を送信する方法。
構成できる .http ファイルのオプションを見つける場所。
Visual Studio 2022 エンドポイントエクスプローラーを使って .http ファイルに要求を作成する方法。

.http ファイルの形式とエディターは、Visual Studio Code の REST Client 拡張機能に影響を受けています。 Visual Studio 2022 の .http エディターでは、.rest が同じファイル形式の代替ファイル拡張子として認識されます。

前提条件

Visual Studio 2022 バージョン 17.8 以降と ASP.NET および Web 開発ワークロードがインストールされていること。

`.http` ファイルの構文

以下のセクションでは、.http ファイルの構文について説明します。

Requests

HTTP 要求の形式は、1 行で HTTPMethod URL HTTPVersion となります。ここで:

HTTPMethod は使用する HTTP メソッドです。例:
- OPTIONS
- GET
- HEAD
- POST
- PUT
- PATCH
- DELETE
- TRACE
- CONNECT
URL は要求の送信先となる URL です。 URL にはクエリ文字列パラメーターを含めることができます。 URL はローカル Web プロジェクトを指す必要はありません。 Visual Studio がアクセスできる任意の URL を指すことができます。
HTTPVersion は省略可能で、使用する必要がある HTTP バージョン (HTTP/1.1、HTTP/2、または HTTP/3) を指定します。

複数の行と ### を区切り記号として使うことで、ファイルに複数の要求を含めることができます。 1 つのファイル内の 3 つの要求を示す次の例は、この構文を示しています。

GET https://localhost:7220/weatherforecast

###

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

###

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

###

要求ヘッダー

1 つ以上のヘッダーを追加するには、要求の行の直後に、各ヘッダーを独自の行で追加します。要求の行と最初のヘッダーとの間、または後続のヘッダーの各行の間には、空白行を含めないでください。次の例に示すように、その形式は 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"
}

###

Comments

# または // で始まる行はコメントです。これらの行は、Visual Studio が HTTP 要求を送信する際には無視されます。

変数

@ で始まる行は、@VariableName=Value という構文を使って変数を定義します。

変数は、その後にファイルで定義される要求で参照できます。それらは、その名前を二重の中かっこ {{ と }} で囲むことによって参照されます。次の例は、2 つの変数を定義して要求で使用しています。

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

変数は、ファイルで以前に定義された他の変数の値を使って定義できます。次の例では、要求で前の例に示した 2 つの変数ではなく、1 つの変数を使用しています。

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

環境ファイルは、1 つ以上の名前付き環境 (前の例の "dev" や "remote" など) が含まれている JSON ファイルです。各名前付き環境には、1 つ以上の変数 (前の例の 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 ファイルと同じフォルダーにある http-client.env.json.user という名前のファイルに配置します。 .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"
  }
}

ユーザーが "dev" 環境を選択すると、http-client.env.json.user ファイル内の Path 値によって http-client.env.json ファイルの値がオーバーライドされるため、その要求は https://localhost:7128/swagger/index.html に送信されます。

同じ環境ファイルを使用して、.http ファイルで次の変数が定義されているとします。

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

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

このシナリオでは、.http ファイル内の変数定義によって環境ファイルの定義がオーバーライドされるため、"dev" 環境の要求は https://contoso.com/weatherforecast に送信されます。

ASP.NET Core ユーザーシークレット

ユーザーシークレットから値を取得するには、ASP.NET Core プロジェクトと同じフォルダーにある環境ファイルを使用します。環境ファイルで、provider と secretName のプロパティを持つ変数を定義します。 provider 値を AspnetUserSecrets に設定し、secretName を目的のユーザーシークレットの名前に設定します。たとえば、次の環境ファイルでは、config:ApiKeyDev ユーザーシークレットからその値を取得する ApiKeyDev という名前の変数を定義します。

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

この変数を .http ファイルで使用するには、それを標準変数と同様に参照します。次に例を示します。

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

この要求が送信されるときは、X-API-KEY ヘッダー内に ApiKeyDev シークレットの値が存在します。

http ファイルで入力すると、エディターに変数名の入力候補一覧が表示されますが、その値は表示されません。

Azure Key Vault

Azure Key Vault は、シークレットの管理に使用できる Azure のいくつかのキー管理ソリューションの 1 つです。 .http ファイルで現在サポートされている 3 つのシークレットストアのうち、Key Vault は、異なるユーザー間でシークレットを共有するための最適な選択肢です。他の 2 つのオプションである ASP.NET ユーザーシークレットと DPAPI 暗号化は、簡単には共有されません。

Azure Key Vault の値を使用するには、目的の 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 では、次のプロパティが定義されています。

名前	説明
provider	Key Vault の場合は、常に `AzureKeyVault` を使用します。
secretName	抽出するシークレットの名前。
resourceId	アクセスする特定の Key Vault の Azure リソース ID。

resourceId プロパティの値は、Azure portal で見つけることができます。 [設定] > [プロパティ] に移動して見つけます。 secretName については、Azure portal の [シークレット] ページに表示されるシークレットの名前を使用します。

たとえば、次の .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);

前のコンソールアプリケーションでは、System.Security.Cryptography.ProtectedData NuGet パッケージを参照します。暗号化された値が .http ファイルで機能できるようにするには、スコープが DataProtectionScope.CurrentUser に設定された状態で暗号化します。暗号化された値は、コピーして環境ファイルに貼り付けることができる Base64 でエンコードされた文字列です。

環境ファイルで、provider と value のプロパティを持つ変数を作成します。 provider を Encrypted に設定し、value を暗号化された値に設定します。たとえば、次の環境ファイルでは、DPAPI で暗号化された文字列からその値を取得する dpapiValue という名前の変数を定義します。

{
  "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 を使用します。次の例では、X-UserName ヘッダー内に 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 ファイルで定義されている変数の入力候補が表示されます。

Note

.env ファイルは既定でソース管理から除外されない可能性があるため、シークレット値がチェックインされないように注意してください。

ランダムな整数

ランダムな整数を生成するには、$randomInt を使用します。その構文は {{$randomInt [min max]}} です。ここで、min と max の値は省略可能です。

日付と時刻

$datetime は、UTC での datetime 文字列を生成します。その構文は {{$datetime [format] [offset option]}} です。ここで、format と offset のオプションは省略可能です。
$localDatetime は、ローカルタイムゾーンでの datetime 文字列を生成します。その構文は {{$localDatetime [format] [offset option]}} です。ここで、format と offset のオプションは省略可能です。
$timeStamp は、UTC での timestamp を生成します。 timestamp は、UTC 時刻での Unix エポックからの秒数です。その構文は {{$timestamp [offset option]}} です。ここで、offset オプションは省略可能です。

[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 unit です。ここで、number は整数であり、unit は次の値のいずれかです。

`unit`	説明
`ms`	Milliseconds
`s`	秒
`m`	分
`h`	時間
`d`	日
`w`	週
`M`	Months
`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"
  }
}

前のいくつかの例では、無料のオープンソース Web サイト <httpbin.org> を使用しています。これは、Microsoft とは提携していないサードパーティの Web サイトです。これらの例では、要求で送信されたヘッダーを含む応答本文が返されます。このリソースを API テストに使用するための他の方法については、httpbin.org サイトのhome ページを参照してください。

サポートされていない構文

Visual Studio 2022 の .http ファイルエディターには、Visual Studio Code の REST クライアント拡張機能にあるすべての機能が含まれているわけではありません。 Visual Studio Code 拡張機能でのみ使用できる重要な機能の一部を、次の一覧に示します。

複数の行にまたがる要求の行
名前付き要求
要求の本文としてファイルパスを指定する
multipart/form-data を使う場合の本文の混合形式
GraphQL 要求
cURL 要求
cURL としてのコピー/貼り付け
要求履歴
応答本文をファイルに保存する
証明書ベースの認証
プロンプト変数
応答プレビューをカスタマイズする
要求ごとの設定

`.http` ファイルの作成

ソリューションエクスプローラーで、ASP.NET Core プロジェクトを右クリックします。
コンテキストメニューで、[追加]>[新しい項目] を選択します。
[新しい項目の追加] ダイアログで、[ASP.NET Core]>[全般] を選択します。
[HTTP ファイル] を選択し、[追加] を選択します。

HTTP 要求を送信する

.http ファイルに少なくとも 1 つの要求を追加し、ファイルを保存します。
要求 URL が localhost とプロジェクトのポートを指している場合は、要求を送信する前にプロジェクトを実行します。
送信される要求の真上にある Send Request または Debug リンクを選択します。

要求は指定した URL に送信され、応答はエディターウィンドウの右側にある別のペインに表示されます。

`.http` ファイルのオプション

.http ファイルの動作のいくつかの側面は構成可能です。何が使用可能かを確認するには、[ツール]>[オプション]>[テキストエディター]>Rest に移動します。たとえば、タイムアウト設定は [詳細設定] タブで構成できます。[オプション] ダイアログのスクリーンショットを次に示します。

[オプション] ダイアログでの [テキストエディター] と Rest の選択。

エンドポイントエクスプローラーを使う

エンドポイントエクスプローラーは、Web API で定義されているすべてのエンドポイントを表示するツールウィンドウです。このツールを使用すると、.http ファイルを使用してエンドポイントに要求を送信できます。

エンドポイントエクスプローラーに表示されるエンドポイントの初期セットは、静的に検出されます。静的に検出できないエンドポイントもいくつかあります。たとえば、クラスライブラリプロジェクトで定義されたエンドポイントは、ランタイムまで検出できません。 Web API を実行またはデバッグすると、Visual Studio バージョン 17.11 Preview はエンドポイントを実行時に動的に検出し、それらをエンドポイントエクスプローラーに追加します。

エンドポイントエクスプローラーを開く

[ビュー]>[その他のウィンドウ]>[Endpoints Explorer] (エンドポイントエクスプローラー) の順に選択します。

`.http` ファイルに要求を追加する

エンドポイントエクスプローラーで要求を右クリックし、[Generate Request] (要求を生成する) を選択します。

要求のコンテキストメニューが表示されているエンドポイントエクスプローラーウィンドウ。[Generate Request] (要求を生成する) メニューの選択が強調表示されています。

ファイル名としてプロジェクト名を持つ .http ファイルが存在する場合は、そのファイルに要求が追加されます。
そうでなければ、ファイル名としてそのプロジェクト名を持つ .http ファイルが作成され、そのファイルに要求が追加されます。

上のスクリーンショットは、最小限の API プロジェクトテンプレートによって定義されたエンドポイントを示しています。次の例は、選択したエンドポイントに対して生成される要求を示しています。

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

###

この記事で前述したように、要求を送信します。

次の方法で共有

Visual Studio 2022 で .http ファイルを使う

前提条件

`.http` ファイルの構文

Requests

要求ヘッダー

要求本文

Comments

変数

環境ファイル

ユーザー固有の環境ファイル

ASP.NET Core ユーザーシークレット

Azure Key Vault

DPAPI 暗号化

環境変数

`.env` ファイル

ランダムな整数

日付と時刻

サポートされていない構文

`.http` ファイルの作成

HTTP 要求を送信する

`.http` ファイルのオプション

エンドポイントエクスプローラーを使う

エンドポイントエクスプローラーを開く

`.http` ファイルに要求を追加する

関連項目

その他のリソース

次の方法で共有

Visual Studio 2022 で .http ファイルを使う

前提条件

.http ファイルの構文

Requests

要求ヘッダー

要求本文

Comments

変数

環境ファイル

ユーザー固有の環境ファイル

ASP.NET Core ユーザー シークレット

Azure Key Vault

DPAPI 暗号化

環境変数

.env ファイル

ランダムな整数

日付と時刻

サポートされていない構文

.http ファイルの作成

HTTP 要求を送信する

.http ファイルのオプション

エンドポイント エクスプローラーを使う

エンドポイント エクスプローラーを開く

.http ファイルに要求を追加する

関連項目

その他のリソース

`.http` ファイルの構文

ASP.NET Core ユーザーシークレット

`.env` ファイル

`.http` ファイルの作成

`.http` ファイルのオプション

エンドポイントエクスプローラーを使う

エンドポイントエクスプローラーを開く

`.http` ファイルに要求を追加する