在 Visual Studio 2022 中使用 .http 檔案

發行項
01/23/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 和 Web 開發工作負載的 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 核心用戶密碼、Azure 金鑰保存庫和 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"
  }
}

環境檔案是 ON JS檔案，其中包含一或多個具名環境，例如上述範例中的 “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 檔案相同的資料夾中。使用 Visual Studio 原始檔控制功能時，預設應從原始檔控制排除結尾 .user 的檔案。

http-client.env.json載入檔案時，Visual Studio 會尋找同層級http-client.env.json.user檔案。如果在檔案和http-client.env.json.user檔案的環境中http-client.env.json定義變數，檔案中的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值會覆寫檔案http-client.env.json中的Path值。

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

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

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

在此案例中，「開發」環境要求會傳送至， https://contoso.com/weatherforecast 因為檔案中的 .http 變數定義會覆寫環境檔案定義。

ASP.NET 核心使用者秘密

若要從使用者秘密取得值，請使用位於與 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 金鑰保存庫是 Azure 中數個金鑰管理解決方案之一，可用於秘密管理。在目前支援.http檔案的三個秘密存放區中，金鑰保存庫是跨不同用戶共用秘密的最佳選擇。其他兩個選項-ASP.NET 用戶密碼和 DPAPI 加密-都不容易共用。

若要使用 Azure 金鑰保存庫的值，您必須使用具有所需金鑰保存庫存取權的帳戶登入 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 金鑰保存庫提取其值。下列屬性定義於上 AKVSecret：

名稱	描述
Provider - 提供者	針對金鑰保存庫，請一律使用 `AzureKeyVault`。
secretName	要擷取的秘密名稱。
resourceId	要存取之特定金鑰保存庫的 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 必須位於項目資料夾中。的格式與的$processEnv格式$dotenv相同。例如，如果 .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是UTC時間的Unix Epoch之後的秒數。語法是 {{$timestamp [offset option]}} 位移選項是選擇性的。

選項[format]是、 rfc1123iso8601或以引號表示的自訂格式之一。例如：

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] 的格式 numberunit 為，其中 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 網站的首頁。

不支援的語法

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]。 例如，您可以在 [進階] 索引標籤上設定逾時設定。以下是 [選項] 對話框的螢幕快照：

Options dialog showing Text Editor and Rest selection.

使用端點總管

[端點總管] 是 Visual Studio 2022 中的工具視窗，提供的 UI 與 .http 檔案編輯器整合以便測試 HTTP 要求。

開啟端點總管

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

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

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

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

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

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

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

###

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

在 Visual Studio 2022 中使用 .http 檔案

必要條件

`.http` 檔案語法

要求

要求標頭

要求本文

註解

變數

環境檔案

使用者特定環境檔案

ASP.NET 核心使用者秘密

Azure Key Vault

DPAPI 加密

環境變數

`.env` 檔

隨機整數

日期和時間

不支援的語法

建立 `.http` 檔案

傳送 HTTP 要求

`.http` 檔案選項

使用端點總管

開啟端點總管

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

另請參閱

意見反應

其他資源

在 Visual Studio 2022 中使用 .http 檔案

必要條件

.http 檔案語法

要求

要求標頭

要求本文

註解

變數

環境檔案

使用者特定環境檔案

ASP.NET 核心使用者秘密

Azure Key Vault

DPAPI 加密

環境變數

.env 檔

隨機整數

日期和時間

不支援的語法

建立 .http 檔案

傳送 HTTP 要求

.http 檔案選項

使用端點總管

開啟端點總管

將要求新增至 .http 檔案

另請參閱

意見反應

其他資源

`.http` 檔案語法

`.env` 檔

建立 `.http` 檔案

`.http` 檔案選項

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