Este artigo foi traduzido por máquina. Para visualizar o arquivo em inglês, marque a caixa de seleção Inglês. Você também pode exibir o texto Em inglês em uma janela pop-up, movendo o ponteiro do mouse sobre o texto.
Tradução
Inglês

UriTemplate and UriTemplateTable

.NET Framework (current version)
 

Os desenvolvedores da Web exigem a capacidade para descrever a forma e o layout dos URIs que seus serviços de respondem.Windows Communication Foundation (WCF) adicionadas duas novas classes para dar aos desenvolvedores controle sobre seus URIs. UriTemplate e UriTemplateTable formam a base do mecanismo de expedição baseada em URI em WCF. Essas classes também podem ser usadas em seus próprios, permitindo que os desenvolvedores tirar proveito de modelos e o mecanismo de mapeamento de URI sem implementar um WCF service.

Um modelo é uma maneira de descrever um conjunto de URIs relativos. O conjunto de modelos URI na tabela a seguir mostra como um sistema que recupera vários tipos de informações sobre o clima pode ser definido.

Dados

Modelo

Previsão nacional

clima/nacionais

Previsão de estado

clima / {estado}

Previsão de cidade

clima / {estado} / {cidade}

Previsão de atividade

clima / {estado} / {cidade} / {atividade}

Esta tabela descreve um conjunto de URIs estruturalmente semelhantes. Cada entrada é um modelo URI. Os segmentos entre chaves descrevem variáveis. Os segmentos não entre chaves descrevem cadeias de caracteres literais. O WCF classes de modelo permitem que um desenvolvedor pegar um URI de entrada, por exemplo, "/ clima/wa/seattle/ciclo", e correspondem a um modelo que descreve, "/weather/ {estado} / {cidade} / {atividade}".

UriTemplate é uma classe que encapsula o modelo URI. O construtor aceita um parâmetro de cadeia de caracteres que define o modelo. Essa cadeia de caracteres contém o modelo no formato descrito na próxima seção. O UriTemplate classe fornece métodos que permitem correspondem um URI de entrada para um modelo, gere um URI de um modelo, recuperar uma coleção de nomes de variáveis usados no modelo, determinar se dois modelos são equivalentes e retornam a cadeia de caracteres do modelo.

Match(Uri, Uri) usa um endereço base e um candidato URI e tenta corresponder o URI para o modelo. Se a correspondência for bem-sucedida, um UriTemplateMatch instância será retornada. O UriTemplateMatch objeto contém um URI de base, o candidato URI, uma coleção de nome/valor de parâmetros de consulta, uma matriz dos segmentos de caminho relativo, uma coleção de nome/valor de variáveis que foram comparados, o UriTemplate usada para fazer a correspondência, uma cadeia de caracteres que contém qualquer parte incomparável o candidato URI (usado quando o modelo tem um caractere curinga) e um objeto que está associado com o modelo de instância.

System_CAPS_noteObservação

O UriTemplate classe ignora o número da porta e o esquema durante a correspondência de um URI de candidato para um modelo.

Há dois métodos que permitem que você gere um URI de um modelo, BindByName(Uri, NameValueCollection) e BindByPosition(Uri, String[]). BindByName(Uri, NameValueCollection) usa um endereço base e uma coleção de nome/valor de parâmetros. Esses parâmetros são substituídos por variáveis quando o modelo está associado. BindByPosition(Uri, String[]) usa os pares nome/valor e substitui-los à esquerda para a direita.

ToString() Retorna a cadeia de caracteres do modelo.

O PathSegmentVariableNames propriedade contém uma coleção de nomes das variáveis usadas em segmentos de caminho na cadeia de caracteres de modelo.

IsEquivalentTo(UriTemplate) leva um UriTemplate como um parâmetro e retorna um valor booleano que especifica se os dois modelos são equivalentes.Para saber mais, veja Equivalência de modelo seção mais adiante neste tópico.

UriTemplate foi projetado para trabalhar com qualquer esquema URI que esteja de acordo com a gramática do URI de HTTP. A seguir estão exemplos de esquemas URI com suporte.

  • http://

  • https://

  • NET.TCP://

  • NET.pipe://

  • SB: / /

Esquemas como file:// e urn: / / não está de acordo com a gramática do URI de HTTP e causar resultados imprevisíveis quando usada com modelos de URI.

Um modelo tem três partes: um caminho, uma consulta opcional e um fragmento opcional. Para obter um exemplo, consulte o seguinte modelo:

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

O caminho consiste em "/weather/ {estado} / {cidade}", a consulta consiste em"? previsão = comprimento {}, e o fragmento consiste em"#frag1".

À esquerda e à direita barras são opcionais na expressão de caminho. Expressões de consulta e o fragmento podem ser totalmente omitidas. Um caminho consiste em uma série de segmentos delimitados por '/', cada segmento pode ter um valor literal, um nome de variável (escrito em {chaves}) ou um caractere curinga (escrito como ' *'). No modelo anterior a "\weather\ segmento é um literal de valor de"{state}"e"{city}"são variáveis. Variáveis têm o nome do conteúdo de suas chaves e posteriormente pode ser substituídos com um valor concreto para criar um fechado URI. O caractere curinga é opcional, mas só pode aparecer no final do URI, onde ele corresponde logicamente "o resto do caminho".

A expressão de consulta, se presente, especifica uma série de pares de nome/valor desordenada delimitada por '&'. Elementos da expressão de consulta podem ser literal pares (x = 2) ou um par de variáveis (x = {var}). Apenas o lado direito da consulta pode ter uma expressão de variável. ({someName} = {someValue} não é permitido. Sem paridade valores (? x) não são permitidos. Não há nenhuma diferença entre uma expressão de consulta vazia e uma expressão de consulta consiste em apenas um único '?' (ambos dizer "qualquer consulta").

A expressão de fragmento pode consistir de um valor literal, sem variáveis são permitidos.

Todos os nomes de variável de modelo dentro de uma cadeia de caracteres de modelo devem ser exclusivos. Nomes de variáveis do modelo diferenciam maiusculas de minúsculas.

Exemplos de cadeias de caracteres de modelo válido:

  • ""

  • "/ sapato"

  • "sapato / *"

  • "{calçado} / barco"

  • "{calçado} / {barco} /bed/ {quilt}"

  • "sapato / {barco}"

  • "sapato / {barco} / *"

  • "sapato/barco? x = 2"

  • "sapato / {barco}? x = {cama}"

  • "sapato / {barco}? x = {cama} & y = faixa"

  • "? x = {calçado}"

  • "calçados? x = 3 & y = {var}

Exemplos de cadeias de caracteres de modelo inválido:

  • "{calçado} / {CALÇADO} / x = 2" – variável nomes duplicados.

  • "{calçado} /boat/? cama = {calçado}" – variável nomes duplicados.

  • "? x = 2 & x = 3" – pares de nome/valor dentro de uma cadeia de caracteres de consulta devem ser exclusivos, mesmo se eles são literais.

  • "? x = 2 &" – cadeia de caracteres de consulta está malformada.

  • "? 2 & x = {calçado}" – cadeia de caracteres de consulta deve ser pares nome/valor.

  • "? y = 2 & & X = 3" – cadeia de caracteres de consulta deve ser pares de valor de nome, nomes não podem começar com '&'.

Segmentos de caminho composto permitem que um único segmento de caminho URI conter várias variáveis, bem como variáveis combinados com literais. A seguir estão exemplos de segmentos de caminho composto válido.

  • /filename. {ext} /

  • /{filename}.jpg/

  • / {filename}. {ext} /

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

A seguir estão exemplos de segmentos de caminho inválido.

  • /{} - Variáveis devem ser nomeadas.

  • / {calçado} {barco} - variáveis devem ser separadas por um literal.

Segmentos de caminho composto permitem que você defina um UriTemplate que tem diversas variáveis dentro de um único segmento de caminho. Por exemplo, na cadeia de modelo a seguir: "endereços / {estado}. {Cidade} "duas variáveis (estado e cidade) são definidos dentro do mesmo segmento. Este modelo corresponderia a uma URL como "http://example.com/Washington.Redmond", mas também serão compatíveis com uma URL como "http://example.com/Washington.Redmond.Microsoft". No último caso, a variável de estado conterá "Washington" e a variável de cidade irá conter "Redmond.Microsoft". Nesse caso, qualquer texto (exceto '/') será compatível com a variável {cidade}. Se você usar um modelo que não corresponde o texto "extra", coloca a variável em um segmento separado de modelo, por exemplo: "endereços / {estado} / {cidade}.

Um segmento curinga nomeada é qualquer segmento de caminho variável cujo nome de variável começa com o caractere curinga ' *'. A seguinte cadeia de caracteres de modelo contém um segmento curinga nomeado chamado "sapato".

"literal/{*shoe}"

Segmentos de curinga devem seguir as regras a seguir:

  • Pode haver no máximo um segmento curinga nomeada para cada cadeia de caracteres do modelo.

  • Um segmento curinga nomeada deve aparecer no segmento a mais à direita no caminho.

  • Um segmento curinga nomeado não pode coexistir com um segmento curinga anônimo na mesma cadeia de caracteres do modelo.

  • O nome de um segmento curinga nomeada deve ser exclusivo.

  • Chamado curinga segmentos não podem ter valores padrão.

  • Segmentos nomeados curinga não podem terminar com "/".

Valores de variável padrão permitem que você especifique valores padrão para variáveis em um modelo. Variáveis de padrão podem ser especificadas com as chaves que declara a variável ou como uma coleção passada para o construtor UriTemplate. O modelo a seguir mostra duas maneiras de especificar um UriTemplate com variáveis com valores padrão.

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

Este modelo declara uma variável chamada a com um valor padrão de 1 e uma variável chamada b com um valor padrão de 5.

System_CAPS_noteObservação

Somente variáveis de segmento de caminho são podem ter valores padrão. Variáveis de cadeia de caracteres de consulta, variáveis de segmento composto e variáveis nomeadas curinga não podem ter valores padrão.

O código a seguir mostra como os valores de variável padrão são tratados durante a correspondência de um URI de candidato.

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

System_CAPS_noteObservação

Um URI, como http://localhost:8000 / / / não coincide com o modelo listado no código anterior, porém um URI, como http://localhost:8000 / does.

O código a seguir mostra como os valores de variável padrão são tratados durante a criação de um URI com um modelo.

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

Quando uma variável recebe um valor padrão de null algumas restrições adicionais. Uma variável pode ter um valor padrão de null se a variável está contida no segmento mais à direita da cadeia de caracteres de modelo ou se todos os segmentos à direita do segmento têm valores padrão de null. A seguir é cadeias de caracteres de modelo válido com valores padrão do 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 seguir é cadeias de caracteres de modelo inválido com valores padrão do 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
    

Quando a correspondência de um candidato URI com um modelo que tem valores padrão, os valores padrão são colocados no BoundVariables coleção se valores não forem especificados no URI candidate.

Dois modelos são considerados estrutural equivalente quando todos os literais os modelos correspondem e têm variáveis nos mesmos segmentos. Por exemplo, os seguintes modelos são estruturalmente equivalentes:

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

Algumas coisas a serem observadas:

  • Se um modelo contém barras à esquerda, somente o primeiro deles é ignorado.

  • Ao comparar cadeias de caracteres de modelo para equivalência estrutural, caso é ignorado para nomes de variáveis e segmentos de caminho, cadeias de caracteres de consulta diferenciam maiusculas de minúsculas.

  • Cadeias de caracteres de consulta são ordenadas.

O UriTemplateTable classe representa uma tabela associativa de UriTemplate objetos associados a um objeto do desenvolvedor da escolha. Um UriTemplateTable deve conter pelo menos um UriTemplate antes de chamar MakeReadOnly(Boolean). O conteúdo de um UriTemplateTable pode ser alterada até MakeReadOnly(Boolean) é chamado. A validação é executada quando MakeReadOnly(Boolean) é chamado. O tipo de validação executada depende do valor da allowMultiple parâmetro para MakeReadOnly(Boolean).

Quando MakeReadOnly(Boolean) é chamado, passando em false, o UriTemplateTable verifica se não há nenhum modelo na tabela. Se ele encontrar quaisquer modelos estrutural equivalentes, ele gerará uma exceção. Isso é usado em conjunto com MatchSingle(Uri) quando você deseja garantir a apenas um modelo corresponde a um URI de entrada.

Quando MakeReadOnly(Boolean) é chamado, passando em true, UriTemplateTable permite que vários modelos estruturalmente equivalente a ser contido dentro de um UriTemplateTable.

Se um conjunto de UriTemplate objetos adicionados a um UriTemplateTable contêm cadeias de caracteres de consulta não deve ser ambíguas. Cadeias de caracteres de consulta idênticos são permitidas.

System_CAPS_noteObservação

Enquanto o UriTemplateTable permite que a base de dados de endereços que esquemas de uso diferente de HTTP, o esquema e número da porta são ignorados durante a correspondência de candidato URIs para modelos.

Modelos que compartilham um caminho equivalente contêm cadeias de caracteres de consulta ambíguo se houver um URI que corresponda a mais de um modelo.

Os seguintes conjuntos de cadeias de caracteres de consulta são inequívoco em si:

  • ? x = 1

  • ? x = 2

  • ? x = 3

  • ? x = 1 & y = {var}

  • ? x = 2 & z = {var}

  • ? x = 3

  • ? x = 1

  • ?

  • ? x = {var}

  • ?

  • ? m = c & obter = rss

  • ? m = c & locar = rss

  • ? m = c & obter = atom

  • ? m = c & locar = atom

Os seguintes conjuntos de modelos de cadeia de caracteres de consulta são ambíguos em si:

  • ? x = 1

  • ? x = {var}

"x = 1"-coincide com os dois modelos.

  • ? x = 1

  • ? y = 2

"x = 1 & y = 2" corresponde a ambos os modelos. Isso ocorre porque uma cadeia de caracteres de consulta pode conter mais variáveis de cadeia de caracteres de consulta e o modelo corresponde.

  • ? x = 1

  • ? x = 1 & y = {var}

"x = 1 & y = 3" corresponde a ambos os modelos.

  • ? x = 3 & y = 4

  • ? x = 3 & z = 5

System_CAPS_noteObservação

Os caracteres á e Á são considerados caracteres diferentes quando aparecem como parte de um caminho de URI ou UriTemplate segmento de caminho literal (mas os caracteres e A são considerados o mesmo). Os caracteres á e Á são considerados os mesmos caracteres quando aparecem como parte de um UriTemplate {variableName} ou uma sequência de caracteres de consulta (e a e também são considerados para ser os mesmos caracteres).

Mostrar: