Använda .http-filer i Visual Studio 2022

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:

• Syntaxen för .http-filen.
• Skapa en .http-fil.
• Så här skickar du en begäran från en .http-fil.
• Var hittar du .http filalternativ som kan konfigureras.
• Så här skapar du begäranden i .http filer med hjälp av Visual Studio 2022 Endpoints Explorer.

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

• Visual Studio 2022 version 17.8 eller senare med arbetsbelastningen ASP.NET och webbutveckling installerad.

.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:
  • ALTERNATIV
  • GET
  • HEAD
  • POST
  • PUT
  • PATCH
  • DELETE
  • TRACE
  • CONNECT
• 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

###

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. Variabelnamnet är skiftlägeskänsligt och får inte innehålla några blanksteg. Värdet kan innehålla alla tecken, inklusive värdet null för att representera ett null-värde.

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:

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.

Begärandevariabler

Du kan skicka värden från en HTTP-begäran till en annan i samma .http fil.

1. Skapa en enradskommentar som finns precis före en begärande-URL för att namnge följande begäran. Följande rader visar till exempel alternativa sätt att namnge begäran login:

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

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

2. I efterföljande begäranden i samma HTTP-fil använder du begärandenamnet för att referera till begäran.

3. Använd följande syntax för att extrahera den specifika delen av det svar som du vill använda.

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

   Med den här syntaxen kan du extrahera värden från själva begäran eller från svaret på den (request|response). För begäran eller svar kan du extrahera värden från brödtexten eller rubrikerna (body|headers).

   När body har valts gäller den *|JSONPath|XPath delen av syntaxen:

   • * extraherar hela svarstexten.

     Exempel: {{login.response.body.*}}

   • För JSON-svar använder du JSONPath- för att extrahera en specifik egenskap eller ett visst attribut.

     Exempel: {{login.response.body.$.token}}

   • För XML-svar använder du XPath- för att extrahera en specifik egenskap eller ett visst attribut.

     Exempel: {{login.response.body./token}}

   När headers har valts extraherar ett rubriknamn hela rubriken. Rubriknamn är inte skiftlägeskänsliga.

   Exempel: {{login.response.headers.Location}}

Om du vill referera till svaret på en namngiven begäran måste du utlösa den namngivna begäran manuellt för att hämta svaret först. När du extraherar värden från svaret får du det senaste svaret om begäran har skickats mer än en gång.

Exempel på användning av variabel för begäran

Anta till exempel att HTTP-filen har en begäran som autentiserar anroparen och du ger den namnet login. Svarstexten är ett JSON-dokument som innehåller ägartoken i en egenskap med namnet token. I efterföljande begäranden vill du skicka in den här ägartoken i ett Authorization-huvud. Följande exempel gör detta:

# @name login

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

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

### 

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

### 

Syntaxen {{login.response.body.$.token}} representerar ägartoken:

• login: Är namnet på begäran.
• response: Refererar till HTTP-svarsobjektet.
• body: Refererar till brödtexten i HTTP-svaret.
• $: Representerar rotelementet i JSON-dokumentet i svarstexten.
• token: Refererar till den specifika egenskapen i JSON-dokumentet.

Utan att använda begärandevariabler skulle du behöva extrahera token manuellt från inloggningssvaret och inkludera den i rubriken för efterföljande begäranden. Med begärandevariabler kan du automatisera den här processen.

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:

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.

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:

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
• 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
• Null-hanteringsvariabler, t.ex. med hjälp av null-villkorsstyrda operatorer eller null-sammankopplingsoperatorer (detta stöds inte heller i Visual Studio Code)

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.

  

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

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.

• 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

• Endpoints Explorer-fönstret känner bara igen literalsträngar för rutter
• webb-API-utveckling i Visual Studio 2022
• Visual Studio Code REST Klienttillägg