Dela via

Använda .http-filer i Visual Studio 2022

  • Artikel

Filredigeraren Visual Studio 2022.http är ett bekvämt sätt att testa ASP.NET Core-projekt, särskilt API-appar. Redigeraren tillhandahåller ett användargränssnitt som:

  • Skapar och uppdaterar .http filer.
  • Skickar HTTP-begäranden som anges i .http filer.
  • Visar svaren.

Den här artikeln innehåller dokumentation för:

Filformatet .http och redigeraren inspirerades av Visual Studio Code REST-klienttillägget. Visual Studio 2022 .http-redigeraren identifierar .rest som ett alternativt filnamnstillägg för samma filformat.

Förutsättningar

.http filsyntax

I följande avsnitt förklaras .http filsyntax.

Förfrågningar

Formatet för en HTTP-begäran är HTTPMethod URL HTTPVersion, allt på en rad, där:

  • HTTPMethod är den HTTP-metod som ska användas, till exempel:
  • URL är url:en som begäran ska skickas till. URL:en kan innehålla frågesträngsparametrar. URL:en behöver inte peka på ett lokalt webbprojekt. Den kan peka på alla URL:er som Visual Studio kan komma åt.
  • HTTPVersion är valfritt och anger den HTTP-version som ska användas, d.v.s. HTTP/1.1, HTTP/2eller HTTP/3.

En fil kan innehålla flera begäranden med hjälp av rader med ### som avgränsare. Följande exempel som visar tre begäranden i en fil illustrerar den här syntaxen:

GET https://localhost:7220/weatherforecast

###

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

###

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

###

Begärandehuvuden

Om du vill lägga till en eller flera rubriker lägger du till varje rubrik på sin egen rad direkt efter begäranderaden. Ta inte med några tomma rader mellan begäranderaden och den första rubriken eller mellan efterföljande rubrikrader. Formatet är HeaderName: Value, enligt följande exempel:

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

###

Viktig

När du anropar ett API som autentiserar med huvuden ska du inte överföra några hemligheter till ett källkodsförråd. Se de metoder som stöds för att lagra hemligheter senare i den här artikeln, till exempel ASP.NET Core-användarhemligheter, Azure Key Vault och DPAPI-kryptering.

Begärandetext

Lägg till begärandetexten efter en tom rad, enligt följande exempel:

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

###

Kommentarer

Rader som börjar med antingen # eller // är kommentarer. Dessa rader ignoreras när Visual Studio skickar HTTP-begäranden.

Variabler

En rad som börjar med @ definierar en variabel med hjälp av syntaxen @VariableName=Value.

Variabler kan refereras till i begäranden som definieras senare i filen. De refereras genom att omsluta sina namn i dubbla klammerparenteser, {{ och }}. I följande exempel visas två variabler som definierats och används i en begäran:

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

Variabler kan definieras med hjälp av värden för andra variabler som definierades tidigare i filen. I följande exempel används en variabel i begäran i stället för de två som visas i föregående exempel:

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

Miljöfiler

Om du vill ge variabler olika värden i olika miljöer skapar du en fil med namnet http-client.env.json. Leta upp filen i samma katalog som .http-filen eller i någon av dess överordnade kataloger. Här är ett exempel på en miljöfil:

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

Miljöfilen är en JSON-fil som innehåller en eller flera namngivna miljöer, till exempel "dev" och "remote" i föregående exempel. Varje namngiven miljö innehåller en eller flera variabler, till exempel HostAddress i föregående exempel. Variabler från en miljöfil refereras på samma sätt som andra variabler, som du ser i följande exempel:

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

Värdet som används för variabeln när du skickar en begäran bestäms av en listruta för miljöväljaren i det övre högra hörnet i .http filredigeraren. Följande skärmbild visar väljaren:

.http-filredigeraren med miljöväljaren markerad. Utvecklingsmiljön har valts.

Miljöfilen behöver inte finnas i projektmappen. Visual Studio letar efter en miljöfil i mappen där .http filen finns. Om den inte finns i den mappen söker Visual Studio igenom de överordnade katalogerna för att hitta den. När en fil med namnet http-client.env.json hittas avslutas sökningen. Filen som finns närmast den .http filen används.

När du har skapat eller redigerat en .http fil kan du behöva stänga och öppna projektet igen för att se ändringarna som återspeglas i miljöväljaren. Tryck på F6 för att välja miljöväljaren.

Visual Studio visar varningar i följande situationer:

  • Filen .http refererar till en variabel som inte har definierats i .http-filen eller i miljöfilen.
  • Miljöfilen innehåller en variabel som inte refereras till i filen .http.

En variabel som definieras i en miljöfil kan vara samma som den som definierats i .http-filen, eller så kan den vara annorlunda. Om en variabel definieras i både .http-filen och miljöfilen åsidosätter värdet i .http-filen värdet i miljöfilen.

Delade variabler

$shared är ett särskilt miljönamn för värden som är samma för flera miljöer. Tänk till exempel på följande miljöfil (http-client.env.json):

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

I föregående exempel definierar $shared-miljön variabeln HostAddress med värdet localhost:7293. Variabeln HostAddress med värdet localhost:7293 fungerar som standard för miljöer som inte definierar en HostAddress. När dev1- eller dev2-miljön har definierats kommer värdet för HostAddress från den $shared miljön eftersom dev1 och dev2 inte definierar en HostAddress variabel. När den staging miljön har definierats anges värdet för HostAddress till https://staging.contoso.com, vilket överskrider standardvärdet för $shared.

Användarspecifika miljöfiler

Ett användarspecifikt värde är ett värde som en utvecklare vill testa med men inte vill dela med teamet. Den http-client.env.json filen är incheckad i källkontrollen som standard, därför INTE lägga till användarspecifika värden i den här filen. Lägg i stället till användarspecifika värden i en fil med namnet http-client.env.json.user. Filen http-client.env.json.user finns i samma mapp som den http-client.env.json filen. Filer som slutar med .user undantas som standard från källkontrollen när du använder Visual Studio-funktioner för källkontroll.

När http-client.env.json-filen läses in letar Visual Studio efter en systerfil http-client.env.json.user. Om en variabel definieras i en miljö i både http-client.env.json-filen och den http-client.env.json.user filen vinner värdet i http-client.env.json.user-filen.

Här är ett exempelscenario som visar hur en användarspecifik miljöfil fungerar. Anta att filen .http har följande innehåll:

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

Anta att filen http-client.env.json innehåller följande innehåll:

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

Och anta att det finns en användarspecifik miljöfil som innehåller följande innehåll:

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

När användaren väljer "dev"-miljön skickas begäran till https://localhost:7128/swagger/index.html eftersom Path-värdet i http-client.env.json.user-filen åsidosätter värdet från http-client.env.json-filen.

Anta att variablerna definieras i filen .http med samma miljöfiler:

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

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

I det här scenariot skickas "dev"-miljöbegäran till https://contoso.com/weatherforecast eftersom variabeldefinitioner i .http filer åsidosätter miljöfildefinitioner.

ASP.NET Core-användarhemligheter

Om du vill hämta ett värde från användarhemligheteranvänder du en miljöfil som finns i samma mapp som ASP.NET Core-projektet. I miljöfilen definierar du en variabel som har egenskaper för provider och secretName. Ange värdet provider till AspnetUserSecrets och ange secretName till namnet på den önskade användarhemligheten. Följande miljöfil definierar till exempel en variabel med namnet ApiKeyDev som hämtar dess värde från config:ApiKeyDev användarhemlighet:

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

Om du vill använda den här variabeln i filen .http refererar du till den som en standardvariabel. Till exempel:

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

När begäran skickas finns hemlighetens värde för ApiKeyDev i X-API-KEY-rubriken.

När du skriver i filen http visar redigeraren en slutförandelista för variabelnamnet men visar inte dess värde.

Azure Key Vault

Azure Key Vault är en av flera viktiga hanteringslösningar i Azure som kan användas för hantering av hemligheter. Av de tre hemlighetslagringslösningar som för närvarande stöds för .http-filer är Key Vault det bästa valet för att dela dessa mellan olika användare. De andra två alternativen–ASP.NET User Secrets och DPAPI-kryptering– är svåra att dela.

Om du vill använda ett värde från Azure Key Vault måste du vara inloggad i Visual Studio med ett konto som har åtkomst till önskat Key Vault. Definiera en variabel i en miljöfil med metadata för att få åtkomst till hemligheten. Variabeln heter AKVSecret i följande exempel:

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

Variabeln AKVSecret hämtar sitt värde från Azure Key Vault. Följande egenskaper definieras på AKVSecret:

Namn Beskrivning
leverantör För Key Vault använder du alltid AzureKeyVault.
hemligtNamn Namnet på hemligheten som ska extraheras.
resourceId Azure-resurs-ID för det specifika Key Vault som ska kommas åt.

Värdet för egenskapen resourceId finns i Azure-portalen. Gå till Inställningar > Egenskaper för att hitta den. För secretNameanvänder du namnet på hemligheten som visas på sidan Secrets i Azure-portalen.

Följande .http-fil har till exempel en begäran som använder det här hemliga värdet.

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

DPAPI-kryptering

I Windows finns det en DATASKYDDS-API (DPAPI) som kan användas för att kryptera känsliga data. När DPAPI används för att kryptera data är de krypterade värdena alltid maskinspecifika, och de är också användarspecifika i .http filer. Dessa värden kan inte delas med andra användare.

Om du vill kryptera ett värde använder du följande konsolprogram:

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

Föregående konsolprogram refererar till System.Security.Cryptography.ProtectedData NuGet-paketet. Om du vill att det krypterade värdet ska fungera i filen .http krypterar du med omfånget inställt på DataProtectionScope.CurrentUser. Det krypterade värdet är en base64-kodad sträng som kan kopieras och klistras in i miljöfilen.

I miljöfilen skapar du en variabel som har egenskaper för provider och value. Ange provider till Encryptedoch ange value till det krypterade värdet. Följande miljöfil definierar till exempel en variabel med namnet dpapiValue som hämtar dess värde från en sträng som krypterades med DPAPI.

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

Med den föregående miljöfilen kan dpapiValue användas i .http-filen som vilken annan variabel som helst. Till exempel:

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

När den här begäran skickas har X-DPAPI-Secret det dekrypterade hemliga värdet.

Miljövariabler

Om du vill hämta värdet för en miljövariabel använder du $processEnv. I följande exempel placeras värdet för miljövariabeln USERNAME i X-UserName-huvudet.

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

Om du försöker använda $processEnv för att komma åt en miljövariabel som inte finns visas ett felmeddelande i .http filredigeraren.

.env filer

Om du vill hämta värdet för en variabel som har definierats i en .env fil använder du $dotenv. Filen .env måste finnas i projektmappen. Formatet för $dotenv är detsamma som för $processEnv. Om .env-filen till exempel har det här innehållet:

USERNAME=userFromDotenv

Och .http-filen har det här innehållet:

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

Rubriken X-UserName kommer att ha "userFromDotenv".

När $dotenv anges i redigeraren visas slutföranden för variablerna som definierats i filen .env.

Not

.env filer kanske inte utesluts från källkontrollen som standard, så var noga med att undvika att checka in några hemliga värden.

Slumpmässiga heltal

Om du vill generera ett slumpmässigt heltal använder du $randomInt. Syntaxen är {{$randomInt [min max]}} där värdena för min och max är valfria.

Datum och tider

  • $datetime genererar en datetime sträng i UTC. Syntaxen är {{$datetime [format] [offset option]}}, där formaterings- och förskjutningsalternativen är valfria.
  • $localDatetime genererar en datetime sträng i den lokala tidszonen. Syntaxen är {{$localDatetime [format] [offset option]}}, där formaterings- och förskjutningsalternativen är valfria.
  • $timeStamp genererar en timestamp i UTC. timestamp är det antalet sekunder sedan Unix-epoken i UTC-tid. Syntaxen är {{$timestamp [offset option]}} där förskjutningsalternativet är valfritt.

Alternativet [format] är ett av rfc1123, iso8601eller ett anpassat format inom citattecken. Till exempel:

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

Här är några exempelvärden som de föregående exemplen genererar:

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

Syntaxen för [offset option] är i formuläret numberunit där number är ett heltal och unit är ett av följande värden:

unit Förklaring
ms Millisekunder
s Sekunder
m Protokoll
h Timmar
d Dagar
w Veckor
M Månader
y År

Till exempel:

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

Här är några exempelvärden som de föregående exemplen genererar:

{
  "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ågra av föregående exempel använder den kostnadsfria webbplatsen med öppen källkod <httpbin.org>. Det här är en webbplats från tredje part som inte är ansluten till Microsoft. I dessa exempel returneras en svarstext med rubrikerna som skickades i begäran. Information om andra sätt att använda den här resursen för API-testning finns på httpbin.org webbplats startsida.

Syntax som inte stöds

Visual Studio 2022 .http filredigeraren har inte alla funktioner som Visual Studio Code REST klienttillägget har. Följande lista innehåller några av de mer viktiga funktionerna som endast är tillgängliga i Visual Studio Code-tillägget:

  • Begärningsrad som sträcker sig över flera rader
  • Namngivna begäranden
  • Ange filsökväg som brödtext i begäran
  • Blandat format för brödtext när du använder fleraparts-/formulärdata
  • GraphQL-begäranden
  • cURL-begäran
  • Kopiera/klistra in som cURL
  • Begärandehistorik
  • Spara svarstext i filen
  • Certifikatbaserad autentisering
  • Promptvariabler
  • Anpassa förhandsgranskning av svar
  • Inställningar per förfrågan

Skapa en .http fil

  • Högerklicka på ett ASP.NET Core-projekt i Solution Explorer.

  • I snabbmenyn väljer du Lägg till>Nytt objekt.

  • I dialogrutan Lägg till nytt objekt väljer du ASP.NET Core>Allmänt.

  • Välj HTTP-filoch välj Lägg till.

    dialogrutan Lägg till nytt objekt med HTTP-filtypen markerad.

Skicka en HTTP-begäran

  • Lägg till minst en begäran till en .http fil och spara filen.

  • Om begärans URL pekar på localhost och projektets port kör du projektet innan du försöker skicka en begäran till den.

  • Välj länken Send Request eller Debug som är direkt ovanför den begäran som ska skickas.

    Begäran skickas till den angivna URL:en och svaret visas i ett separat fönster till höger om redigeringsfönstret.

    .http-filredigeraren med knappen

.http filalternativ

Vissa aspekter av .http filbeteende kan konfigureras. Om du vill se vad som är tillgängligt går du till Verktyg>Alternativ>textredigeraren>Rest. Timeout-inställningen kan till exempel konfigureras på fliken Avancerat. Här är en skärmbild av dialogrutan Alternativ:

Alternativdialogrutan som visar textredigeraren och viloinställningen.

Använd Endpoints Explorer

Endpoints Explorer är ett verktygsfönster som visar alla slutpunkter som ett webb-API definierar. Med verktyget kan du skicka begäranden till slutpunkterna med hjälp av en .http fil.

Den första uppsättningen slutpunkter som visas av Endpoints Explorer identifieras statiskt. Det finns vissa slutpunkter som inte kan identifieras statiskt. Ändpunkter som definierats i ett klassbiblioteksprojekt kan till exempel inte upptäckas förrän vid körning. När du kör eller felsöker ett webb-API identifierar Visual Studio version 17.11 Preview slutpunkter dynamiskt vid körning och lägger även till dem i Endpoints Explorer.

Öppna Endpoints Explorer

Välj View>Other Windows>Endpoints Explorer.

Lägga till en begäran i en .http-fil

Högerklicka på en begäran i Endpoints Explorer och välj Generera begäran.

fönstret Endpoints Explorer som visar snabbmenyn för begäran med menyvalet

  • Om en .http-fil med projektnamnet som filnamn finns, läggs begäran till i den filen.
  • Annars skapas en .http fil med projektnamnet som filnamn och begäran läggs till i filen.

Föregående skärmbild visar slutpunkter som definierats av den minimala API-projektmallen. I följande exempel visas den begäran som genereras för den valda slutpunkten:

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

###

Skicka begäran enligt beskrivningen tidigare i den här artikeln.

Se även