在 Visual Studio 2022 中使用 .http 檔案
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
辨識為相同檔案格式的替代副檔名。
必要條件
.http
檔案語法
下列各節說明 .http
檔案語法。
要求
HTTP 要求的格式為 HTTPMethod URL HTTPVersion
,全部在一行上,其中:
HTTPMethod
是要使用的 HTTP 方法,例如: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
的環境選取器下拉式清單所決定。 下列螢幕快照顯示選取器:
環境檔案不一定位於項目資料夾中。 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]
是、 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 網站的首頁。
不支援的語法
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]。 例如,您可以在 [進階] 索引標籤上設定逾時設定。以下是 [選項] 對話框的螢幕快照:
使用端點總管
[端點總管] 是 Visual Studio 2022 中的工具視窗,提供的 UI 與 .http
檔案編輯器整合以便測試 HTTP 要求。
開啟端點總管
選取 [檢視]> [其他視窗]> [端點總管]。
將要求新增至 .http
檔案
以滑鼠右鍵按一下 [端點總管] 中的要求,然後選取 [產生要求]。
- 如果存在使用專案名稱做為檔案名稱的
.http
檔案,要求就會新增至該檔案。 - 否則,會使用專案名稱做為檔案名來建立
.http
檔案,並將要求新增至該檔案。
上述螢幕擷取畫面顯示基本 API 專案範本定義的端點。 下列範例顯示針對所選端點產生的要求:
GET {{WebApplication1_HostAddress}}/weatherforecast/
Accept: application/json
###
如本文稍早所述傳送要求。
另請參閱
意見反應
https://aka.ms/ContentUserFeedback。
即將登場:在 2024 年,我們將逐步淘汰 GitHub 問題作為內容的意見反應機制,並將它取代為新的意見反應系統。 如需詳細資訊,請參閱:提交並檢視相關的意見反應