共用方式為


在 Visual Studio 2022 中使用 .http 檔案

Visual Studio 2022.http 檔案編輯器提供方便的方式來測試 ASP.NET Core 專案,特別是 API 應用程式。 編輯器提供的 UI 可:

  • 建立和更新 .http 檔案。
  • 傳送 .http 檔案中指定的 HTTP 要求。
  • 顯示回應。

本文包含下列內容的文件:

.http 檔案格式和編輯器受到 Visual Studio Code REST 用戶端延伸模組的啟發。 Visual Studio 2022 .http 編輯器會將 .rest 辨識為相同檔案格式的替代副檔名。

必要條件

.http 檔案語法

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

要求

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

  • HTTPMethod 是要使用的 HTTP 方法,例如:
  • URL 是要傳送要求的目標 URL。 URL 可以包含查詢字串參數。 URL 不一定必須指向本機 Web 專案。 它可以指向 Visual Studio 可以存取的任何 URL。
  • HTTPVersion 是選用,並指定應該使用的 HTTP 版本,也就是 HTTP/1.1HTTP/2HTTP/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 VaultDPAPI 加密

要求本文

在空白行後面新增要求本文,如下列範例所示:

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 專案相同資料夾中的環境檔案。 在環境檔案中,定義具有 providersecretName 屬性的變數。 將 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 編碼字串,可以複製並貼到環境檔案中。

在環境檔案中,建立具有 providervalue 屬性的變數。 將 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]}},其中 minmax 值是選擇性的。

日期和時間

  • $datetime 會產生 UTC 格式的 datetime 字串。 語法是 {{$datetime [format] [offset option]}},其中格式和位移選項是選擇性的。
  • $localDatetime 會產生當地時區的 datetime 字串。 語法是 {{$localDatetime [format] [offset option]}},其中格式和位移選項是選擇性的。
  • $timeStamp 會產生 UTC 格式的 timestamptimestampUnix Epoch 以來的秒數 (UTC 時間格式)。 語法是 {{$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] 語法的格式為 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 要求

  • 將至少一個要求新增至 .http 檔案並儲存檔案。

  • 如果要求 URL 指向 localhost 和專案的連接埠,請先執行專案,再嘗試傳送要求給它。

  • 選取 Send RequestDebug 連結,直接高於要傳送的要求。

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

    醒目提示 [執行] 按鈕並顯示回應窗格的 .http 檔案編輯器視窗。

.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

###

本文稍早所述傳送要求。

另請參閱