Экспорт (0) Печать
Развернуть все
Эта статья переведена вручную. Наведите указатель мыши на предложения статьи, чтобы просмотреть исходный текст. Дополнительные сведения.
Перевод
Текст оригинала

UriTemplate и UriTemplateTable

Интернет-разработчикам требуется возможность описывать форму и структуру универсальных кодов ресурса (URI), на которые отвечают их службы. В Windows Communication Foundation (WCF) добавлены два новых класса, позволяющие разработчикам контролировать свои универсальные коды ресурса (URI). Классы UriTemplate и UriTemplateTable формируют основу модуля отправки данных на основе URI, который используется в WCF. Эти классы могут также использоваться сами по себе, позволяя разработчиками воспользоваться преимуществами шаблонов и механизма сопоставления универсального кода ресурса (URI) без реализации службы WCF.

Шаблон — это способ описания набора относительных универсальных кодов ресурса (URI). Набор шаблонов универсальных кодов ресурсов (URI), приведенный в следующей таблице, показывает, как может быть определена система, извлекающая различные виды информации о погоде.

Data

Шаблон

Прогноз для страны

weather/national

Прогноз для штата

weather/{state}

Прогноз для города

weather/{state}/{city}

Прогноз для рода занятий

weather/{state}/{city}/{activity}

В этой таблице описывает набор, структурно аналогичный универсальным кодам ресурсов (URI). Каждая запись является шаблоном универсального кода ресурса (URI). Сегменты в фигурных скобках описывают переменные. Сегменты без фигурных скобок описывают строки литералов. Классы-шаблоны WCF позволяют разработчику сопоставить входящий универсальный код ресурса (URI) (например, «/weather/wa/seattle/cycling») с описывающим его шаблоном («/weather/{state}/{city}/{activity}»).

Класс UriTemplate является классом, инкапсулирующим шаблон универсального кода ресурса (URI). Конструктор принимает строковый параметр, задающий шаблон. Эта строка содержит шаблон в формате, приведенном в следующем разделе. Класс UriTemplate предоставляет методы, позволяющие сопоставлять входящий URI с шаблоном, создавать URI из шаблона, получать коллекцию имен переменных в шаблоне, определять, эквивалентны ли два шаблона, и возвращать строку шаблона.

Метод Match(Uri, Uri) принимает базовый адрес и потенциальный универсальный код ресурса (URI), после чего пытается сопоставить универсальный код ресурса (URI) с шаблоном. Если сопоставление завершается успешно, возвращается экземпляр UriTemplateMatch. Объект UriTemplateMatch содержит базовый универсальный код ресурса (URI), потенциальный URI, коллекцию имя/значение параметров запроса, массив сегментов относительного пути, коллекцию имя/значение сопоставленных переменных, экземпляр UriTemplate, использованный для сопоставления, строку, содержащую несопоставленную часть потенциального URI (используется, если шаблон содержит подстановочный знак) и объект, связанный с этим шаблоном.

Примечание Примечание

При сопоставлении потенциального универсального кода ресурса (URI) класс UriTemplate не учитывает схему и номер порта.

Есть два метода, позволяющие создавать универсальный код ресурса (URI) из шаблона — BindByName(Uri, NameValueCollection) и BindByPosition(Uri, String[]). Метод BindByName(Uri, NameValueCollection) принимает базовый адрес и коллекцию параметров вида имя/значение. Эти параметры подставляются вместо переменных при использовании шаблона. Метод BindByPosition(Uri, String[]) принимает пары имя/значение и подставляет их в порядке слева направо.

Метод ToString() возвращает строку шаблона.

Свойство PathSegmentVariableNames содержит коллекцию имен переменных, используемых в сегментах пути в строке шаблона.

Метод IsEquivalentTo(UriTemplate) принимает UriTemplate в качестве параметра и возвращает логическое значение, указывающее, являются ли два шаблона эквивалентными. Дополнительные сведения см. в подраздел «Эквивалентность шаблонов» далее в этом разделе.

Класс UriTemplate предназначен для работы с любой схемой URI, соблюдающей грамматику URI HTTP. Ниже приведены примеры поддерживаемых схем URI.

  • http://

  • https://

  • net.tcp://

  • net.pipe://

  • sb://

Схемы, подобные file:// и urn://, не соответствуют грамматике URI HTTP и при использовании с шаблонами URI приведут к непредсказуемым результатам.

Bb675245.collapse_all(ru-ru,VS.110).gifСинтаксис строки шаблона

Шаблон содержит три части: путь, необязательный запрос и необязательный фрагмент. Например, рассмотрим следующий шаблон:

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

Путь состоит из «/weather/{state}/{city}», запрос состоит из «?forecast={length}», и фрагмент состоит из «#frag1».

Начальные и конечные знаки косой черты в выражении пути необязательны.Как запрос, так и фрагмент могут быть полностью опущены.Путь состоит из последовательных сегментов, разделенных знаком "/", каждый сегмент имеет литеральное значение, имя переменной (указанное в {фигурных скобках}) или подстановочный знак (указанный как "*").В предыдущем шаблоне сегмент "\weather\" является литеральным значением, а "{state}" и "{city}" — это переменные.Переменным присваивается имя, содержащееся в их фигурных скобках; впоследствии переменные могут заменяться конкретными значениями для создания закрытого URI.Подстановочный знак является необязательным, но может использоваться только в конце универсального кода ресурса (URI), где он логически означает «остальная часть пути».

Выражение запроса (если оно указано) задает неупорядоченную последовательность пар «имя-значение», разделяемых знаком «&».Элементами выражения запроса могут быть либо литеральные пары (x=2) или переменная пара (x={var}).Переменное выражение может содержаться только в правой части запроса.Конструкции ({someName} = {someValue}) не допускаются.Непарные значения (?x) не допускаются.Пустое выражение запроса и выражение запроса, содержащее только знак вопроса "?", равнозначны (оба означают «любой запрос»).

Выражение фрагмента может содержать любое литеральное значение, переменные не допускаются.

Все имена переменных шаблона в строке шаблона должны быть уникальными.В именах переменных шаблона регистр не учитывается.

Ниже приведены допустимые строки шаблона:

  • ""

  • "/shoe"

  • "/shoe/*"

  • "{shoe}/boat"

  • “{shoe}/{boat}/bed/{quilt}”

  • “shoe/{boat}”

  • “shoe/{boat}/*”

  • “shoe/boat?x=2”

  • “shoe/{boat}?x={bed}”

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

  • “?x={shoe}”

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

Ниже приведены недопустимые строки шаблона:

  • “{shoe}/{SHOE}/x=2” — повторяющиеся имена переменных.

  • “{shoe}/boat/?bed={shoe}” — повторяющиеся имена переменных.

  • "?x=2&x=3" — пары «имя-значение» в строке запроса должны быть уникальными, даже если они являются литералами.

  • "?x=2&" — строка запроса неправильного формата.

  • "?2&x={shoe}" — строка запроса должна состоять из пар «имя-значение».

  • "?y=2&&&X=3" — строка запроса должна состоять из пар «имя-значение», а имена не могут начинаться с символа «».

Bb675245.collapse_all(ru-ru,VS.110).gifСоставные сегменты пути

Составные сегменты пути позволяют включать в один сегмент пути универсального кода ресурса (URI) несколько переменных, а также несколько переменных совместно с литералами. Ниже приведены примеры допустимых составных сегментов пути:

  • /имя_файла.{ext}/

  • /{filename}.jpg/

  • /{filename}.{ext}/

  • /{a}.{b}некоторый_литерал{c}({d})/

Ниже приведены примеры недопустимых составных сегментов пути.

  • /{} — переменная должна иметь имя.

  • /{shoe}{boat} — переменные должны разделяться литералом.

Bb675245.collapse_all(ru-ru,VS.110).gifСовпадающие и составные сегменты пути

Составные сегменты пути позволяют определять UriTemplate, который имеет несколько переменных в одном сегменте пути. Возьмем в качестве примера следующую строку шаблона: «Адреса/{штат}.{город}». Две переменные («штат» и «город») определены в одном сегменте. Этот шаблон будет соответствовать такому URL-адресу, как «http://example.com/Washington.Redmond», но он также будет соответствовать такому URL-адресу, как «http://example.com/Washington.Redmond.Microsoft». В последнем случае переменная «штат» будет содержать название штата «Вашингтон», а переменная «город» будет содержать «Redmond.Microsoft». В данном случае любой текст (за исключением символа «/») будет соответствовать переменной {город}. Если требуется шаблон, который не будет соответствовать «дополнительному» тексту, поместите переменную в отдельный сегмент шаблона, например: «Адреса/{штат}/{город}.

Bb675245.collapse_all(ru-ru,VS.110).gifИменованные сегменты с подстановочным знаком

Именованный сегмент с подстановочным знаком — это любой переменный сегмент, имя переменной которого начинается с символа-шаблона "*". Следующая строка шаблона содержит именованный сегмент с подстановочным знаком, имеющий имя «shoe».

"literal/{*shoe}"

Сегменты с подстановочными знаками должны удовлетворять следующим правилам.

  • В каждой строке шаблона должно быть не более одного именованного сегмента с подстановочным знаком.

  • Именованный сегмент с подстановочным знаком должен быть самым правым сегментом пути.

  • Именованный сегмент с подстановочным знаком и анонимный сегмент с подстановочным знаком не могут одновременно использоваться в одной строке шаблона.

  • Имя именованного сегмента с подстановочным знаком должно быть уникальным.

  • Именованные сегменты с подстановочным знаком не могут иметь значений по умолчанию.

  • Именованные сегменты с подстановочным знаком не могут заканчиваться знаком "/".

Bb675245.collapse_all(ru-ru,VS.110).gifЗначения переменных по умолчанию

Значения переменных по умолчанию позволяют задавать значения по умолчанию для переменных шаблона. Значения переменных по умолчанию могут быть заданы в фигурных скобках, объявляющих переменную, или в виде коллекции, передаваемой конструктору UriTemplate. В следующем шаблоне показаны два способа задания UriTemplate с переменными, имеющими значения по умолчанию.

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

В этом шаблоне объявляются переменная с именем a и значением по умолчанию 1 и переменная с именем b со значением по умолчанию 5.

ПримечаниеПримечание

Значения по умолчанию могут иметь только переменные сегмента пути.Переменные строки запроса, переменные составного сегмента и именованные переменные с подстановочным знаком не могут иметь значений по умолчанию.

В следующем коде показано, как обрабатываются значения переменных по умолчанию при сопоставлении потенциального универсального кода ресурса (URI).

Uri baseAddress = new Uri("http://localhost:800 
Dictionary<string,string> defVals = new Dictionary<string,string> {{"a","1"}, {"b", "5"}};
UriTemplate t = new UriTemplate("/test/{a}/{b}", defVals);0");
UriTemplate t = new UriTemplate("/{state=WA}/{city=Redmond}/", true);
Uri candidate = new Uri("http://localhost:8000/OR");

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

// Display contents of BoundVariables
foreach (string key in m1.BoundVariables.AllKeys)
{
    Console.WriteLine("\t\t{0}={1}", 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

ПримечаниеПримечание

URI вида http://localhost:8000/// не соответствует шаблону, указанному в приведенном выше коде, в отличие от URI вида http://localhost:8000/.

В следующем коде показано, как обрабатываются значения переменных по умолчанию при создании универсального кода ресурса (URI) с помощью шаблона.

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

Если переменной присвоено значение по умолчанию null, существуют дополнительные ограничения.Переменная может иметь значение по умолчанию null, если эта переменная содержится в самом правом сегменте строки шаблона или если все сегменты справа от этого сегмента имеют значения по умолчанию null.Ниже приводятся допустимые строки шаблона со значениями по умолчанию null:

Ниже приводятся недопустимые строки шаблона со значениями по умолчанию 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
    

Bb675245.collapse_all(ru-ru,VS.110).gifЗначения по умолчанию и сопоставление

При сопоставлении URI-кандидата с шаблоном, имеющим значения по умолчанию, в коллекцию BoundVariables помещаются значения по умолчанию, если в URI-кандидате не указаны значения.

Bb675245.collapse_all(ru-ru,VS.110).gifЭквивалентность шаблонов

Два шаблона называются структурно эквивалентными, если все литералы в шаблоне совпадают, а переменные находятся в одинаковых сегментах. Например, указанные ниже шаблоны структурно эквивалентны.

  • /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

Некоторые замечания.

  • Если шаблон содержит начальные символы косой черты, не учитывается только первый из них.

  • При сравнении строк шаблона для определения их структурной эквивалентности регистр пропускается для имен переменных и сегментов пути, в строках запроса регистр учитывается.

  • Строки запроса неупорядочены.

Класс UriTemplateTable представляет ассоциативную таблицу объектов UriTemplate, привязанных к объекту, выбранному разработчиком. Класс UriTemplateTable должен содержать по крайней мере один объект UriTemplate, чтобы можно было вызвать метод MakeReadOnly(Boolean). Содержимое таблицы UriTemplateTable можно изменять до тех пор, пока не будет вызван метод MakeReadOnly(Boolean). Проверка выполняется при вызове метода MakeReadOnly(Boolean). Тип выполняемой проверки зависит от значения параметра allowMultiple метода MakeReadOnly(Boolean).

Если при вызове метода MakeReadOnly(Boolean) ему передается значение false, таблица UriTemplateTable проверяется, чтобы убедиться, что в ней отсутствуют шаблоны. Если будут найдены какие-либо структурно эквивалентные шаблоны, возникает исключение. Это используется совместно с методом MatchSingle(Uri), если требуется обеспечить, чтобы только один шаблон соответствовал входящему универсальному коду ресурса (URI).

Если при выборе метода MakeReadOnly(Boolean) ему передается значение true, UriTemplateTable допускает наличии нескольких структурно эквивалентных шаблонов в UriTemplateTable.

Если набор объектов UriTemplate, добавленных в таблицу UriTemplateTable, содержит строки запроса, они не должны быть неоднозначными. Допускаются идентичные строки запросов.

Примечание Примечание

Хотя UriTemplateTable допускает базовые адреса, использующие схемы, отличные от HTTP, при сопоставлении потенциальных универсальных кодов ресурсов (URI) с шаблонами схема и номер порта пропускаются.

Bb675245.collapse_all(ru-ru,VS.110).gifНеоднозначность строки запроса

Шаблоны, содержащие эквивалентные пути, содержат неоднозначные строки запроса, если существует универсальный код ресурса (URI), соответствующий нескольким шаблонам.

Приведенные ниже наборы строк запроса однозначны внутри себя.

  • ?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

Приведенные ниже шаблоны строк запроса неоднозначны внутри себя.

  • ?x=1

  • ?x={var}

"x=1" — соответствует обеим шаблонам.

  • ?x=1

  • ?y=2

Строка "x=1&y=2" соответствует обоим шаблонам. Это связано с тем, что строка запроса может содержать больше переменных стоки запроса, чем соответствующий ей шаблон.

  • ?x=1

  • ?x=1&y={var}

Строка "x=1&y=3" соответствует обоим шаблонам.

  • ?x=3&y=4

  • ?x=3&z=5

Примечание Примечание

Буквы "á" и "Á" считаются разными символами, если они используются в пути универсального кода ресурса (URI) или в литерале сегмента пути UriTemplate (но буквы "a" и "A" считаются одинаковыми). Буквы "á" и "Á" считаются одинаковыми символами, если они используются в UriTemplate {имя_переменной} или строке запроса (а буквы "a" и "A" также считаются одинаковыми).

Добавления сообщества

ДОБАВИТЬ
Показ:
© 2015 Microsoft