Menggunakan file .http di Visual Studio 2022

  • Artikel

Editor file Visual Studio 2022.http menyediakan cara mudah untuk menguji proyek ASP.NET Core, terutama aplikasi API. Editor menyediakan UI yang:

  • Membuat dan memperbarui .http file.
  • Mengirim permintaan HTTP yang ditentukan dalam .http file.
  • Menampilkan respons.

Artikel ini berisi dokumentasi untuk:

.http Format file dan editor terinspirasi oleh ekstensi Klien Visual Studio CodeREST. Editor Visual Studio 2022 .http mengenali .rest sebagai ekstensi file alternatif untuk format file yang sama.

Prasyarat

.http sintaks file

Bagian berikut menjelaskan .http sintaks file.

Permintaan

Format untuk permintaan HTTP adalah HTTPMethod URL HTTPVersion, semua pada satu baris, di mana:

  • HTTPMethod adalah metode HTTP untuk digunakan, misalnya:
  • URL adalah URL untuk mengirim permintaan. URL dapat menyertakan parameter string kueri. URL tidak harus menunjuk ke proyek web lokal. Ini dapat menunjuk ke URL apa pun yang dapat diakses Visual Studio.
  • HTTPVersionbersifat opsional dan menentukan versi HTTP yang harus digunakan, yaitu, , HTTP/1.1HTTP/2, atau HTTP/3.

File dapat berisi beberapa permintaan dengan menggunakan baris dengan ### sebagai pemisah. Contoh berikut menunjukkan tiga permintaan dalam file yang mengilustrasikan sintaks ini:

GET https://localhost:7220/weatherforecast

###

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

###

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

###

Header permintaan

Untuk menambahkan satu atau beberapa header, tambahkan setiap header pada barisnya sendiri segera setelah baris permintaan. Jangan sertakan baris kosong antara baris permintaan dan header pertama atau di antara baris header berikutnya. Formatnya adalah HeaderName: Value, seperti yang ditunjukkan dalam contoh berikut:

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

###

Penting

Saat memanggil API yang mengautentikasi dengan header, jangan terapkan rahasia apa pun ke repositori kode sumber. Lihat metode yang didukung untuk menyimpan rahasia nanti di artikel ini, seperti rahasia pengguna ASP.NET Core, Azure Key Vault, dan enkripsi DPAPI.

Isi permintaan

Tambahkan isi permintaan setelah baris kosong, seperti yang ditunjukkan dalam contoh berikut:

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

###

Komentar

Baris yang dimulai dengan atau #// adalah komentar. Baris ini diabaikan saat Visual Studio mengirim permintaan HTTP.

Variabel

Baris yang dimulai dengan @ mendefinisikan variabel dengan menggunakan sintaks @VariableName=Value.

Variabel dapat dirujuk dalam permintaan yang ditentukan nanti dalam file. Mereka dirujuk dengan membungkus namanya dalam kurung kurawal ganda, {{ dan }}. Contoh berikut menunjukkan dua variabel yang ditentukan dan digunakan dalam permintaan:

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

Variabel dapat didefinisikan menggunakan nilai variabel lain yang ditentukan sebelumnya dalam file. Contoh berikut menggunakan satu variabel dalam permintaan alih-alih keduanya ditampilkan dalam contoh sebelumnya:

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

File lingkungan

Untuk memberikan variabel nilai yang berbeda di lingkungan yang berbeda, buat file bernama http-client.env.json. Temukan file dalam direktori yang sama dengan .http file atau di salah satu direktori induknya. Berikut adalah contoh file lingkungan:

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

File lingkungan adalah JSfile ON yang berisi satu atau beberapa lingkungan bernama, seperti "dev" dan "remote" dalam contoh sebelumnya. Setiap lingkungan bernama berisi satu atau beberapa variabel, seperti HostAddress dalam contoh sebelumnya. Variabel dari file lingkungan dirujuk dengan cara yang sama seperti variabel lain, seperti yang ditunjukkan dalam contoh berikut:

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

Nilai yang digunakan untuk variabel saat mengirim permintaan ditentukan oleh dropdown pemilih lingkungan di sudut .http kanan atas editor file. Cuplikan layar berikut menunjukkan pemilih:

.http file editor with environment selector highlighted. The 'dev' environment is selected.

File lingkungan tidak harus berada di folder proyek. Visual Studio mencari file lingkungan di folder tempat .http file berada. Jika tidak ada di folder tersebut, Visual Studio akan melihat direktori induk untuk menemukannya. Ketika file bernama http-client.env.json ditemukan, pencarian berakhir. File yang ditemukan terdekat dengan .http file digunakan.

Setelah membuat atau mengedit .http file, Anda mungkin harus menutup dan membuka kembali proyek untuk melihat perubahan yang tercermin dalam pemilih lingkungan. Tekan F6 untuk memilih pemilih lingkungan.

Visual Studio menampilkan peringatan dalam situasi berikut:

  • File .http mereferensikan variabel yang tidak ditentukan dalam .http file atau dalam file lingkungan.
  • File lingkungan berisi variabel yang tidak dirujuk dalam .http file.

Variabel yang ditentukan dalam file lingkungan dapat sama dengan yang didefinisikan dalam .http file, atau bisa berbeda. Jika variabel didefinisikan dalam .http file dan file lingkungan, nilai dalam .http file akan mengambil alih nilai dalam file lingkungan.

File lingkungan khusus pengguna

Nilai khusus pengguna adalah nilai apa pun yang ingin diuji oleh pengembang individu tetapi tidak ingin berbagi dengan tim. http-client.env.json Karena file dicek masuk ke kontrol sumber secara default, file tidak akan sesuai untuk menambahkan nilai khusus pengguna ke file ini. Sebagai gantinya, letakkan dalam file bernama http-client.env.json.user yang terletak di folder yang sama dengan http-client.env.json file. File yang diakhir dengan .user harus dikecualikan dari kontrol sumber secara default saat menggunakan fitur kontrol sumber Visual Studio.

http-client.env.json Saat file dimuat, Visual Studio mencari file saudarahttp-client.env.json.user. Jika variabel didefinisikan dalam lingkungan dalam http-client.env.json file dan http-client.env.json.user file, nilai dalam http-client.env.json.user file akan menang.

Berikut adalah contoh skenario yang menunjukkan cara kerja file lingkungan khusus pengguna. Misalkan .http file memiliki konten berikut:

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

Dan misalkan http-client.env.json file berisi konten berikut:

{
  "dev": {
    "HostAddress": "https://localhost:7128",
    "Path": "/weatherforecast"
  },
  "remote": {
    "HostAddress": "https://contoso.com",
    "Path": "/weatherforecast"
  }
}

Dan misalkan ada file lingkungan khusus pengguna yang berisi konten berikut:

{
  "dev": {
    "Path": "/swagger/index.html"
  }
}

Saat pengguna memilih lingkungan "dev", permintaan dikirim ke https://localhost:7128/swagger/index.html karena nilai dalam http-client.env.json.user file mengambil alih nilai dari http-client.env.jsonPath file.

Dengan file lingkungan yang sama, misalkan variabel ditentukan dalam .http file:

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

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

Dalam skenario ini, permintaan lingkungan "dev" dikirim ke https://contoso.com/weatherforecast karena definisi variabel dalam .http file mengambil alih definisi file lingkungan.

ASP.NET Rahasia pengguna Core

Untuk mendapatkan nilai dari rahasia pengguna, gunakan file lingkungan yang terletak di folder yang sama dengan proyek ASP.NET Core. Dalam file lingkungan, tentukan variabel yang memiliki provider properti dan secretName . Atur nilai ke providerAspnetUserSecrets dan atur secretName ke nama rahasia pengguna yang diinginkan. Misalnya, file lingkungan berikut menentukan variabel bernama ApiKeyDev yang mendapatkan nilainya dari config:ApiKeyDev rahasia pengguna:

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

Untuk menggunakan variabel ini dalam .http file, referensikan seperti variabel standar. Misalnya:

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

Saat permintaan dikirim, nilai ApiKeyDev rahasia berada di header X-API-KEY.

Saat Anda mengetik dalam http file, editor menunjukkan daftar penyelesaian untuk nama variabel tetapi tidak menunjukkan nilainya.

Azure Key Vault

Azure Key Vault adalah salah satu dari beberapa solusi manajemen utama di Azure yang dapat digunakan untuk manajemen rahasia. Dari tiga penyimpanan rahasia yang saat ini didukung untuk .http file, Key Vault adalah pilihan terbaik untuk berbagi rahasia di berbagai pengguna. Dua opsi lainnya—ASP.NET Rahasia Pengguna dan enkripsi DPAPI—tidak mudah dibagikan.

Untuk menggunakan nilai dari Azure Key Vault, Anda harus masuk ke Visual Studio dengan akun yang memiliki akses ke Key Vault yang diinginkan. Tentukan variabel dalam file lingkungan dengan metadata untuk mengakses rahasia. Variabel dinamai AKVSecret dalam contoh berikut:

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

Variabel AKVSecret menarik nilainya dari Azure Key Vault. Properti berikut didefinisikan pada AKVSecret:

Nama Deskripsi
penyedia Untuk Key Vault, selalu gunakan AzureKeyVault.
secretName Nama rahasia yang akan diekstrak.
resourceId ID sumber daya Azure untuk akses Key Vault tertentu.

Nilai untuk resourceId properti dapat ditemukan di portal Azure. Buka Properti Pengaturan > untuk menemukannya. Untuk secretName, gunakan nama rahasia yang muncul di halaman Rahasia di portal Azure.

Misalnya, file berikut .http memiliki permintaan yang menggunakan nilai rahasia ini.

GET {{HostAddress}}{{Path}}
X-AKV-SECRET: {{akvSecret}}

Enkripsi DPAPI

Di Windows, ada API Perlindungan Data (DPAPI) yang dapat digunakan untuk mengenkripsi data sensitif. Ketika DPAPI digunakan untuk mengenkripsi data, nilai terenkripsi selalu spesifik untuk komputer, dan nilai tersebut juga khusus pengguna dalam .http file. Nilai-nilai ini tidak dapat dibagikan dengan pengguna lain.

Untuk mengenkripsi nilai, gunakan aplikasi konsol berikut:

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

Aplikasi konsol sebelumnya mereferensikan paket System.Security.Cryptography.ProtectedData NuGet. Untuk mengaktifkan nilai terenkripsi agar berfungsi dalam .http file, enkripsi dengan cakupan yang diatur ke DataProtectionScope.CurrentUser. Nilai terenkripsi adalah string berkode base64 yang dapat disalin dan ditempelkan ke dalam file lingkungan.

Dalam file lingkungan, buat variabel yang memiliki provider properti dan value . Atur provider ke Encrypted, dan atur value ke nilai terenkripsi. Misalnya, file lingkungan berikut menentukan variabel bernama dpapiValue yang mendapatkan nilainya dari string yang dienkripsi dengan DPAPI.

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

Dengan file lingkungan sebelumnya, dpapiValue dapat digunakan dalam .http file seperti variabel lainnya. Misalnya:

GET {{HostAddress}}{{Path}}
X-DPAPI-Secret: {{dpapiSecret}}

Ketika permintaan ini dikirim, X-DPAPI-Secret memiliki nilai rahasia yang didekripsi.

Variabel lingkungan

Untuk mendapatkan nilai variabel lingkungan, gunakan $processEnv. Contoh berikut menempatkan nilai variabel lingkungan USERNAME di header X-UserName.

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

Jika Anda mencoba menggunakan $processEnv untuk mengakses variabel lingkungan yang tidak ada, .http editor file akan menampilkan pesan kesalahan.

.env File

Untuk mendapatkan nilai variabel yang ditentukan dalam .env file, gunakan $dotenv. File .env harus berada di folder proyek. Format untuk $dotenv sama dengan untuk $processEnv. Misalnya, jika .env file memiliki konten ini:

USERNAME=userFromDotenv

.http Dan file memiliki konten ini:

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

Header X-UserName akan memiliki "userFromDotenv".

Ketika $dotenv dimasukkan di editor, itu menunjukkan penyelesaian untuk variabel yang ditentukan dalam .env file.

Catatan

.env file mungkin tidak dikecualikan dari kontrol sumber secara default, jadi berhati-hatilah untuk menghindari pemeriksaan dalam nilai rahasia apa pun.

Bilangan bulat acak

Untuk menghasilkan bilangan bulat acak, gunakan $randomInt. Sintaksnya adalah {{$randomInt [min max]}} tempat min nilai dan max bersifat opsional.

Tanggal dan waktu

  • $datetimedatetime menghasilkan string dalam UTC. Sintaksnya adalah {{$datetime [format] [offset option]}} tempat opsi format dan offset bersifat opsional.
  • $localDatetimedatetime menghasilkan string di zona waktu lokal. Sintaksnya adalah {{$localDatetime [format] [offset option]}} tempat opsi format dan offset bersifat opsional.
  • $timeStamptimestamp menghasilkan dalam UTC. adalah timestampjumlah detik sejak Unix Epoch dalam waktu UTC. Sintaksnya adalah {{$timestamp [offset option]}} tempat opsi offset bersifat opsional.

Opsinya [format] adalah salah satu dari rfc1123, iso8601, atau format kustom dalam tanda kutip. Misalnya:

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

Berikut adalah beberapa nilai sampel yang dihasilkan contoh sebelumnya:

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

Sintaksnya [offset option] adalah dalam bentuk numberunit di mana number adalah bilangan bulat dan unit merupakan salah satu nilai berikut:

unit Penjelasan
ms Milidetik
s Detik
m Menit
h Jam
d Hari
w Minggu
M Bulan
y Tahun

Misalnya:

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

Berikut adalah beberapa nilai sampel yang dihasilkan contoh sebelumnya:

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

Beberapa contoh sebelumnya menggunakan situs web <sumber terbuka gratis httpbin.org>. Ini adalah situs web pihak ketiga yang tidak berafiliasi dengan Microsoft. Dalam contoh ini, ia mengembalikan isi respons dengan header yang dikirim dalam permintaan. Untuk informasi tentang cara lain untuk menggunakan sumber daya ini untuk pengujian API, lihat beranda situs httpbin.org.

Sintaksis yang tidak didukung

Editor file Visual Studio 2022 .http tidak memiliki semua fitur yang dimiliki ekstensi Klien Visual Studio CodeREST. Daftar berikut ini mencakup beberapa fitur yang lebih signifikan yang hanya tersedia di ekstensi Visual Studio Code:

  • Baris permintaan yang mencakup lebih dari satu baris
  • Permintaan bernama
  • Tentukan jalur file sebagai isi permintaan
  • Format campuran untuk isi saat menggunakan multipart/form-data
  • Permintaan GraphQL
  • Permintaan cURL
  • Salin/tempel sebagai cURL
  • Riwayat permintaan
  • Simpan isi respons ke file
  • Autentikasi berbasis sertifikat
  • Variabel perintah
  • Menyesuaikan pratinjau respons
  • Pengaturan per permintaan

Membuat .http file

  • Di Penjelajah Solusi, klik kanan proyek ASP.NET Core.

  • Di menu konteks, pilih Tambahkan>Item Baru.

  • Dalam dialog Tambahkan Item Baru, pilih ASP.NET Core>General.

  • Pilih File HTTP, dan pilih Tambahkan.

    Add New Item dialog showing HTTP File type selected.

Kirim permintaan HTTP

  • Tambahkan setidaknya satu permintaan ke .http file dan simpan file.

  • Jika URL permintaan menunjuk ke localhost dan port proyek, jalankan proyek sebelum mencoba mengirim permintaan ke dalamnya.

  • Send Request Pilih tautan atau Debug yang berada tepat di atas permintaan yang akan dikirim.

    Permintaan dikirim ke URL yang ditentukan, dan respons muncul di panel terpisah di sebelah kanan jendela editor.

    .http file editor window with 'run' button highlighted and showing the response pane.

.http opsi file

Beberapa aspek .http perilaku file dapat dikonfigurasi. Untuk melihat apa yang tersedia, buka Opsi>Alat>Editor>Teks Istirahat. Misalnya, pengaturan batas waktu dapat dikonfigurasi pada tab Tingkat Lanjut . Berikut adalah cuplikan layar dialog Opsi :

Options dialog showing Text Editor and Rest selection.

Menggunakan Penjelajah Titik Akhir

Endpoints Explorer adalah jendela alat di Visual Studio 2022 yang menyediakan UI yang terintegrasi dengan .http editor file untuk menguji permintaan HTTP.

Buka Penjelajah Titik Akhir

Pilih Tampilkan>Penjelajah Titik Akhir Windows>Lainnya.

Menambahkan permintaan ke .http file

Klik kanan permintaan di Endpoints Explorer dan pilih Buat Permintaan.

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

  • .http Jika file dengan nama proyek sebagai nama file ada, permintaan ditambahkan ke file tersebut.
  • Jika tidak, .http file dibuat dengan nama proyek sebagai nama file, dan permintaan ditambahkan ke file tersebut.

Cuplikan layar sebelumnya menunjukkan titik akhir yang ditentukan oleh templat proyek API minimal. Contoh berikut menunjukkan permintaan yang dihasilkan untuk titik akhir yang dipilih:

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

###

Kirim permintaan seperti yang dijelaskan sebelumnya dalam artikel ini.

Baca juga