Visual Studio 2022'de .http dosyalarını kullanma

Visual Studio 2022 .http dosya düzenleyicisi, ASP.NET Core projelerini, özellikle API uygulamalarını test etmek için kullanışlı bir yol sağlar. Düzenleyici, aşağıdakileri sağlayan bir kullanıcı arabirimi sağlar:

• Dosyaları oluşturur ve güncelleştirir .http .
• Dosyalarda .http belirtilen HTTP isteklerini gönderir.
• Yanıtları görüntüler.

Bu makalede şunlara yönelik belgeler yer alır:

• Dosya .http söz dizimi.
• Dosya oluşturma.http.
• Bir dosyadan .httpistek gönderme.
• Yapılandırılabilir dosya seçenekleri nerede bulunur .http ?.
• Visual Studio 2022 Uç Nokta Gezgini'ni kullanarak dosyalarda istek .http oluşturma.

.http Dosya biçimi ve düzenleyici, Visual Studio Code REST İstemci uzantısından esinlendi. Visual Studio 2022 .http düzenleyicisi, aynı dosya biçimi için alternatif bir dosya uzantısı olarak tanır .rest .

Önkoşullar

• ASP.NET ve web geliştirme iş yükünün yüklü olduğu Visual Studio 2022 sürüm 17.8 veya üzeri.

.http dosya söz dizimi

Aşağıdaki bölümlerde dosya söz dizimi açıklanmaktadır .http .

İstekler

HTTP isteğinin biçimi, tek bir satırdadır HTTPMethod URL HTTPVersionve burada:

• HTTPMethod kullanılacak HTTP yöntemidir, örneğin:
  • OPTIONS
  • GET
  • HEAD
  • POST
  • PUT
  • PATCH
  • DELETE
  • İZ
  • BAĞLAMAK
• URL , isteğin gönderiliyor olduğu URL'dir. URL, sorgu dizesi parametrelerini içerebilir. URL'nin yerel bir web projesine işaret etmek zorunda değildir. Visual Studio'nın erişebileceği herhangi bir URL'ye işaret edebilir.
• HTTPVersionisteğe bağlıdır ve kullanılması gereken HTTP sürümünü ( , HTTP/1.1HTTP/2veya HTTP/3) belirtir.

Bir dosya, sınırlayıcı olarak satırları ### kullanarak birden çok istek içerebilir. Bir dosyada üç isteği gösteren aşağıdaki örnekte bu söz dizimi gösterilmektedir:

GET https://localhost:7220/weatherforecast

###

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

###

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

###

İstek üst bilgileri

Bir veya daha fazla üst bilgi eklemek için, her üst bilgiyi istek satırından hemen sonra kendi satırına ekleyin. İstek satırıyla ilk üst bilgi arasına veya sonraki üst bilgi satırları arasına boş satır eklemeyin. Biçimi, aşağıdaki örneklerde gösterildiği gibi şeklindedir HeaderName: Value:

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

###

Önemli

Üst bilgilerle kimlik doğrulaması yapan bir API'yi çağırırken, bir kaynak kodu deposuna gizli dizi işlemeyin. Bu makalenin devamında ASP.NET Core kullanıcı gizli dizileri, Azure Key Vault ve DPAPI şifrelemesi gibi gizli dizileri depolamak için desteklenen yöntemlere bakın.

Request body

Aşağıdaki örnekte gösterildiği gibi istek gövdesini boş bir satırdan sonra ekleyin:

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

###

Açıklamalar

Ya da # // açıklamalarla başlayan satırlar. Visual Studio HTTP istekleri gönderdiğinde bu satırlar yoksayılır.

Değişkenler

ile @ başlayan bir satır, söz dizimini @VariableName=Valuekullanarak bir değişken tanımlar.

Daha sonra dosyada tanımlanan isteklerde değişkenlere başvurulabilir. Bunlara, adlarını çift küme ayracı ve }}içine sarmalayarak başvurulur{{. Aşağıdaki örnekte, bir istekte tanımlanan ve kullanılan iki değişken gösterilmektedir:

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

Değişkenler, dosyada daha önce tanımlanmış olan diğer değişkenlerin değerleri kullanılarak tanımlanabilir. Aşağıdaki örnek, önceki örnekte gösterilen iki değişken yerine istekte bir değişken kullanır:

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

Ortam dosyaları

Değişkenlere farklı ortamlarda farklı değerler vermek için adlı http-client.env.jsonbir dosya oluşturun. Dosyayı, dosyayla aynı dizinde .http veya üst dizinlerinden birinde bulun. Aşağıda bir ortam dosyası örneği verilmiştir:

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

Ortam dosyası, önceki örnekteki "dev" ve "remote" gibi bir veya daha fazla adlandırılmış ortam içeren bir JSON dosyasıdır. Her adlandırılmış ortam, önceki örnekte olduğu gibi HostAddress bir veya daha fazla değişken içerir. Ortam dosyasındaki değişkenlere, aşağıdaki örnekte gösterildiği gibi diğer değişkenlerle aynı şekilde başvurulur:

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

İstek gönderirken değişken için kullanılan değer, dosya düzenleyicisinin sağ üst köşesindeki .http bir ortam seçici açılan listesi tarafından belirlenir. Aşağıdaki ekran görüntüsünde seçici gösterilmektedir:

Ortam dosyasının proje klasöründe olması gerekmez. Visual Studio, dosyanın bulunduğu .http klasörde bir ortam dosyası arar. Bu klasörde değilse, Visual Studio bulmak için üst dizinlere bakar. adlı http-client.env.json bir dosya bulunduğunda arama sona erer. Dosyaya .http en yakın bulunan dosya kullanılır.

Dosyayı .http oluşturduktan veya düzenledikten sonra, ortam seçiciye yansıtılan değişiklikleri görmek için projeyi kapatıp yeniden açmanız gerekebilir. Ortam seçiciyi seçmek için F6 tuşuna basın.

Visual Studio aşağıdaki durumlarda uyarılar görüntüler:

• Dosya, .http dosyada veya ortam dosyasında tanımlanmayan .http bir değişkene başvurur.
• Ortam dosyası, dosyada .http başvurulmuyor bir değişken içeriyor.

Ortam dosyasında tanımlanan değişken, dosyada .http tanımlanan değişkenle aynı veya farklı olabilir. Bir değişken hem dosyada hem de .http ortam dosyasında tanımlanmışsa, dosyadaki .http değer ortam dosyasındaki değeri geçersiz kılar.

Kullanıcıya özgü ortam dosyaları

Kullanıcıya özgü bir değer, tek bir geliştiricinin test etmek istediği ancak ekiple paylaşmak istemediği herhangi bir değerdir. http-client.env.json Dosya varsayılan olarak kaynak denetiminde iade edilmiş olduğundan, bu dosyaya kullanıcıya özgü değerler eklemek uygun olmaz. Bunun yerine, bunları dosyayla aynı klasörde bulunan adlı http-client.env.json.user bir dosyaya http-client.env.json yerleştirin. ile .user biten dosyalar, Visual Studio kaynak denetimi özellikleri kullanılırken varsayılan olarak kaynak denetiminden dışlanmalıdır.

http-client.env.json Dosya yüklendiğinde, Visual Studio eşdüzey http-client.env.json.user bir dosya arar. Bir değişken hem dosyadaki hem de http-client.env.json dosyadaki http-client.env.json.user bir ortamda tanımlanırsa, dosyadaki http-client.env.json.user değer kazanır.

Kullanıcıya özgü bir ortam dosyasının nasıl çalıştığını gösteren örnek bir senaryo aşağıda verilmiştir. Dosyada .http aşağıdaki içeriğe sahip olduğunu varsayalım:

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

Dosyanın aşağıdaki içeriği içerdiğini varsayalım http-client.env.json :

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

Ayrıca aşağıdaki içeriği içeren kullanıcıya özgü bir ortam dosyası olduğunu varsayalım:

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

Kullanıcı "dev" ortamını seçtiğinde, dosyadaki değer dosyadaki değeri geçersiz kıldığından Path istek gönderilirhttps://localhost:7128/swagger/index.html.http-client.env.json.user http-client.env.json

Aynı ortam dosyalarıyla, değişkenlerin dosyada .http tanımlandığını varsayalım:

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

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

Bu senaryoda, dosyalardaki değişken tanımları ortam dosyası tanımlarını .http geçersiz kıldığından "dev" ortam isteği gönderilirhttps://contoso.com/weatherforecast.

ASP.NET Core kullanıcı gizli dizileri

Kullanıcı gizli dizilerinden bir değer almak için, ASP.NET Core projesiyle aynı klasörde bulunan bir ortam dosyasını kullanın. Ortam dosyasında ve secretName özelliklerine sahip provider bir değişken tanımlayın. provider değerini AspnetUserSecrets olarak ayarlayın ve istenen kullanıcı gizli dizisinin adına ayarlayınsecretName. Örneğin, aşağıdaki ortam dosyası kullanıcı gizli dizisinden config:ApiKeyDev değerini alan adlı ApiKeyDev bir değişken tanımlar:

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

Bu değişkeni dosyada .http kullanmak için standart değişken gibi başvurun. Örneğin:

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

İstek gönderildiğinde, gizli dizinin değeri ApiKeyDev X-API-KEY üst bilgisindedir.

Siz dosyaya http yazarken, düzenleyici değişken adı için bir tamamlanma listesi gösterir ancak değerini göstermez.

Azure Key Vault

Azure Key Vault , Azure'da gizli dizi yönetimi için kullanılabilecek çeşitli anahtar yönetimi çözümlerinden biridir. Şu anda dosyalar için .http desteklenen üç gizli dizi deposundan Key Vault, gizli dizileri farklı kullanıcılar arasında paylaşmak için en iyi seçenektir. Kullanıcı Gizli Dizileri ve DPAPI şifrelemesi ASP.NET diğer iki seçenek kolayca paylaşılamaz.

Azure Key Vault'tan bir değer kullanmak için, visual studio'da istenen Key Vault'a erişimi olan bir hesapla oturum açmanız gerekir. Gizli diziye erişmek için meta verileri içeren bir ortam dosyasında bir değişken tanımlayın. Değişkeni aşağıdaki örnekte adlandırılmıştır AKVSecret :

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

değişkeni AKVSecret değerini Azure Key Vault'tan çeker. Aşağıdaki özellikler üzerinde AKVSecrettanımlanır:

Veri Akışı Adı	Açıklama
sağlayıcı	Key Vault için her zaman kullanın AzureKeyVault.
secretName	Ayıklanması gereken gizli dizinin adı.
resourceId	Erişecek belirli Key Vault için Azure kaynak kimliği.

Özelliğin resourceId değeri Azure portalında bulunabilir. Bulmak için Ayarlar > Özellikleri'ne gidin. için secretName, Azure portalındaki Gizli Diziler sayfasında görünen gizli dizinin adını kullanın.

Örneğin, aşağıdaki .http dosyada bu gizli dizi değerini kullanan bir istek vardır.

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

DPAPI şifrelemesi

Windows'ta, hassas verileri şifrelemek için kullanılabilecek bir Veri Koruma API'si (DPAPI) vardır. Verileri şifrelemek için DPAPI kullanıldığında, şifrelenmiş değerler her zaman makineye özgüdür ve dosyalarda .http da kullanıcıya özgüdür. Bu değerler diğer kullanıcılarla paylaşılamaz.

Bir değeri şifrelemek için aşağıdaki konsol uygulamasını kullanın:

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

Yukarıdaki konsol uygulaması System.Security.Cryptography.ProtectedData NuGet paketine başvurur. Şifrelenmiş değerin dosyada .http çalışmasını sağlamak için, kapsamı olarak ayarlanmış DataProtectionScope.CurrentUserşekilde şifreleyin. Şifrelenmiş değer, ortam dosyasına kopyalanıp yapıştırılabilen base64 kodlanmış bir dizedir.

Ortam dosyasında ve value özelliklerine sahip provider bir değişken oluşturun. olarak Encryptedayarlayın provider ve şifrelenmiş değere ayarlayınvalue. Örneğin, aşağıdaki ortam dosyası, değerini DPAPI ile şifrelenmiş bir dizeden alan adlı dpapiValue bir değişken tanımlar.

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

Önceki ortam dosyasıyla, dpapiValue dosyada .http diğer değişkenler gibi kullanılabilir. Örneğin:

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

Bu istek gönderildiğinde, X-DPAPI-Secret şifresi çözülmüş gizli dizi değerine sahiptir.

Ortam değişkenleri

Ortam değişkeninin değerini almak için kullanın $processEnv. Aşağıdaki örnek, USERNAME ortam değişkeninin değerini X-UserName üst bilgisine yerleştirir.

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

Mevcut olmayan bir ortam değişkenine erişmek için kullanmayı $processEnv denerseniz, .http dosya düzenleyicisi bir hata iletisi görüntüler.

.env Dosyaları

Bir dosyada .env tanımlanan değişkenin değerini almak için kullanın $dotenv. Dosya .env proje klasöründe olmalıdır. için $dotenv biçimi ile aynıdır $processEnv. Örneğin, dosyada .env bu içerik varsa:

USERNAME=userFromDotenv

Dosyada .http şu içerik vardır:

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

Üst X-UserName bilgide "userFromDotenv" bulunur.

Düzenleyiciye girildiğinde $dotenv , dosyada .env tanımlanan değişkenlerin tamamlanmalarını gösterir.

Not

.env dosyalar varsayılan olarak kaynak denetiminden dışlanmayabilir, bu nedenle gizli dizi değerlerinin denetlenmemesi için dikkatli olun.

Rastgele tamsayılar

Rastgele bir tamsayı oluşturmak için kullanın $randomInt. Söz dizimi, {{$randomInt [min max]}} ve max değerlerinin min isteğe bağlı olduğu yerdir.

Tarihler ve saatler

• $datetime UTC'de bir datetime dize oluşturur. Söz dizimi, {{$datetime [format] [offset option]}} biçim ve uzaklık seçeneklerinin isteğe bağlı olduğu yerdir.
• $localDatetime yerel saat diliminde bir datetime dize oluşturur. Söz dizimi, {{$localDatetime [format] [offset option]}} biçim ve uzaklık seçeneklerinin isteğe bağlı olduğu yerdir.
• $timeStamp utc olarak bir timestamp oluşturur. timestamp, UTC saatinde Unix Dönemi'nin üzerinden geçen saniye sayısıdır. Söz dizimi, {{$timestamp [offset option]}} uzaklık seçeneğinin isteğe bağlı olduğu yerdir.

Seçenek[format], tırnak içinde , iso8601veya özel bir biçimden biridirrfc1123. Örneğin:

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

Yukarıdaki örneklerin oluşturduğu bazı örnek değerler şunlardır:

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

Söz [offset option] dizimi, tamsayı olan number formdadır number unit ve unit aşağıdaki değerlerden biridir:

unit	Açıklama
ms	Milisaniye
s	Saniye
m	Dakika
h	Saat Sayısı
d	Gün sayısı
w	Hafta
M	Aylar
y	Yıl

Örneğin:

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

Yukarıdaki örneklerin oluşturduğu bazı örnek değerler şunlardır:

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

Yukarıdaki örneklerden bazıları ücretsiz açık kaynak web sitesi <httpbin.org> kullanır. Bu, Microsoft'a bağlı olmayan bir üçüncü taraf web sitesidir. Bu örneklerde, istekte gönderilen üst bilgileri içeren bir yanıt gövdesi döndürür. Bu kaynağı API testi için kullanmanın diğer yolları hakkında bilgi için httpbin.org sitesinin home sayfasına bakın.

Desteklenmeyen söz dizimi

Visual Studio 2022 .http dosya düzenleyicisi, Visual Studio Code REST İstemci uzantısının sahip olduğu tüm özelliklere sahip değildir. Aşağıdaki liste, yalnızca Visual Studio Code uzantısında kullanılabilen daha önemli özelliklerden bazılarını içerir:

• Birden fazla satıra yayılan istek satırı
• Adlandırılmış istekler
• Dosya yolunu isteğin gövdesi olarak belirtin
• Çok parçalı/form-verileri kullanılırken gövde için karma biçim
• GraphQL istekleri
• cURL isteği
• cURL olarak kopyala/yapıştır
• İstek geçmişi
• Yanıt gövdesini dosyaya kaydetme
• Sertifika tabanlı kimlik doğrulaması
• İstem değişkenleri
• Yanıt önizlemesini özelleştirme
• İstek başına ayarlar

Dosya oluşturma .http

• Çözüm Gezgini bir ASP.NET Core projesine sağ tıklayın.

• Bağlam menüsünde Yeni Öğe Ekle'yi>seçin.

• Yeni Öğe Ekle iletişim kutusunda ASP.NET Çekirdek>Genel'i seçin.

• HTTP Dosyası'nın ardından Ekle'yi seçin.

  

HTTP isteği gönderme

• Dosyaya en az bir .http istek ekleyin ve dosyayı kaydedin.

• İstek URL'si localhost'a ve projenin bağlantı noktasına işaret ederse, istek göndermeye çalışmadan önce projeyi çalıştırın.

• Gönderilecek isteğin Send Request doğrudan üstündeki veya Debug bağlantısını seçin.

  İstek belirtilen URL'ye gönderilir ve yanıt düzenleyici penceresinin sağında ayrı bir bölmede görüntülenir.

  

.http dosya seçenekleri

Dosya davranışının .http bazı yönleri yapılandırılabilir. Nelerin kullanılabilir olduğunu görmek için Araçlar>Seçenekleri>Metin Düzenleyicisi'ne >Restgidin. Örneğin, zaman aşımı ayarı Gelişmiş sekmesinde yapılandırılabilir. Seçenekler iletişim kutusunun ekran görüntüsü aşağıdadır:

Uç Nokta Gezgini'ni kullanma

Uç Noktalar Gezgini , bir web API'sinin tanımladığı tüm uç noktaları gösteren bir araç penceresidir. Araç, bir .http dosya kullanarak uç noktalara istek göndermenizi sağlar.

Uç Nokta Gezgini'nin görüntülediği ilk uç nokta kümesi statik olarak bulunur. Statik olarak bulunamaz bazı uç noktalar vardır. Örneğin, bir sınıf kitaplığı projesinde tanımlanan uç noktalar çalışma zamanına kadar bulunamaz. Bir web API'sini çalıştırdığınızda veya hatalarını ayıkladığınızda, Visual Studio sürüm 17.11 Preview çalışma zamanında uç noktaları dinamik olarak bulur ve bunları Uç Nokta Gezgini'ne ekler.

Uç Nokta Gezgini'ne gidin

Diğer Windows>Uç Noktalarını Görüntüle>Gezgini'ne tıklayın.

Dosyaya .http istek ekleme

Uç Nokta Gezgini'nde bir isteğe sağ tıklayın ve İstek Oluştur'a tıklayın.

• Dosya adı olarak proje adına sahip bir .http dosya varsa, istek bu dosyaya eklenir.
• Aksi takdirde, dosya adı proje adıyla bir .http dosya oluşturulur ve istek bu dosyaya eklenir.

Yukarıdaki ekran görüntüsünde, minimum API proje şablonu tarafından tanımlanan uç noktalar gösterilmektedir. Aşağıdaki örnekte, seçili uç nokta için oluşturulan istek gösterilmektedir:

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

###

İsteği bu makalenin önceki bölümlerinde açıklandığı gibi gönderin.

Ayrıca bkz.

• Uç Nokta Gezgini penceresi yalnızca yollar için değişmez dizeleri tanır
• Visual Studio 2022'de Web API'sini geliştirme
• Visual Studio Code REST İstemci uzantısı