Używanie plików HTTP w programie Visual Studio 2022

Edytor plików programu Visual Studio 2022.http zapewnia wygodny sposób testowania projektów ASP.NET Core, zwłaszcza aplikacji interfejsu API. Edytor udostępnia interfejs użytkownika, który:

• Tworzy i aktualizuje .http pliki.
• Wysyła żądania HTTP określone w .http plikach.
• Wyświetla odpowiedzi.

Ten artykuł zawiera dokumentację dla:

• Składnia .httppliku.
• Jak utworzyć .http plik.
• Jak wysłać żądanie z .http pliku.
• Gdzie można znaleźć .http opcje plików, które można skonfigurować.
• Jak tworzyć żądania w .http plikach przy użyciu Eksploratora punktów końcowych programu Visual Studio 2022.

.http Format pliku i edytor został zainspirowany rozszerzeniemREST. Edytor programu Visual Studio 2022 .http rozpoznaje .rest jako alternatywne rozszerzenie pliku dla tego samego formatu pliku.

Wymagania wstępne

• Program Visual Studio 2022 w wersji 17.8 lub nowszejz zainstalowanym obciążeniem ASP.NET i tworzenie aplikacji internetowych.

.http składnia pliku

W poniższych sekcjach opisano .http składnię pliku.

Żądania

Format żądania HTTP to HTTPMethod URL HTTPVersion, wszystko w jednym wierszu, gdzie:

• HTTPMethod to metoda HTTP do użycia, na przykład:
  • OPTIONS
  • GET
  • HEAD
  • POST
  • PUT
  • PATCH
  • DELETE
  • ŚLAD
  • POŁĄCZYĆ
• URL to adres URL do wysłania żądania. Adres URL może zawierać parametry ciągu zapytania. Adres URL nie musi wskazywać lokalnego projektu internetowego. Może wskazywać dowolny adres URL, do którego ma dostęp program Visual Studio.
• HTTPVersion jest opcjonalny i określa wersję PROTOKOŁU HTTP, która ma być używana, czyli , HTTP/1.1, HTTP/2lub HTTP/3.

Plik może zawierać wiele żądań przy użyciu wierszy z ogranicznikami ### . Poniższy przykład przedstawiający trzy żądania w pliku ilustruje następującą składnię:

GET https://localhost:7220/weatherforecast

###

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

###

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

###

Nagłówki żądań

Aby dodać co najmniej jeden nagłówek, dodaj każdy nagłówek w osobnym wierszu bezpośrednio po wierszu żądania. Nie dołączaj żadnych pustych wierszy między wierszem żądania a pierwszym nagłówkiem lub między kolejnymi wierszami nagłówka. Format to HeaderName: Value, jak pokazano w następujących przykładach:

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

###

Ważne

Podczas wywoływania interfejsu API, który uwierzytelnia się przy użyciu nagłówków, nie zatwierdzaj żadnych wpisów tajnych w repozytorium kodu źródłowego. Zobacz obsługiwane metody przechowywania wpisów tajnych w dalszej części tego artykułu, takie jak ASP.NET Podstawowe wpisy tajne użytkownika, usługa Azure Key Vault i szyfrowanie DPAPI.

Treść żądania

Dodaj treść żądania po pustym wierszu, jak pokazano w poniższym przykładzie:

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

###

Komentarze

Wiersze rozpoczynające się od # lub // są komentarzami. Te wiersze są ignorowane, gdy program Visual Studio wysyła żądania HTTP.

Zmienne

Wiersz rozpoczynający się od @ definiuje zmienną przy użyciu składni @VariableName=Value.

Zmienne można odwoływać się do żądań zdefiniowanych w dalszej części pliku. Odwołuje się do nich zawijanie ich nazw w podwójnych nawiasach klamrowych {{ i }}. W poniższym przykładzie przedstawiono dwie zmienne zdefiniowane i używane w żądaniu:

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

Zmienne można zdefiniować przy użyciu wartości innych zmiennych, które zostały zdefiniowane wcześniej w pliku. W poniższym przykładzie użyto jednej zmiennej w żądaniu zamiast dwóch pokazanych w poprzednim przykładzie:

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

Pliki środowiska

Aby nadać zmienne różne wartości w różnych środowiskach, utwórz plik o nazwie http-client.env.json. Znajdź plik w tym samym katalogu co .http plik lub w jednym z katalogów nadrzędnych. Oto przykład pliku środowiska:

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

Plik środowiska jest plikiem JSON zawierającym co najmniej jedno nazwane środowiska, takie jak "dev" i "remote" w poprzednim przykładzie. Każde nazwane środowisko zawiera co najmniej jedną zmienną, na przykład HostAddress w poprzednim przykładzie. Zmienne z pliku środowiskowego odwołują się do tego samego, co inne zmienne, jak pokazano w poniższym przykładzie:

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

Wartość używana dla zmiennej podczas wysyłania żądania jest określana przez listę rozwijaną selektora środowiska w prawym górnym rogu edytora .http plików. Poniższy zrzut ekranu przedstawia selektor:

Plik środowiska nie musi znajdować się w folderze projektu. Program Visual Studio wyszukuje plik środowiska w folderze, w którym .http istnieje plik. Jeśli nie znajduje się on w tym folderze, program Visual Studio przegląda katalogi nadrzędne, aby go znaleźć. Po znalezieniu pliku o nazwie http-client.env.json wyszukiwanie kończy się. Używany jest plik znajdujący się najbliżej .http pliku.

Po utworzeniu lub edytowaniu .http pliku może być konieczne zamknięcie i ponowne otwarcie projektu, aby zobaczyć zmiany odzwierciedlone w selektorze środowiska. Naciśnij F6 , aby wybrać selektor środowiska.

Program Visual Studio wyświetla ostrzeżenia w następujących sytuacjach:

• Plik .http odwołuje się do zmiennej, która nie jest zdefiniowana w .http pliku ani w pliku środowiska.
• Plik środowiska zawiera zmienną, do którego nie odwołuje się .http plik.

Zmienna zdefiniowana w pliku środowiskowym może być taka sama jak zmienna zdefiniowana w .http pliku lub może być inna. Jeśli zmienna jest zdefiniowana zarówno w pliku, .http jak i pliku środowiska, wartość w .http pliku zastępuje wartość w pliku środowiska.

Pliki środowiska specyficzne dla użytkownika

Wartość specyficzna dla użytkownika to dowolna wartość, z którą dany deweloper chce przetestować, ale nie chce udostępniać zespołowi. http-client.env.json Ponieważ plik jest domyślnie zaewidencjonowany do kontroli źródła, nie byłoby odpowiednie dodanie wartości specyficznych dla użytkownika do tego pliku. Zamiast tego umieść je w pliku o nazwie http-client.env.json.user znajdującej się w tym samym folderze co http-client.env.json plik. Pliki kończące się elementem .user powinny być domyślnie wykluczone z kontroli źródła podczas korzystania z funkcji kontroli źródła programu Visual Studio.

Po załadowaniu http-client.env.json pliku program Visual Studio szuka pliku równorzędnego http-client.env.json.user . Jeśli zmienna jest zdefiniowana w środowisku zarówno http-client.env.json w pliku, jak i http-client.env.json.user w pliku, wartość w http-client.env.json.user pliku zostanie wygrana.

Oto przykładowy scenariusz pokazujący, jak działa plik środowiska specyficzny dla użytkownika. Załóżmy, .http że plik ma następującą zawartość:

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

Załóżmy, że http-client.env.json plik zawiera następującą zawartość:

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

Załóżmy, że istnieje plik środowiska specyficzny dla użytkownika zawierający następującą zawartość:

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

Gdy użytkownik wybierze środowisko "dev", żądanie zostanie wysłane, https://localhost:7128/swagger/index.html ponieważ wartość w Path pliku zastępuje wartość z http-client.env.json.userhttp-client.env.json pliku.

W przypadku tych samych plików środowiskowych załóżmy, że zmienne są zdefiniowane w .http pliku:

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

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

W tym scenariuszu żądanie środowiska "dev" jest wysyłane do https://contoso.com/weatherforecast , ponieważ definicje zmiennych w .http plikach zastępują definicje plików środowiska.

wpisy tajne użytkownika platformy ASP.NET Core

Aby uzyskać wartość z wpisów tajnych użytkownika, użyj pliku środowiskowego znajdującego się w tym samym folderze co projekt ASP.NET Core. W pliku środowiska zdefiniuj zmienną, która ma provider właściwości i secretName . provider Ustaw wartość AspnetUserSecrets na i ustaw secretName na nazwę żądanego wpisu tajnego użytkownika. Na przykład następujący plik środowiska definiuje zmienną o nazwie ApiKeyDev , która pobiera jej wartość z wpisu tajnego config:ApiKeyDev użytkownika:

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

Aby użyć tej zmiennej .http w pliku, odwołaj się do niej jak zmienna standardowa. Na przykład:

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

Po wysłaniu żądania wartość wpisu tajnego ApiKeyDev znajduje się w nagłówku X-API-KEY.

Podczas wpisywania http pliku edytor wyświetla listę uzupełniania dla nazwy zmiennej, ale nie wyświetla jej wartości.

Azure Key Vault

Usługa Azure Key Vault jest jednym z kilku kluczowych rozwiązań do zarządzania na platformie Azure, które mogą być używane do zarządzania wpisami tajnymi. Spośród trzech magazynów wpisów tajnych obecnie obsługiwanych dla .http plików usługa Key Vault jest najlepszym wyborem do udostępniania wpisów tajnych między różnymi użytkownikami. Pozostałe dwie opcje — ASP.NET wpisy tajne użytkownika i szyfrowanie DPAPI — nie są łatwo udostępniane.

Aby użyć wartości z usługi Azure Key Vault, musisz zalogować się do programu Visual Studio przy użyciu konta, które ma dostęp do żądanej usługi Key Vault. Zdefiniuj zmienną w pliku środowiskowym z metadanymi, aby uzyskać dostęp do wpisu tajnego. Zmienna ma nazwę AKVSecret w poniższym przykładzie:

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

Zmienna AKVSecret pobiera swoją wartość z usługi Azure Key Vault. Następujące właściwości są definiowane w pliku AKVSecret:

Nazwa/nazwisko	opis
dostawca	W przypadku usługi Key Vault zawsze używaj polecenia AzureKeyVault.
secretName	Nazwa wpisu tajnego do wyodrębnienia.
resourceId	Identyfikator zasobu platformy Azure dla określonej usługi Key Vault w celu uzyskania dostępu.

Wartość resourceId właściwości można znaleźć w witrynie Azure Portal. Przejdź do > ustawień, aby je znaleźć. W przypadku secretNameprogramu użyj nazwy wpisu tajnego wyświetlanego na stronie Wpisy tajne w witrynie Azure Portal.

Na przykład poniższy .http plik zawiera żądanie, które używa tej wartości wpisu tajnego.

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

Szyfrowanie DPAPI

W systemie Windows istnieje interfejs API ochrony danych (DPAPI), który może służyć do szyfrowania poufnych danych. Gdy interfejs DPAPI jest używany do szyfrowania danych, zaszyfrowane wartości są zawsze specyficzne dla maszyny i są również specyficzne dla użytkownika w .http plikach. Tych wartości nie można udostępniać innym użytkownikom.

Aby zaszyfrować wartość, użyj następującej aplikacji konsolowej:

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

Poprzednia aplikacja konsolowa odwołuje się do pakietu NuGet System.Security.Cryptography.ProtectedData . Aby włączyć zaszyfrowaną wartość do pracy w .http pliku, zaszyfruj za pomocą zakresu ustawionego na DataProtectionScope.CurrentUser. Zaszyfrowana wartość jest ciągiem zakodowanym w formacie base64, który można skopiować i wkleić do pliku środowiska.

W pliku środowiska utwórz zmienną, która ma provider właściwości i .value Ustaw provider wartość Encryptedi ustaw value wartość na wartość zaszyfrowaną. Na przykład poniższy plik środowiska definiuje zmienną o nazwie dpapiValue , która pobiera jej wartość z ciągu zaszyfrowanego przy użyciu interfejsu DPAPI.

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

Z poprzednim plikiem środowiska można użyć w dpapiValue pliku .http tak jak każda inna zmienna. Na przykład:

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

Po wysłaniu tego żądania klucz tajny X-DPAPI-Secret ma odszyfrowywane wartości wpisu tajnego.

Zmienne środowiskowe

Aby uzyskać wartość zmiennej środowiskowej, użyj polecenia $processEnv. W poniższym przykładzie wartość zmiennej środowiskowej USERNAME jest umieszczana w nagłówku X-UserName.

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

Jeśli spróbujesz użyć $processEnv metody w celu uzyskania dostępu do zmiennej środowiskowej, która nie istnieje, .http w edytorze plików zostanie wyświetlony komunikat o błędzie.

.env Pliki

Aby uzyskać wartość zmiennej zdefiniowanej .env w pliku, użyj polecenia $dotenv. Plik .env musi znajdować się w folderze projektu. Format dla $dotenv parametru jest taki sam jak w przypadku $processEnv. Jeśli na przykład plik ma następującą .env zawartość:

USERNAME=userFromDotenv

Plik ma następującą .http zawartość:

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

Nagłówek X-UserName będzie miał wartość "userFromDotenv".

Po $dotenv wprowadzeniu w edytorze są wyświetlane uzupełnienia zmiennych zdefiniowanych w .env pliku.

Uwaga

.env pliki mogą nie być domyślnie wykluczone z kontroli źródła, dlatego należy zachować ostrożność, aby uniknąć ewidencjonowania żadnych wartości wpisów tajnych.

Liczby całkowite losowe

Aby wygenerować losową liczbę całkowitą, użyj polecenia $randomInt. Składnia to {{$randomInt [min max]}} miejsce, w którym min wartości i max są opcjonalne.

Daty i godziny

• $datetime generuje datetime ciąg w formacie UTC. Składnia polega {{$datetime [format] [offset option]}} na tym, że opcje formatowania i przesunięcia są opcjonalne.
• $localDatetime generuje datetime ciąg w lokalnej strefie czasowej. Składnia polega {{$localDatetime [format] [offset option]}} na tym, że opcje formatowania i przesunięcia są opcjonalne.
• $timeStamp generuje wartość timestamp w formacie UTC. Jest timestamp to liczba sekund od epoki unix w czasie UTC. Składnia polega {{$timestamp [offset option]}} na tym, że opcja przesunięcia jest opcjonalna.

Opcja [format] jest jednym z rfc1123, iso8601lub formatu niestandardowego w cudzysłowie. Na przykład:

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

Poniżej przedstawiono kilka przykładowych wartości generowanych przez powyższe przykłady:

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

Składnia [offset option] jest w postaci numberunit , w której number jest liczbą całkowitą i unit jest jedną z następujących wartości:

unit	Wyjaśnienie
ms	Milisekundy
s	Sekundy
m	Minuty
h	godzin(y)
d	dni
w	Tygodnie
M	Miesiące
y	Lata

Na przykład:

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

Poniżej przedstawiono kilka przykładowych wartości generowanych przez powyższe przykłady:

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

Niektóre z powyższych przykładów używają bezpłatnej witryny internetowej <typu open source httpbin.org>. Jest to witryna internetowa innej firmy, która nie jest powiązana z firmą Microsoft. W tych przykładach zwraca treść odpowiedzi z nagłówkami, które zostały wysłane w żądaniu. Aby uzyskać informacje o innych sposobach używania tego zasobu do testowania home interfejsu API, zobacz stronę witryny httpbin.org.

Nieobsługiwana składnia

Edytor plików programu Visual Studio 2022 .http nie ma wszystkich funkcji, które ma rozszerzenieREST. Poniższa lista zawiera niektóre z bardziej znaczących funkcji dostępnych tylko w rozszerzeniu programu Visual Studio Code:

• Wiersz żądania obejmujący więcej niż jeden wiersz
• Nazwane żądania
• Określ ścieżkę pliku jako treść żądania
• Format mieszany treści w przypadku używania danych wieloczęściowych/formularzy
• Żądania GraphQL
• Żądanie cURL
• Kopiowanie/wklejanie jako cURL
• Historia żądań
• Zapisywanie treści odpowiedzi w pliku
• Uwierzytelnianie oparte na certyfikatach
• Zmienne monitu
• Dostosowywanie podglądu odpowiedzi
• Ustawienia poszczególnych żądań

Tworzenie .http pliku

• W Eksplorator rozwiązań kliknij prawym przyciskiem myszy projekt ASP.NET Core.

• W menu kontekstowym wybierz pozycję Dodaj>nowy element.

• W oknie dialogowym Dodawanie nowego elementu wybierz pozycję ASP.NET Core>Ogólne.

• Wybierz pozycję Plik HTTP, a następnie wybierz pozycję Dodaj.

  

Wysyłanie żądania HTTP

• Dodaj co najmniej jedno żądanie do .http pliku i zapisz plik.

• Jeśli adres URL żądania wskazuje localhost i port projektu, uruchom projekt przed próbą wysłania żądania do niego.

• Send Request Wybierz link lub Debug bezpośrednio powyżej żądania do wysłania.

  Żądanie jest wysyłane do określonego adresu URL, a odpowiedź pojawia się w osobnym okienku po prawej stronie okna edytora.

  

.http opcje pliku

Niektóre aspekty .http zachowania pliku można skonfigurować. Aby zobaczyć, co jest dostępne, przejdź do pozycji Narzędzia>Opcje>Edytor>Rest tekstu. Na przykład ustawienie limitu czasu można skonfigurować na karcie Zaawansowane . Oto zrzut ekranu przedstawiający okno dialogowe Opcje :

Korzystanie z Eksploratora punktów końcowych

Eksplorator punktów końcowych to okno narzędzi pokazujące wszystkie punkty końcowe zdefiniowane przez internetowy interfejs API. Narzędzie umożliwia wysyłanie żądań do punktów końcowych przy użyciu .http pliku.

Początkowy zestaw punktów końcowych wyświetlanych przez eksploratora punktów końcowych jest wykrywany statycznie. Istnieje kilka punktów końcowych, których nie można odnaleźć statycznie. Na przykład punkty końcowe zdefiniowane w projekcie biblioteki klas nie mogą być odnajdywane do czasu uruchomienia. Podczas uruchamiania lub debugowania internetowego interfejsu API program Visual Studio w wersji 17.11 (wersja zapoznawcza) odnajduje punkty końcowe dynamicznie w czasie wykonywania oraz dodaje je do Eksploratora punktów końcowych.

Otwieranie Eksploratora punktów końcowych

Wybierz pozycję Wyświetl>inne eksploratora punktów końcowych systemu Windows.>

Dodawanie żądania do .http pliku

Kliknij prawym przyciskiem myszy żądanie w Eksploratorze punktów końcowych i wybierz polecenie Generuj żądanie.

• .http Jeśli plik o nazwie projektu jako nazwa pliku istnieje, żądanie zostanie dodane do tego pliku.
• .http W przeciwnym razie plik zostanie utworzony z nazwą projektu jako nazwą pliku, a żądanie zostanie dodane do tego pliku.

Powyższy zrzut ekranu przedstawia punkty końcowe zdefiniowane przez minimalny szablon projektu interfejsu API. W poniższym przykładzie pokazano żądanie wygenerowane dla wybranego punktu końcowego:

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

###

Wyślij żądanie zgodnie z opisem we wcześniejszej sekcji tego artykułu.

Zobacz też

• Okno Eksploratora punktów końcowych rozpoznaje tylko ciągi literału dla tras
• Tworzenie internetowego interfejsu API w programie Visual Studio 2022
• Rozszerzenie klienta programu Visual Studio Code REST