Použití souborů .http v sadě Visual Studio 2022

  • Článek

Editor souborů sady Visual Studio 2022 .http poskytuje pohodlný způsob testování ASP.NET základních projektů, zejména aplikací API. Editor poskytuje uživatelské rozhraní, které:

  • Vytvoří a aktualizuje .http soubory.
  • Odešle požadavky HTTP zadané v .http souborech.
  • Zobrazí odpovědi.

Tento článek obsahuje dokumentaci pro:

Formát .http souborů a editor byl inspirovaný rozšířením klienta editoru Visual Studio CodeREST. Editor sady Visual Studio 2022 .http rozpozná .rest jako alternativní příponu souboru pro stejný formát souboru.

Požadavky

.http Syntaxe souboru

Následující části vysvětlují .http syntaxi souboru.

Žádosti

Formát požadavku HTTP je HTTPMethod URL HTTPVersion, vše na jednom řádku, kde:

  • HTTPMethod je metoda HTTP, která se má použít, například:
  • URL je adresa URL pro odeslání požadavku. Adresa URL může obsahovat parametry řetězce dotazu. Adresa URL nemusí odkazovat na místní webový projekt. Může odkazovat na libovolnou adresu URL, ke které má Visual Studio přístup.
  • HTTPVersion je nepovinná a určuje verzi PROTOKOLU HTTP, která se má použít, tj HTTP/1.1. , , HTTP/2nebo HTTP/3.

Soubor může obsahovat více požadavků pomocí řádků s ### oddělovači. Následující příklad znázorňující tři požadavky v souboru znázorňuje tuto syntaxi:

GET https://localhost:7220/weatherforecast

###

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

###

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

###

Záhlaví žádosti

Pokud chcete přidat jednu nebo více hlaviček, přidejte každou hlavičku na vlastní řádek hned za řádek požadavku. Nezahrnujte žádné prázdné řádky mezi řádkem požadavku a první hlavičkou nebo mezi dalšími řádky záhlaví. Formát je , jak je HeaderName: Valueznázorněno v následujících příkladech:

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

###

Důležité

Při volání rozhraní API, které se ověřuje pomocí hlaviček, neověřte do úložiště zdrojového kódu žádné tajné kódy. Podívejte se na podporované metody ukládání tajných kódů dále v tomto článku, jako jsou ASP.NET základní tajné kódy uživatelů, Azure Key Vault a šifrování DPAPI.

Text požadavku

Přidejte text požadavku za prázdný řádek, jak je znázorněno v následujícím příkladu:

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

###

Komentáře

Řádky, které začínají nebo # // jsou komentáře. Tyto řádky se ignorují, když Visual Studio odesílá požadavky HTTP.

Proměnné

Řádek, který začíná @ definováním proměnné pomocí syntaxe @VariableName=Value.

Proměnné lze odkazovat v požadavcích, které jsou definovány později v souboru. Odkazují na to tak, {{ že jména zabalí do dvojitých složených závorek a }}. Následující příklad ukazuje dvě proměnné definované a použité v požadavku:

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

Proměnné lze definovat pomocí hodnot jiných proměnných, které byly definovány dříve v souboru. V následujícím příkladu se místo dvou zobrazených v předchozím příkladu používá jedna proměnná v požadavku:

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

Soubory prostředí

Pokud chcete dát proměnným různé hodnoty v různých prostředích, vytvořte soubor s názvem http-client.env.json. Vyhledejte soubor ve stejném adresáři jako .http soubor nebo v některém z jeho nadřazených adresářů. Tady je příklad souboru prostředí:

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

Soubor prostředí je soubor JSON, který obsahuje jedno nebo více pojmenovaných prostředí, například "dev" a "remote" v předchozím příkladu. Každé pojmenované prostředí obsahuje jednu nebo více proměnných, například HostAddress v předchozím příkladu. Proměnné ze souboru prostředí se odkazují stejným způsobem jako na jiné proměnné, jak je znázorněno v následujícím příkladu:

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

Hodnota použitá pro proměnnou při odesílání požadavku je určena rozevíracím seznamem selektoru prostředí v pravém horním rohu editoru .http souborů. Následující snímek obrazovky ukazuje selektor:

Editor souborů .http se zvýrazněným selektorem prostředí Je vybrané vývojové prostředí.

Soubor prostředí nemusí být ve složce projektu. Visual Studio hledá soubor prostředí ve složce, ve které .http soubor existuje. Pokud není v této složce, Visual Studio ji vyhledá pomocí nadřazených adresářů. Když se najde soubor s názvem http-client.env.json , hledání skončí. Soubor nalezený nejblíže k .http souboru se použije.

Po vytvoření nebo úpravě .http souboru možná budete muset projekt zavřít a znovu otevřít, aby se změny projevily ve selektoru prostředí. Stisknutím klávesy F6 vyberte volič prostředí.

Visual Studio zobrazuje upozornění v následujících situacích:

  • Soubor .http odkazuje na proměnnou, která není definována v .http souboru nebo v souboru prostředí.
  • Soubor prostředí obsahuje proměnnou, na kterou se v .http souboru neodkazuje.

Proměnná definovaná v souboru prostředí může být stejná jako proměnná definovaná v .http souboru nebo může být odlišná. Pokud je proměnná definována v .http souboru i v souboru prostředí, hodnota v .http souboru přepíše hodnotu v souboru prostředí.

Soubory prostředí specifické pro uživatele

Hodnota specifická pro uživatele je jakákoli hodnota, se kterou chce jednotlivý vývojář testovat, ale nechce ji sdílet s týmem. http-client.env.json Vzhledem k tomu, že je soubor ve výchozím nastavení vrácený se změnami do správy zdrojového kódu, není vhodné do tohoto souboru přidat hodnoty specifické pro uživatele. Místo toho je vložte do souboru, http-client.env.json.user který se nachází ve stejné složce jako soubor http-client.env.json . Soubory, které končí .user , by měly být ve výchozím nastavení vyloučeny ze správy zdrojového kódu při použití funkcí správy zdrojového kódu sady Visual Studio.

http-client.env.json Po načtení souboru sada Visual Studio vyhledá soubor na stejné úrovnihttp-client.env.json.user. Pokud je proměnná definována v prostředí v http-client.env.json souboru i http-client.env.json.user v souboru, hodnota v http-client.env.json.user souboru vyhraje.

Tady je ukázkový scénář, který ukazuje, jak soubor prostředí specifický pro uživatele funguje. Předpokládejme, .http že soubor obsahuje následující obsah:

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

A předpokládejme, http-client.env.json že soubor obsahuje následující obsah:

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

A předpokládejme, že existuje soubor prostředí specifický pro uživatele, který obsahuje následující obsah:

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

Když uživatel vybere vývojové prostředí, požadavek se odešle, https://localhost:7128/swagger/index.html protože hodnota v http-client.env.json.user souboru přepíše hodnotu ze http-client.env.json Path souboru.

Předpokládejme, že se v souboru definují .http proměnné se stejnými soubory prostředí:

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

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

V tomto scénáři se odešle požadavek na vývojové prostředí, protože https://contoso.com/weatherforecast definice proměnných v .http souborech přepisují definice souborů prostředí.

tajné kódy uživatele ASP.NET Core

Pokud chcete získat hodnotu z tajných kódů uživatelů, použijte soubor prostředí, který se nachází ve stejné složce jako projekt ASP.NET Core. V souboru prostředí definujte proměnnou, která má provider a secretName má vlastnosti. provider Nastavte hodnotu na AspnetUserSecrets a nastavte secretName na název požadovaného tajného klíče uživatele. Například následující soubor prostředí definuje proměnnou s názvem ApiKeyDev , která získá jeho hodnotu z tajného config:ApiKeyDev kódu uživatele:

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

Pokud chcete tuto proměnnou použít v .http souboru, odkazujte na ni jako na standardní proměnnou. Příklad:

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

Při odeslání požadavku je hodnota tajného ApiKeyDev kódu v hlavičce X-API-KEY.

Při psaní do http souboru editor zobrazuje seznam dokončení pro název proměnné, ale nezobrazuje jeho hodnotu.

Azure Key Vault

Azure Key Vault je jedním z několika řešení pro správu klíčů v Azure, která se dají použít ke správě tajných kódů. Ze tří úložišť tajných kódů aktuálně podporovaných pro .http soubory je služba Key Vault nejlepší volbou pro sdílení tajných kódů mezi různými uživateli. Další dvě možnosti – ASP.NET tajných kódů uživatelů a šifrování DPAPI – se nesdílí snadno.

Pokud chcete použít hodnotu ze služby Azure Key Vault, musíte být přihlášení k sadě Visual Studio pomocí účtu, který má přístup k požadované službě Key Vault. Definujte proměnnou v souboru prostředí s metadaty pro přístup k tajnému kódu. Proměnná je pojmenována AKVSecret v následujícím příkladu:

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

Proměnná AKVSecret načítá svou hodnotu ze služby Azure Key Vault. Následující vlastnosti jsou definovány v AKVSecret:

Název Popis
Zprostředkovatel Pro Key Vault vždy používejte AzureKeyVault.
secretName Název tajného kódu, který se má extrahovat.
resourceId ID prostředku Azure pro konkrétní službu Key Vault pro přístup.

Hodnotu resourceId vlastnosti najdete na webu Azure Portal. Přejděte na Vlastnosti nastavení > a vyhledejte ho. Pokud secretNamechcete, použijte název tajného kódu, který se zobrazí na stránce Tajné kódy na webu Azure Portal.

Například následující .http soubor obsahuje požadavek, který používá tuto hodnotu tajného kódu.

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

Šifrování DPAPI

Ve Windows je k dispozici rozhraní API pro ochranu dat (DPAPI), které lze použít k šifrování citlivých dat. Při použití rozhraní DPAPI k šifrování dat jsou šifrované hodnoty vždy specifické pro počítač a jsou také uživatelem specifické pro .http soubory. Tyto hodnoty nelze sdílet s jinými uživateli.

K šifrování hodnoty použijte následující konzolovou aplikaci:

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

Předchozí konzolová aplikace odkazuje na balíček NuGet System.Security.Cryptography.ProtectedData . Pokud chcete, aby šifrovaná hodnota fungovala .http v souboru, zašifrujte ji nastavením oboru .DataProtectionScope.CurrentUser Zašifrovaná hodnota je řetězec kódovaný v base64, který lze zkopírovat a vložit do souboru prostředí.

V souboru prostředí vytvořte proměnnou, která má provider a value má vlastnosti. Nastavte provider na Encryptedhodnotu a nastavte value na zašifrovanou hodnotu. Například následující soubor prostředí definuje proměnnou s názvem dpapiValue , která získá jeho hodnotu z řetězce, který byl zašifrován pomocí DPAPI.

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

S předchozím souborem dpapiValue prostředí lze v .http souboru použít stejně jako jakoukoli jinou proměnnou. Příklad:

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

Při odeslání tohoto požadavku má X-DPAPI-Secret dešifrovanou hodnotu tajného kódu.

Proměnné prostředí

K získání hodnoty proměnné prostředí použijte $processEnv. Následující příklad vloží hodnotu proměnné prostředí USERNAME do hlavičky X-UserName.

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

Pokud se pokusíte použít $processEnv pro přístup k proměnné prostředí, která neexistuje, .http zobrazí editor souborů chybovou zprávu.

.env soubory

K získání hodnoty proměnné, která je definována v .env souboru, použijte $dotenv. Soubor .env musí být ve složce projektu. Formát pro $dotenv je stejný jako pro $processEnv. Pokud .env má soubor například tento obsah:

USERNAME=userFromDotenv

.http Soubor má tento obsah:

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

Hlavička X-UserName bude mít hodnotu userFromDotenv.

Po $dotenv zadání v editoru se zobrazí dokončení proměnných definovaných v .env souboru.

Poznámka:

.env Soubory nemusí být ve výchozím nastavení vyloučené ze správy zdrojového kódu, proto buďte opatrní, abyste se vyhnuli vrácení se kontrolou jakýchkoli tajných hodnot.

Náhodná celá čísla

Chcete-li vygenerovat náhodné celé číslo, použijte $randomInt. Syntaxe je {{$randomInt [min max]}} místo, kde min jsou hodnoty max volitelné.

Datové typy pro datum a čas

  • $datetime vygeneruje řetězec ve standardu datetime UTC. Syntaxe je místo, kde jsou {{$datetime [format] [offset option]}} možnosti formátu a posunu volitelné.
  • $localDatetime vygeneruje datetime řetězec v místním časovém pásmu. Syntaxe je místo, kde jsou {{$localDatetime [format] [offset option]}} možnosti formátu a posunu volitelné.
  • $timeStamp vygeneruje timestamp v UTC. Jedná se timestamp o počet sekund od unixového epochy v čase UTC. Syntaxe je místo, kde je {{$timestamp [offset option]}} možnost posunu volitelná.

Možnost [format] je jedna z rfc1123, iso8601nebo vlastní formát v uvozovkách. Příklad:

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

Tady jsou některé ukázkové hodnoty, které vygenerují předchozí příklady:

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

Syntaxe [offset option] je ve tvaru number unit , kde number je celé číslo a unit je jednou z následujících hodnot:

unit Vysvětlení
ms Milisekundy
s Sekundy
m Minuty
h hod
d dny
w Týdny
M Měsíce
y Roky

Příklad:

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

Tady jsou některé ukázkové hodnoty, které vygenerují předchozí příklady:

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

Některé z předchozích příkladů používají bezplatný opensourcový web <httpbin.org>. Jedná se o web třetí strany, který není přidružený k Microsoftu. V těchto příkladech vrátí text odpovědi s hlavičkami, které byly odeslány v požadavku. Informace o dalších způsobech použití tohoto prostředku pro testování rozhraní API najdete na stránce webu httpbin.orghome.

Nepodporovaná syntaxe

Editor souborů sady Visual Studio 2022 .http nemá všechny funkce, které má rozšíření klienta editoru Visual Studio CodeREST. Následující seznam obsahuje některé z významných funkcí dostupných pouze v rozšíření Visual Studio Code:

  • Řádek požadavku, který zahrnuje více než jeden řádek
  • Pojmenované požadavky
  • Zadejte cestu k souboru jako text požadavku.
  • Smíšený formát textu při použití vícedílných dat nebo dat formuláře
  • Požadavky GraphQL
  • Požadavek cURL
  • Kopírovat/vložit jako cURL
  • Historie požadavků
  • Uložení textu odpovědi do souboru
  • Ověřování pomocí certifikátů
  • Proměnné výzvy
  • Přizpůsobení náhledu odpovědi
  • Nastavení pro jednotlivé požadavky

Vytvoření .http souboru

  • V Průzkumník řešení klikněte pravým tlačítkem na projekt ASP.NET Core.

  • V místní nabídce vyberte Přidat>novou položku.

  • V dialogovém okně Přidat novou položku vyberte ASP.NET Core>General.

  • Vyberte soubor HTTP a vyberte Přidat.

    Dialogové okno Přidat novou položku s vybraným typem souboru HTTP

Odeslání požadavku HTTP

  • Přidejte do souboru aspoň jeden požadavek .http a soubor uložte.

  • Pokud adresa URL požadavku odkazuje na localhost a port projektu, spusťte projekt před pokusem o odeslání požadavku.

  • Send Request Vyberte odkaz, Debug který je přímo nad žádostí, která se má odeslat.

    Požadavek se odešle na zadanou adresu URL a odpověď se zobrazí v samostatném podokně napravo od okna editoru.

    Okno editoru souborů .http se zvýrazněným tlačítkem Spustit a zobrazeným podoknem odpovědi

.http možnosti souboru

Je možné nakonfigurovat některé aspekty .http chování souboru. Pokud chcete zjistit, co je k dispozici, přejděte do textového editoruRest> Možnosti>nástrojů.> Nastavení časového limitu je například možné nakonfigurovat na kartě Upřesnit . Tady je snímek obrazovky s dialogovým oknem Možnosti :

Dialogové okno Možnosti s textovým editorem a Rest výběrem

Použití Průzkumníka koncových bodů

Průzkumník koncových bodů je okno nástroje, které zobrazuje všechny koncové body, které webové rozhraní API definuje. Nástroj umožňuje odesílat požadavky do koncových bodů pomocí .http souboru.

Počáteční sada koncových bodů, které Zobrazí Průzkumník koncových bodů, se zjistí staticky. Některé koncové body se nedají staticky zjistit. Například koncové body definované v projektu knihovny tříd se nedají zjistit, dokud neschybuje modul runtime. Když spustíte nebo ladíte webové rozhraní API, Visual Studio verze 17.11 Preview zjišťuje koncové body dynamicky také za běhu a přidává je do Průzkumníka koncových bodů.

Otevření Průzkumníka koncových bodů

Vyberte Zobrazit>další průzkumníka koncových bodů Windows.>

Přidání požadavku do .http souboru

V Průzkumníku koncových bodů klikněte pravým tlačítkem myši na žádost a vyberte Vygenerovat požadavek.

Okno Průzkumník koncových bodů zobrazující místní nabídku požadavku se zvýrazněným výběrem nabídky Generate Request (Vygenerovat požadavek).

  • Pokud existuje .http soubor s názvem projektu, který obsahuje název souboru, přidá se do souboru požadavek.
  • .http V opačném případě se vytvoří soubor s názvem projektu jako názvem souboru a požadavek se do něj přidá.

Předchozí snímek obrazovky ukazuje koncové body definované minimální šablonou projektu rozhraní API. Následující příklad ukazuje požadavek vygenerovaný pro vybraný koncový bod:

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

###

Odešlete požadavek, jak je popsáno výše v tomto článku.

Viz také