UriTemplate ve UriTemplateTable

  • Makale

Web geliştiricileri, hizmetlerinin yanıt verdiği URI'lerin şeklini ve düzenini açıklama olanağı gerektirir. Windows Communication Foundation (WCF), geliştiricilere URI'leri üzerinde denetim sağlamak için iki yeni sınıf ekledi. UriTemplate ve UriTemplateTable WCF'de URI tabanlı dağıtım altyapısının temelini oluşturur. Bu sınıflar kendi başlarına da kullanılabilir ve geliştiricilerin WCF hizmeti uygulamadan şablonlardan ve URI eşleme mekanizmasından yararlanmasına olanak sağlar.

Şablonlar

Şablon, göreli URI'ler kümesini açıklamanın bir yoludur. Aşağıdaki tabloda yer alan URI şablonları kümesi, çeşitli hava durumu bilgilerini alan bir sistemin nasıl tanımlandığını gösterir.

Veri Template
Ulusal Tahmin hava durumu/ulusal
Durum Tahmini hava durumu/{state}
Şehir Tahmini hava durumu/{state}/{city}
Etkinlik Tahmini hava durumu/{state}/{city}/{activity}

Bu tabloda yapısal olarak benzer URI'ler açıklanmaktadır. Her girdi bir URI şablonudur. Küme ayraçlarındaki segmentler değişkenleri açıklar. Küme ayraçlarında olmayan kesimler değişmez değer dizelerini açıklar. WCF şablon sınıfları, bir geliştiricinin "/weather/wa/seattle/cycling" gibi bir gelen URI almasına ve bunu "/weather/{state}/{city}/{activity}" tanımlayan bir şablonla eşleştirmesine olanak sağlar.

UriTemplate

UriTemplate bir URI şablonunu kapsülleyen bir sınıftır. Oluşturucu, şablonu tanımlayan bir dize parametresi alır. Bu dize, şablonu bir sonraki bölümde açıklanan biçimde içerir. UriTemplate sınıfı, gelen bir URI'yi şablonla eşleştirmenize, şablondan URI oluşturmanıza, şablonda kullanılan değişken adları koleksiyonunu almanıza, iki şablonun eşdeğer olup olmadığını belirlemenize ve şablonun dizesini döndürmenize olanak sağlayan yöntemler sağlar.

Match(Uri, Uri) bir temel adres ve aday URI alır ve URI'yi şablonla eşleştirmeye çalışır. Eşleşme başarılı olursa bir UriTemplateMatch örnek döndürülür. UriTemplateMatch nesnesi bir temel URI, aday URI, sorgu parametrelerinin ad/değer koleksiyonu, göreli yol kesimlerinin dizisi, eşleşen değişkenlerin ad/değer koleksiyonu, UriTemplate eşleşmeyi gerçekleştirmek için kullanılan örnek, aday URI'sinin eşleşmeyen bir bölümünü içeren bir dize (şablonun joker karakteri olduğunda kullanılır), ve şablonla ilişkilendirilmiş bir nesne.

Not

sınıf, UriTemplate bir aday URI'sini şablonla eşleştirirken şemayı ve bağlantı noktası numarasını yoksayar.

Bir şablondan BindByName(Uri, NameValueCollection) URI oluşturmanıza olanak sağlayan iki yöntem vardır ve BindByPosition(Uri, String[]). BindByName(Uri, NameValueCollection) bir temel adres ve parametrelerden oluşan bir ad/değer koleksiyonu alır. Bu parametreler, şablon bağlı olduğunda değişkenlerle değiştirilir. BindByPosition(Uri, String[]) ad/değer çiftlerini alır ve bunları soldan sağa bırakır.

ToString() şablon dizesini döndürür.

özelliği, PathSegmentVariableNames şablon dizesindeki yol kesimleri içinde kullanılan değişkenlerin adlarının bir koleksiyonunu içerir.

IsEquivalentTo(UriTemplate) parametre olarak bir UriTemplate alır ve iki şablonun eşdeğer olup olmadığını belirten bir Boole değeri döndürür. Daha fazla bilgi için bu konunun devamında yer alan Şablon Eşdeğerliği bölümüne bakın.

UriTemplate , HTTP URI dil bilgisi ile uyumlu herhangi bir URI düzeniyle çalışacak şekilde tasarlanmıştır. Aşağıda desteklenen URI düzenlerine örnekler verilmiştir.

  • http://

  • https://

  • net.tcp://

  • net.pipe://

  • sb://

file:// ve urn:// gibi düzenler HTTP URI dil bilgisi ile uyumlu değildir ve URI şablonlarıyla kullanıldığında öngörülemeyen sonuçlara neden olur.

Şablon Dizesi Söz Dizimi

Şablonun üç bölümü vardır: yol, isteğe bağlı sorgu ve isteğe bağlı bir parça. Bir örnek için aşağıdaki şablona bakın:

"/weather/{state}/{city}?forecast={length)#frag1

Yol "/weather/{state}/{city}", sorgu "?forecast={length}" ve parça da "#frag1" öğesinden oluşur.

Yol ifadesinde baştaki ve sondaki eğik çizgiler isteğe bağlıdır. Hem sorgu hem de parça ifadeleri tamamen atlanabilir. Bir yol, '/' ile sınırlandırılmış bir dizi kesimden oluşur; her kesimin değişmez değeri, değişken adı ({küme ayracı} ile yazılır) veya joker karakteri ('*' olarak yazılır) olabilir. Önceki şablonda "\weather\ segmenti değişmez değerken "{state}" ve "{city}" değişkenlerdir. Değişkenler, adlarını küme ayraçlarının içeriğinden alır ve daha sonra kapalı bir URI oluşturmak için somut bir değerle değiştirilebilir. Joker karakter isteğe bağlıdır, ancak yalnızca URI'nin sonunda görünebilir ve burada mantıksal olarak "yolun geri kalanı" ile eşleşir.

Sorgu ifadesi varsa, '&' ile sınırlandırılmış bir dizi sıralanmamış ad/değer çifti belirtir. Sorgu ifadesinin öğeleri değişmez değer çiftleri (x=2) veya değişken çifti (x={var}) olabilir. Sorgunun yalnızca sağ tarafında değişken ifadesi olabilir. ({someName} = {someValue} öğesine izin verilmiyor. Eşleşmeyen değerlere (?x) izin verilmez. Boş bir sorgu ifadesi ile yalnızca tek bir '?' içeren sorgu ifadesi arasında bir fark yoktur (her ikisi de "herhangi bir sorgu" anlamına gelir).

Parça ifadesi değişmez değerden oluşabilir, hiçbir değişkene izin verilmez.

Şablon dizesi içindeki tüm şablon değişkeni adları benzersiz olmalıdır. Şablon değişkeni adları büyük/küçük harfe duyarlı değildir.

Geçerli şablon dizeleri örnekleri:

  • ""

  • "/shoe"

  • "/shoe/*"

  • "{shoe}/boat"

  • "{shoe}/{boat}/bed/{quilt}"

  • "shoe/{boat}"

  • "shoe/{boat}/*"

  • "ayakkabı/tekne?x=2"

  • "shoe/{boat}?x={bed}"

  • "shoe/{boat}?x={bed}&y=band"

  • "?x={shoe}"

  • "shoe?x=3&y={var}

Geçersiz şablon dizeleri örnekleri:

  • "{shoe}/{SHOE}/x=2" – Yinelenen değişken adları.

  • "{shoe}/boat/?bed={shoe}" – Yinelenen değişken adları.

  • "?x=2&x=3" – Bir sorgu dizesi içindeki ad/değer çiftleri, değişmez değerler olsa bile benzersiz olmalıdır.

  • "?x=2&" – Sorgu dizesi yanlış biçimlendirilmiş.

  • "?2&x={shoe}" – Sorgu dizesi ad/değer çiftleri olmalıdır.

  • "?y=2&&X=3" – Sorgu dizesi ad değer çiftleri olmalıdır, adlar '&' ile başlayamaz.

Bileşik Yol Kesimleri

Bileşik yol kesimleri, tek bir URI yol kesiminin birden çok değişkeni ve değişmez değerlerle birleştirilmiş değişkenleri içermesini sağlar. Aşağıda geçerli bileşik yol kesimlerine örnekler verilmiştir.

  • /Dosyaadı. {ext}/

  • /{filename}.jpg/

  • /{filename}. {ext}/

  • /{a}. {b}someLiteral{c}({d})/

Aşağıda geçersiz yol kesimlerine örnekler verilmiştir.

  • /{} - Değişkenler adlandırılmalıdır.

  • /{shoe}{boat} - Değişkenler değişmez değerle ayrılmalıdır.

Eşleşen ve Bileşik Yol Kesimleri

Bileşik yol kesimleri, tek bir yol kesiminde birden çok değişkeni olan bir UriTemplate tanımlamanızı sağlar. Örneğin, şu şablon dizesinde: "Addresses/{state}. {city}" iki değişken (eyalet ve şehir) aynı segment içinde tanımlanır. Bu şablon gibi http://example.com/Washington.Redmond bir URL ile eşleşse de gibi http://example.com/Washington.Redmond.Microsoftbir URL ile eşleşecektir. İkinci durumda, state değişkeni "Washington" ve şehir değişkeni "Redmond.Microsoft" içerecektir. Bu durumda tüm metinler ('/' hariç) {city} değişkeniyle eşleşecektir. "Ek" metinle eşleşmeyecek bir şablon istiyorsanız, değişkeni ayrı bir şablon kesimine yerleştirin, örneğin: "Addresses/{state}/{city}.

Adlandırılmış Joker Karakter Kesimleri

Adlandırılmış joker segment, değişken adı '*' joker karakteriyle başlayan herhangi bir yol değişkeni segmentidir. Aşağıdaki şablon dizesi "shoe" adlı adlandırılmış bir joker karakter kesimi içerir.

"literal/{*shoe}"

Joker segmentlerin aşağıdaki kurallara uyması gerekir:

  • Her şablon dizesi için en fazla bir joker karakter segmenti olabilir.

  • Adlandırılmış joker karakter kesimi, yolun en sağdaki kesiminde görünmelidir.

  • Adlandırılmış joker karakter kesimi, aynı şablon dizesi içinde anonim bir joker segmentle birlikte bulunamaz.

  • Adlandırılmış joker karakter kesiminin adı benzersiz olmalıdır.

  • Adlandırılmış joker segmentlerin varsayılan değerleri olamaz.

  • Adlandırılmış joker karakter kesimleri "/" ile bitemez.

Varsayılan Değişken Değerleri

Varsayılan değişken değerleri, şablon içindeki değişkenler için varsayılan değerleri belirtmenize olanak sağlar. Varsayılan değişkenler, değişkeni bildiren küme ayraçlarıyla veya UriTemplate oluşturucusna geçirilen bir koleksiyon olarak belirtilebilir. Aşağıdaki şablonda, varsayılan değerlere sahip değişkenler içeren bir UriTemplate öğesini belirtmenin iki yolu gösterilmektedir.

UriTemplate t = new UriTemplate("/test/{a=1}/{b=5}");

Bu şablon, varsayılan değeri ile adlı a bir değişken ve varsayılan değeri 15ile adlı b bir değişken bildirir.

Not

Yalnızca yol segmenti değişkenlerinin varsayılan değerlere sahip olması sağlanır. Sorgu dizesi değişkenlerinin, bileşik segment değişkenlerinin ve adlandırılmış joker değişkenlerin varsayılan değerlere sahip olması yasaktır.

Aşağıdaki kod, aday URI'sini eşleştirirken varsayılan değişken değerlerinin nasıl işleneceğini gösterir.

Uri baseAddress = new Uri("http://localhost:8000/");

UriTemplate t = new UriTemplate("/{state=WA}/{city=Redmond}/", true);
Uri candidate = new Uri("http://localhost:8000/OR");

UriTemplateMatch m1 = t.Match(baseAddress, candidate);

Console.WriteLine($"Template: {t}");
Console.WriteLine($"Candidate URI: {candidate}");

// Display contents of BoundVariables
Console.WriteLine("BoundVariables:");
foreach (string key in m1.BoundVariables.AllKeys)
{
    Console.WriteLine($"\t{key}={m1.BoundVariables[key]}");
}
// The output of the above code is  
// Template: /{state=WA}/{city=Redmond}/
// Candidate URI: http://localhost:8000/OR
// BoundVariables:
//         STATE=OR
//         CITY=Redmond

Not

gibi http://localhost:8000/// bir URI, önceki kodda listelenen şablonla eşleşmiyor, ancak URI gibi http://localhost:8000/ bir URI ile eşleşmiyor.

Aşağıdaki kod, şablonla URI oluşturulurken varsayılan değişken değerlerinin nasıl işleneceğini gösterir.

Uri baseAddress = new Uri("http://localhost:8000/");  
Dictionary<string,string> defVals = new Dictionary<string,string> {{"a","1"}, {"b", "5"}};  
UriTemplate t = new UriTemplate("/test/{a}/{b}", defVals);  
NameValueCollection vals = new NameValueCollection();  
vals.Add("a", "10");  
  
Uri boundUri = t.BindByName(baseAddress, vals);  
Console.WriteLine("BaseAddress: {0}", baseAddress);  
Console.WriteLine("Template: {0}", t.ToString());  
  
Console.WriteLine("Values: ");  
foreach (string key in vals.AllKeys)  
{  
    Console.WriteLine("\tKey = {0}, Value = {1}", key, vals[key]);  
}  
Console.WriteLine("Bound URI: {0}", boundUri);  
  
// The output of the preceding code is  
// BaseAddress: http://localhost:8000/  
// Template: /test/{a}/{b}  
// Values:  
//     Key = a, Value = 10  
// Bound URI: http://localhost:8000/test/10/5

Bir değişkene varsayılan değeri null verildiğinde bazı ek kısıtlamalar vardır. Değişken, şablon dizesinin null en doğru segmentinde yer alırsa veya segmentin sağındaki tüm kesimler varsayılan değerlerine sahipse değişkenin varsayılan değeri nullolabilir. Varsayılan değerleri olan geçerli şablon dizeleri şunlardır null:

  • UriTemplate t = new UriTemplate("shoe/{boat=null}");

  • UriTemplate t = new UriTemplate("{shoe=null}/{boat=null}");

  • UriTemplate t = new UriTemplate("{shoe=1}/{boat=null}");

Aşağıdakiler, varsayılan değerleri olan geçersiz şablon dizeleridir null:

  • UriTemplate t = new UriTemplate("{shoe=null}/boat"); // null default must be in the right most path segment

  • UriTemplate t = new UriTemplate("{shoe=null}/{boat=x}/{bed=null}"); // shoe cannot have a null default because boat does not have a default null value

Varsayılan Değerler ve Eşleştirme

Aday URI'sini varsayılan değerleri olan bir şablonla eşleştirirken, aday URI'sinde BoundVariables değerler belirtilmezse varsayılan değerler koleksiyona yerleştirilir.

Şablon Eşdeğerliği

Tüm şablonların değişmez değerleri eşleştiğinde ve aynı segmentlerde değişkenlere sahip olduğunda iki şablonun yapısal olarak eşdeğer olduğu söylenir. Örneğin, aşağıdaki şablonlar yapısal olarak eşdeğerdir:

  • /a/{var1}/b b/{var2}?x=1&y=2

  • a/{x}/b%20b/{var1}?y=2&x=1

  • a/{y}/B%20B/{z}/?y=2&x=1

Dikkate bilmeniz gereken birkaç şey:

  • Şablonda baştaki eğik çizgiler varsa, yalnızca ilki yoksayılır.

  • Yapısal denklik için şablon dizeleri karşılaştırılırken değişken adları ve yol kesimleri için büyük/küçük harf yoksayılır, sorgu dizeleri büyük/küçük harfe duyarlıdır.

  • Sorgu dizeleri sıralanmamış.

Uritemplatetable

sınıfı, UriTemplateTable geliştiricinin UriTemplate seçtiği bir nesneye bağlı nesnelerden oluşan ilişkilendirici bir tabloyu temsil eder. çağrısından UriTemplateTableMakeReadOnly(Boolean)önce en az bir tane UriTemplate içermelidir. öğesinin içeriği çağrılana UriTemplateTable kadar MakeReadOnly(Boolean) değiştirilebilir. Doğrulama çağrıldığında MakeReadOnly(Boolean) gerçekleştirilir. Gerçekleştirilen doğrulama türü parametresinin allowMultipleMakeReadOnly(Boolean)değerine bağlıdır.

geçirilen falseolarak çağrıldığındaMakeReadOnly(Boolean), UriTemplateTable tabloda şablon olmadığından emin olmak için denetimler yapılır. Yapısal olarak eşdeğer şablonlar bulursa bir özel durum oluşturur. Bu, gelen bir URI ile yalnızca bir şablonun eşleştiğinden emin olmak istediğinizde birlikte MatchSingle(Uri) kullanılır.

geçişi trueUriTemplateTable olarak çağrıldığındaMakeReadOnly(Boolean), birden çok yapısal olarak eşdeğer şablonun içinde UriTemplateTablebulunmasına izin verir.

Bir nesne kümesine UriTemplate eklenen nesneler UriTemplateTable sorgu dizeleri içeriyorsa, belirsiz olmamalıdır. Aynı sorgu dizelerine izin verilir.

Not

UriTemplateTable HTTP dışındaki düzenleri kullanan temel adreslere izin verirken, aday URI'leri şablonlarla eşleştirirken düzen ve bağlantı noktası numarası yoksayılır.

Sorgu Dizesi Belirsizliği

Eşdeğer bir yolu paylaşan şablonlar, birden fazla şablonla eşleşen bir URI varsa belirsiz sorgu dizeleri içerir.

Aşağıdaki sorgu dizeleri kümeleri kendi içinde belirsizdir:

  • ?x=1

  • ?x=2

  • ?x=3

  • ?x=1&y={var}

  • ?x=2&z={var}

  • ?x=3

  • ?x=1

  • ?

  • ? x={var}

  • ?

  • ?m=get&c=rss

  • ?m=put&c=rss

  • ?m=get&c=atom

  • ?m=put&c=atom

Aşağıdaki sorgu dizesi şablonları kümeleri kendi içinde belirsizdir:

  • ?x=1

  • ?x={var}

"x=1" - Her iki şablonla da eşleşir.

  • ?x=1

  • ?y=2

"x=1&y=2" her iki şablonla da eşleşir. Bunun nedeni, bir sorgu dizesinin daha fazla sorgu dizesi değişkeni içermesi ve sonra da eşleştirdiği şablonu içermesidir.

  • ?x=1

  • ?x=1&y={var}

"x=1&y=3" her iki şablonla da eşleşir.

  • ?x=3&y=4

  • ?x=3&z=5

Not

Á ve Á karakterleri, URI yolunun veya UriTemplate yol kesimi değişmez değerinin parçası olarak göründüklerinde farklı karakterler olarak kabul edilir (ancak a ve A karakterleri aynı olarak kabul edilir). á ve Á karakterleri bir {variableName} veya sorgu dizesinin UriTemplate parçası olarak göründüğünde aynı karakterler olarak kabul edilir (ve a ve A da aynı karakterler olarak kabul edilir).

Ayrıca bkz.