在 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 用戶端延伸模組的啟發。 Visual Studio 2022 .http 編輯器會將 .rest 辨識為相同檔案格式的替代副檔名。

必要條件

已安裝具有 ASP.NET 與網頁程式開發工作負載的 Visual Studio 2022 17.8 版或更新版本。

`.http` 檔案語法

下列各節說明 .http 檔案語法。

要求

HTTP 要求的格式為 HTTPMethod URL HTTPVersion，全部在一行上，其中：

HTTPMethod 是要使用的 HTTP 方法，例如：
- OPTIONS
- 取得
- HEAD
- POST
- PUT
- PATCH
- DELETE
- TRACE
- CONNECT
URL 是要傳送要求的目標 URL。 URL 可以包含查詢字串參數。 URL 不一定必須指向本機 Web 專案。它可以指向 Visual Studio 可以存取的任何 URL。
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"
}

###

註解

開頭為 # 或 // 的行是註解。當 Visual Studio 傳送 HTTP 要求時，會忽略這些行。

變數

開頭為 @ 的行會使用 @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 檔案編輯器。已選取 'dev' 環境。

環境檔案不一定位於專案資料夾中。 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 檔案相同的資料夾中。使用 Visual Studio 原始檔控制功能時，預設應從原始檔控制排除以 .user 結尾的檔案。

載入 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" 環境時，要求會傳送至 https://localhost:7128/swagger/index.html，因為 http-client.env.json.user 檔案中的 Path 值會覆寫 http-client.env.json 檔案中的值。

使用相同的環境檔案，假設變數是在 .http 檔案中定義：

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

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

在此案例中，"dev" 環境要求會傳送至 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 的值，您必須使用可存取所需 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 資源識別碼。

您可以在 Azure 入口網站中找到 resourceId 屬性的值。移至 [設定] > [屬性] 以尋找它。針對 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);

上述主控台應用程式會參考 System.Security.Cryptography.ProtectedData NuGet 套件。若要讓加密值在 .http 檔案中運作，請使用設定為 DataProtectionScope.CurrentUser 的範圍進行加密。加密值是 base64 編碼字串，可以複製並貼到環境檔案中。

在環境檔案中，建立具有 provider 和 value 屬性的變數。將 provider 設定為 Encrypted，並將 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]}}，其中 min 和 max 值是選擇性的。

日期和時間

$datetime 會產生 UTC 格式的 datetime 字串。語法是 {{$datetime [format] [offset option]}}，其中格式和位移選項是選擇性的。
$localDatetime 會產生當地時區的 datetime 字串。語法是 {{$localDatetime [format] [offset option]}}，其中格式和位移選項是選擇性的。
$timeStamp 會產生 UTC 格式的 timestamp。 timestamp 是 Unix Epoch 以來的秒數 (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 unit，其中 number 是整數，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>。這是與 Microsoft 無關的第三方網站。在這些範例中，會傳回回應本文，其中包含要求中傳送的標頭。如需使用此資源進行 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 檔案並儲存檔案。
如果要求 URL 指向 localhost 和專案的連接埠，請先執行專案，再嘗試傳送要求給它。
選取 Send Request 或 Debug 連結，直接高於要傳送的要求。

要求會傳送至指定的 URL，而回應會出現在編輯器視窗右側的個別窗格中。

`.http` 檔案選項

您可以設定 .http 檔案行為的一些層面。若要查看可用項目，請移至 [工具]>[選項]>[文字編輯器]>Rest。例如，您可以在 [進階] 索引標籤上設定逾時設定。以下是 [選項] 對話方塊的螢幕擷取畫面：

選項對話方塊顯示文字編輯器和 Rest 選取項目。

使用端點總管

[端點總管] 是一個工具視窗，其中顯示 Web API 定義的所有端點。此工具可讓您使用 .http 檔案將要求傳送至端點。

[端點總管] 顯示的初始端點集會以靜態方式探索。有些端點無法以靜態方式探索。例如，直到執行階段，才能探索類別庫專案中定義的端點。當您執行或偵錯 Web API 時，Visual Studio 17.11 版 Preview 也會在執行階段動態探索端點，並將這些端點新增至 [端點總管]。

開啟端點總管

選取 [檢視] > [其他視窗] > [端點總管]。

將要求新增至 `.http` 檔案

以滑鼠右鍵按一下 [端點總管] 中的要求，然後選取 [產生要求]。

[端點總管] 視窗，其中顯示已醒目提示 [產生要求] 功能表選取項目的要求操作功能表。

如果存在使用專案名稱做為檔案名稱的 .http 檔案，要求就會新增至該檔案。
否則，會使用專案名稱做為檔案名來建立 .http 檔案，並將要求新增至該檔案。

上述螢幕擷取畫面顯示基本 API 專案範本定義的端點。下列範例顯示針對所選端點產生的要求：

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

###

如本文稍早所述傳送要求。

共用方式為

在 Visual Studio 2022 中使用 .http 檔案

必要條件

`.http` 檔案語法

要求

要求標頭

要求本文

註解

變數

環境檔案

使用者特定環境檔案

ASP.NET Core 使用者祕密

Azure Key Vault

DPAPI 加密

環境變數

`.env` 檔案

隨機整數

日期和時間

不支援的語法

建立 `.http` 檔案

傳送 HTTP 要求

`.http` 檔案選項

使用端點總管

開啟端點總管

將要求新增至 `.http` 檔案

另請參閱

其他資源

共用方式為

在 Visual Studio 2022 中使用 .http 檔案

必要條件

.http 檔案語法

要求

要求標頭

要求本文

註解

變數

環境檔案

使用者特定環境檔案

ASP.NET Core 使用者祕密

Azure Key Vault

DPAPI 加密

環境變數

.env 檔案

隨機整數

日期和時間

不支援的語法

建立 .http 檔案

傳送 HTTP 要求

.http 檔案選項

使用端點總管

開啟端點總管

將要求新增至 .http 檔案

另請參閱

其他資源

`.http` 檔案語法

`.env` 檔案

建立 `.http` 檔案

`.http` 檔案選項

將要求新增至 `.http` 檔案