Sử dụng file .http trong Visual Studio 2022

Trình soạn thảo file .http trong Visual Studio 2022 cung cấp một cách tiện lợi để kiểm thử (test) các dự án ASP.NET Core, đặc biệt là ứng dụng API. Trình soạn thảo cung cấp giao diện người dùng cho phép:

• Tạo và cập nhật file .http.
• Gửi các HTTP request (yêu cầu HTTP) được chỉ định trong file .http.
• Hiển thị các response (phản hồi).

Bài viết này bao gồm tài liệu về:

• Cú pháp file .http.
• Cách tạo file .http.
• Cách gửi request từ file .http.
• Nơi tìm các tùy chọn file .http có thể cấu hình.
• Cách tạo request trong file .http bằng Endpoints Explorer (Trình khám phá Endpoint) của Visual Studio 2022.

Định dạng file .http và trình soạn thảo được lấy cảm hứng từ tiện ích mở rộng REST Client của Visual Studio Code. Trình soạn thảo .http trong Visual Studio 2022 cũng nhận ra .rest là phần mở rộng thay thế cho cùng định dạng file.

Điều kiện tiên quyết

• Visual Studio 2022 phiên bản 17.8 trở lên với workload (khối công việc) ASP.NET and web development được cài đặt.

Cú pháp file .http

Các phần sau đây giải thích cú pháp file .http.

Request (Yêu cầu)

Định dạng cho một HTTP request là HTTPMethod URL HTTPVersion, tất cả trên một dòng, trong đó:

• HTTPMethod là phương thức HTTP cần sử dụng, ví dụ:
• OPTIONS
• GET
• HEAD
• POST
• PUT
• PATCH
• DELETE
• TRACE
• CONNECT
• URL là địa chỉ URL để gửi request đến. URL có thể bao gồm các tham số query string. URL không nhất thiết phải trỏ đến một dự án web cục bộ — có thể trỏ đến bất kỳ URL nào mà Visual Studio có thể truy cập.
• HTTPVersion là tùy chọn và chỉ định phiên bản HTTP nên sử dụng, tức là HTTP/1.1, HTTP/2, hoặc HTTP/3.

Một file có thể chứa nhiều request bằng cách sử dụng các dòng có ### làm dấu phân cách. Ví dụ sau đây cho thấy ba request trong một file:

GET https://localhost:7220/weatherforecast

###

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

###

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

###

Request headers (Tiêu đề yêu cầu)

Để thêm một hoặc nhiều header, thêm mỗi header trên một dòng riêng ngay sau dòng request. Không thêm dòng trống giữa dòng request và header đầu tiên, hoặc giữa các header liên tiếp. Định dạng là 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

###

Request body (Thân yêu cầu)

Thêm body của request sau một dòng trống:

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

###

Comment (Ghi chú)

Các dòng bắt đầu bằng # hoặc // là comment. Những dòng này bị bỏ qua khi Visual Studio gửi HTTP request.

Variable (Biến)

Một dòng bắt đầu bằng @ định nghĩa một biến với cú pháp @VariableName=Value. Tên biến phân biệt chữ hoa/thường và không được chứa dấu cách. Giá trị có thể chứa bất kỳ ký tự nào, kể cả giá trị null để biểu thị giá trị null.

Biến có thể được tham chiếu trong các request được định nghĩa sau đó trong file. Chúng được tham chiếu bằng cách bao tên trong dấu ngoặc nhọn kép {{ và }}:

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

Biến có thể được định nghĩa bằng cách sử dụng giá trị của các biến được định nghĩa trước đó trong file:

@hostname=localhost
@port=44320
@host={{hostname}}:{{port}}
GET https://{{host}}/api/search/tool

Environment files (File môi trường)

Để cung cấp các giá trị khác nhau cho biến trong các môi trường khác nhau, tạo file có tên http-client.env.json. Đặt file này trong cùng thư mục với file .http hoặc trong một thư mục cha của nó. Ví dụ về file môi trường:

{
  "dev": {
    "HostAddress": "https://localhost:44320"
  },
  "remote": {
    "HostAddress": "https://contoso.com"
  }
}

File môi trường là file JSON chứa một hoặc nhiều môi trường được đặt tên, chẳng hạn như "dev" và "remote". Mỗi môi trường được đặt tên chứa một hoặc nhiều biến. Các biến từ file môi trường được tham chiếu giống như các biến khác:

GET {{HostAddress}}/api/search/tool

Giá trị được sử dụng cho biến khi gửi request được xác định bởi dropdown chọn môi trường ở góc trên bên phải của trình soạn thảo file .http.

File môi trường không nhất thiết phải nằm trong thư mục dự án. Visual Studio tìm kiếm file môi trường trong thư mục chứa file .http. Nếu không tìm thấy, Visual Studio sẽ tìm qua các thư mục cha. Khi tìm thấy file có tên http-client.env.json, quá trình tìm kiếm dừng lại. File gần nhất với file .http sẽ được sử dụng.

Visual Studio hiển thị cảnh báo trong các tình huống sau:

• File .http tham chiếu đến biến không được định nghĩa trong file .http hoặc file môi trường.
• File môi trường chứa biến không được tham chiếu trong file .http.

Biến được định nghĩa trong file .http sẽ ghi đè giá trị trong file môi trường nếu cùng tên.

Shared variables (Biến dùng chung)

$shared là tên môi trường đặc biệt cho các giá trị giống nhau trong nhiều môi trường:

{
    "$shared": {
        "HostAddress": "https://localhost:7293"
    },
    "dev1": {
        "username": "dev1user"
    },
    "dev2": {
        "username": "dev2user"
    },
    "staging": {
        "username": "staginguser",
        "HostAddress": "https://staging.contoso.com"
    }
}

Trong ví dụ trên, môi trường $shared định nghĩa biến HostAddress với giá trị mặc định localhost:7293. Khi chọn môi trường dev1 hoặc dev2, giá trị HostAddress lấy từ $shared. Khi chọn môi trường staging, giá trị HostAddress là https://staging.contoso.com, ghi đè giá trị mặc định từ $shared.

Request variables (Biến request)

Bạn có thể truyền giá trị từ một HTTP request sang request khác trong cùng file .http.

1. Tạo comment một dòng ngay trước URL request để đặt tên cho request tiếp theo:

``http # @name login https://contoso.com/api/login HTTP/1.1 ``

``http // @name login https://contoso.com/api/login HTTP/1.1 ``

1. Trong các request tiếp theo, sử dụng tên request để tham chiếu.
2. Sử dụng cú pháp sau để trích xuất phần cụ thể của response:

``http {{<request name>.(response|request).(body|headers).(*|JSONPath|XPath|<header name>)}} ``

Cú pháp này cho phép trích xuất giá trị từ bản thân request hoặc từ response của nó. Đối với cả request hoặc response, bạn có thể trích xuất giá trị từ body hoặc header.

Khi chọn body:

• * trích xuất toàn bộ body: {{login.response.body.*}}
• JSONPath cho JSON: {{login.response.body.$.token}}
• XPath cho XML: {{login.response.body./token}}

Khi chọn headers, tên header sẽ trích xuất toàn bộ header (không phân biệt hoa/thường): {{login.response.headers.Location}}

Ví dụ sử dụng biến request

Giả sử file HTTP có request xác thực được đặt tên login. Body response là tài liệu JSON chứa bearer token trong thuộc tính token. Các request tiếp theo sẽ truyền bearer token này trong header Authorization:

# @name login

POST {{TodoApi_HostAddress}}/users/token 
Content-Type: application/json 

{ 
  "username": "{{myusername}}", 
} 

### 

GET {{TodoApi_HostAddress}}/todos 
Authorization: Bearer {{login.response.body.$.token}}

###

Cú pháp {{login.response.body.$.token}} biểu thị bearer token:

• login: Tên request.
• response: Đối tượng HTTP response.
• body: Body của HTTP response.
• $: Phần tử gốc của tài liệu JSON trong body response.
• token: Thuộc tính cụ thể trong tài liệu JSON.

User-specific environment files (File môi trường dành riêng cho người dùng)

Giá trị dành riêng cho người dùng là giá trị mà một nhà phát triển muốn kiểm thử nhưng không muốn chia sẻ với nhóm. File http-client.env.json được đưa vào source control (quản lý phiên bản) theo mặc định, vì vậy KHÔNG thêm giá trị dành riêng cho người dùng vào file này. Thay vào đó, thêm chúng vào file có tên http-client.env.json.user. File này nằm trong cùng thư mục với file http-client.env.json. Các file kết thúc bằng .user bị loại trừ khỏi source control theo mặc định khi sử dụng tính năng source control của Visual Studio.

Khi file http-client.env.json được tải, Visual Studio tìm kiếm file http-client.env.json.user cùng thư mục. Nếu biến được định nghĩa trong cả hai file, giá trị trong file .user sẽ thắng.

ASP.NET Core user secrets (Bí mật người dùng)

Để lấy giá trị từ user secrets, sử dụng file môi trường nằm trong cùng thư mục với dự án ASP.NET Core. Trong file môi trường, định nghĩa biến có thuộc tính provider và secretName. Đặt giá trị provider thành AspnetUserSecrets và secretName thành tên user secret mong muốn:

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

Để sử dụng biến này trong file .http, tham chiếu nó như một biến thông thường:

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

Azure Key Vault

Azure Key Vault là một trong nhiều giải pháp quản lý key trong Azure. Trong số ba kho lưu trữ secret hiện được hỗ trợ cho file .http, Key Vault là lựa chọn tốt nhất để chia sẻ secret giữa các người dùng khác nhau.

Để sử dụng giá trị từ Azure Key Vault, bạn phải đăng nhập vào Visual Studio với tài khoản có quyền truy cập vào Key Vault mong muốn. Định nghĩa biến trong file môi trường với siêu dữ liệu để truy cập secret:

{
  "dev": {
    "AKVSecret": {
      "provider": "AzureKeyVault",
      "secretName": "SecretInKeyVault",
      "resourceId": "/subscriptions/3a914c59-8175a9e0e540/resourceGroups/my-key-vault-rg/providers/Microsoft.KeyVault/vaults/my-key-vault-01182024"
    }
  }
}

DPAPI encryption (Mã hóa DPAPI)

Trên Windows, có Data Protection API (DPAPI) có thể được sử dụng để mã hóa dữ liệu nhạy cảm. Khi DPAPI được sử dụng, các giá trị được mã hóa luôn dành riêng cho máy và cũng dành riêng cho người dùng trong file .http. Các giá trị này không thể chia sẻ với người dùng khác.

Để mã hóa giá trị, sử dụng ứng dụng console sau:

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);

Trong file môi trường, tạo biến có thuộc tính provider và value. Đặt provider thành Encrypted và value thành giá trị đã mã hóa:

{
  "dev": {
    "dpapiValue": {
      "provider": "Encrypted",
      "value": "AQAAANCMnd8BFdERjHoAwE/Cl+sBAAAA5qwfg4+Bhk2nsy6ujgg3GAAAAAACAAAAAAAQZgAAAAEAACAAAAAqNXhXc098k1TtKmaI4cUAbJVALMVP1zOR7mhC1RBJegAAAAAOgAAAAAIAACAAAABKu4E9WC/zX5LYZZhOS2pukxMTF9R4yS+XA9HoYF98GzAAAAAzFXatt461ZnVeUWgOV8M/DkqNviWUUjexAXOF/JfpJMw/CdsizQyESus2QjsCtZlAAAAAL7ns3u9mEk6wSMIn+KNsW/vdAw51OaI+HPVrt5vFvXRilTtvGbU/JnxsoIHj0Z7OOxlwOSg1Qdn60zEqmlFJBg=="
    }
  }
}

Environment variables (Biến môi trường)

Để lấy giá trị của biến môi trường, sử dụng $processEnv. Ví dụ sau đặt giá trị của biến môi trường USERNAME trong header X-UserName:

GET {{HostAddress}}{{Path}}
X-UserName: {{$processEnv USERNAME}}

File .env

Để lấy giá trị của biến được định nghĩa trong file .env, sử dụng $dotenv. File .env phải nằm trong thư mục dự án:

GET {{HostAddress}}{{Path}}
X-UserName: {{$dotenv USERNAME}}

Random integers (Số nguyên ngẫu nhiên)

Để tạo số nguyên ngẫu nhiên, sử dụng $randomInt. Cú pháp là {{$randomInt [min max]}} trong đó min và max là tùy chọn.

Dates and times (Ngày và giờ)

• $datetime tạo chuỗi datetime theo UTC. Cú pháp: {{$datetime [format] [offset option]}}
• $localDatetime tạo chuỗi datetime theo múi giờ địa phương. Cú pháp: {{$localDatetime [format] [offset option]}}
• $timestamp tạo timestamp theo UTC (số giây kể từ Unix Epoch). Cú pháp: {{$timestamp [offset option]}}

Tùy chọn [format] là một trong rfc1123, iso8601, hoặc định dạng tùy chỉnh trong dấu ngoặc kép:

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

Cú pháp [offset option] có dạng number unit trong đó number là số nguyên và unit là một trong các giá trị sau:

Ví dụ:

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

Cú pháp không được hỗ trợ

Trình soạn thảo .http trong Visual Studio 2022 không có tất cả tính năng của tiện ích mở rộng REST Client của Visual Studio Code. Các tính năng chỉ có trong tiện ích Visual Studio Code bao gồm:

• Dòng request kéo dài nhiều dòng
• Chỉ định đường dẫn file làm body của request
• Định dạng hỗn hợp cho body khi sử dụng multipart/form-data
• Request GraphQL
• Request cURL
• Copy/paste dưới dạng cURL
• Lịch sử request
• Lưu body response vào file
• Xác thực dựa trên certificate
• Biến prompt
• Tùy chỉnh xem trước response
• Cài đặt theo từng request
• Xử lý biến null

Tạo file .http

• Trong Solution Explorer, nhấp chuột phải vào dự án ASP.NET Core.
• Trong menu ngữ cảnh, chọn Add > New Item.
• Trong hộp thoại Add New Item, chọn ASP.NET Core > General.
• Chọn HTTP File và nhấp Add.

Gửi HTTP request

• Thêm ít nhất một request vào file .http và lưu file.
• Nếu URL request trỏ đến localhost và cổng của dự án, hãy chạy dự án trước khi gửi request.
• Chọn link Send Request hoặc Debug nằm trực tiếp phía trên request cần gửi.

Request sẽ được gửi đến URL đã chỉ định và response hiển thị trong pane riêng ở bên phải cửa sổ soạn thảo.

Tùy chọn file .http

Một số khía cạnh của hành vi file .http có thể được cấu hình. Để xem những gì có sẵn, vào Tools > Options > Text Editor > Rest. Ví dụ, cài đặt timeout có thể được cấu hình trên tab Advanced.

Sử dụng Endpoints Explorer

Endpoints Explorer (Trình khám phá Endpoint) là cửa sổ công cụ hiển thị tất cả các endpoint mà một web API định nghĩa. Công cụ cho phép bạn gửi request đến các endpoint bằng cách sử dụng file .http.

Bộ endpoint ban đầu mà Endpoints Explorer hiển thị được khám phá tĩnh. Có một số endpoint không thể được khám phá tĩnh. Ví dụ, các endpoint được định nghĩa trong dự án class library không thể được khám phá cho đến khi chạy. Khi bạn chạy hoặc debug một web API, Visual Studio phiên bản 17.11 Preview khám phá các endpoint động tại thời điểm chạy và thêm chúng vào Endpoints Explorer.

Mở Endpoints Explorer

Chọn View > Other Windows > Endpoints Explorer.

Thêm request vào file .http

Nhấp chuột phải vào request trong Endpoints Explorer và chọn Generate Request.

• Nếu file .http có tên file là tên dự án đã tồn tại, request sẽ được thêm vào file đó.
• Nếu không, file .http sẽ được tạo với tên dự án và request sẽ được thêm vào đó.

Ví dụ request được tạo cho endpoint đã chọn:

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

###

Gửi request như đã mô tả ở phần trước của bài viết này.