Visão geral de modelo de programação HTTP Web do WCFWCF Web HTTP Programming Model Overview

O modelo de programação HTTP WEB do Windows Communication Foundation (WCF) fornece os elementos básicos necessários para criar serviços HTTP WEB com o WCF.The Windows Communication Foundation (WCF) WEB HTTP programming model provides the basic elements required to build WEB HTTP services with WCF. Os serviços HTTP WEB do WCF são projetados para serem acessados pela mais ampla variedade de clientes possíveis, incluindo navegadores da Web e têm os seguintes requisitos exclusivos:WCF WEB HTTP services are designed to be accessed by the widest range of possible clients, including Web browsers and have the following unique requirements:

  • URIs e processamento de URI Os URIs desempenham uma função central no design dos serviços HTTP da WEB.URIs and URI Processing URIs play a central role in the design of WEB HTTP services. O modelo de programação WEB HTTP do WCF usa as UriTemplate UriTemplateTable classes e para fornecer recursos de processamento de URI.The WCF WEB HTTP programming model uses the UriTemplate and UriTemplateTable classes to provide URI processing capabilities.

  • Suporte para operações Get e post Os serviços HTTP da WEB usam o verbo GET para recuperação de dados, além de vários verbos de invocação para modificação de dados e invocação remota.Support for GET and POST operations WEB HTTP services make use of the GET verb for data retrieval, in addition to various invoke verbs for data modification and remote invocation. O modelo de programação WEB HTTP do WCF usa o WebGetAttribute e o WebInvokeAttribute para associar operações de serviço com VERBOS http Get e outros, como put, post e Delete.The WCF WEB HTTP programming model uses the WebGetAttribute and WebInvokeAttribute to associate service operations with both GET and other HTTP verbs like PUT, POST, and DELETE.

  • Vários formatos de dados Os serviços de estilo da Web processam muitos tipos de dados além das mensagens SOAP.Multiple data formats Web-style services process many kinds of data in addition to SOAP messages. O modelo de programação WEB HTTP do WCF usa o WebHttpBinding e WebHttpBehavior para oferecer suporte a vários formatos de dados diferentes, incluindo documentos XML, objeto de dados JSON e fluxos de conteúdo binário, como imagens, arquivos de vídeo ou texto sem formatação.The WCF WEB HTTP programming model uses the WebHttpBinding and WebHttpBehavior to support many different data formats including XML documents, JSON data object, and streams of binary content such as images, video files, or plain text.

O modelo de programação WEB HTTP do WCF amplia o alcance do WCF para abranger cenários de estilo da Web que incluem serviços HTTP WEB, serviços AJAX e JSON e feeds de distribuição (ATOM/RSS).The WCF WEB HTTP programming model extends the reach of WCF to cover Web-style scenarios that include WEB HTTP services, AJAX and JSON services, and Syndication (ATOM/RSS) feeds. Para obter mais informações sobre os serviços AJAX e JSON, consulte integração Ajax e suporte JSON.For more information about AJAX and JSON services, see AJAX Integration and JSON Support. Para obter mais informações sobre a distribuição, consulte visão geral da agregação do WCF.For more information about Syndication, see WCF Syndication Overview.

Não há nenhuma restrição extra nos tipos de dados que podem ser retornados de um serviço HTTP da WEB.There are no extra restrictions on the types of data that can be returned from a WEB HTTP service. Qualquer tipo serializável pode ser retornado de uma operação de serviço HTTP WEB.Any serializable type can be returned from an WEB HTTP service operation. Como as operações de serviço HTTP da WEB podem ser invocadas por um navegador da Web, há uma limitação sobre quais tipos de dados podem ser especificados em uma URL.Because WEB HTTP service operations can be invoke by a web browser there is a limitation on what data types can be specified in a URL. Para obter mais informações sobre quais tipos têm suporte por padrão, consulte a seção URLs e parâmetros da cadeia de consulta do UriTemplate abaixo.For more information on what types are supported by default see the UriTemplate Query String Parameters and URLs section below. O comportamento padrão pode ser alterado fornecendo sua própria implementação de T:System.ServiceModel.Dispatcher.QueryStringConverter, que especifica como converter os parâmetros especificados em uma URL para o tipo de parâmetro real.The default behavior can be changed by providing your own T:System.ServiceModel.Dispatcher.QueryStringConverter implementation which specifies how to convert the parameters specified in a URL to the actual parameter type. Para obter mais informações, consulte QueryStringConverter.For more information, see QueryStringConverter

Cuidado

Os serviços escritos com o modelo de programação WEB HTTP do WCF não usam mensagens SOAP.Services written with the WCF WEB HTTP programming model do not use SOAP messages. Como o SOAP não é usado, os recursos de segurança fornecidos pelo WCF não podem ser usados.Because SOAP is not used, the security features provided by WCF cannot be used. Você pode, no entanto, usar a segurança baseada em transporte hospedando seu serviço com HTTPS.You can, however use transport-based security by hosting your service with HTTPS. Para obter mais informações sobre a segurança do WCF, consulte visão geral de segurançaFor more information about WCF security, see Security Overview

Aviso

A instalação da extensão WebDAV para o IIS pode fazer com que os serviços HTTP da Web retornem um erro HTTP 405, pois a extensão WebDAV tenta lidar com todas as solicitações PUT.Installing the WebDAV extension for IIS can cause Web HTTP services to return an HTTP 405 error as the WebDAV extension attempts to handle all PUT requests. Para contornar esse problema, você pode desinstalar a extensão WebDAV ou desabilitar a extensão WebDAV para seu site.To work around this issue you can uninstall the WebDAV extension or disable the WebDAV extension for your web site. Para obter mais informações, consulte IIS e WebDAVFor more information, see IIS and WebDav

Processamento de URI com UriTemplate e UriTemplateTableURI Processing with UriTemplate and UriTemplateTable

Os modelos de URI fornecem uma sintaxe eficiente para expressar grandes conjuntos de URIs estruturalmente semelhantes.URI templates provide an efficient syntax for expressing large sets of structurally similar URIs. Por exemplo, o modelo a seguir expressa o conjunto de todos os URIs de três segmentos que começam com "a" e terminam com "c" sem considerar o valor do segmento intermediário: a/{Segment}/cFor example, the following template expresses the set of all three-segment URIs that begin with "a" and end with "c" without regard to the value of the intermediate segment: a/{segment}/c

Este modelo descreve URIs como o seguinte:This template describes URIs like the following:

  • a/x/ca/x/c

  • a/s/ca/y/c

  • a/z/ca/z/c

  • e assim por diante.and so on.

Neste modelo, a notação de chave ("{Segment}") indica um segmento variável em vez de um valor literal.In this template, the curly brace notation ("{segment}") indicates a variable segment instead of a literal value.

.NET Framework fornece uma API para trabalhar com modelos de URI chamados UriTemplate ..NET Framework provides an API for working with URI templates called UriTemplate. UriTemplates permita que você faça o seguinte:UriTemplates allow you to do the following:

  • Você pode chamar um dos Bind métodos com um conjunto de parâmetros para produzir um URI totalmente fechado que corresponda ao modelo.You can call one of the Bind methods with a set of parameters to produce a fully-closed URI that matches the template. Isso significa que todas as variáveis dentro do modelo de URI são substituídas por valores reais.This means all variables within the URI template are replaced with actual values.

  • Você pode chamar Match () com um URI candidato, que usa um modelo para dividir um URI candidato em suas partes constituintes e retorna um dicionário que contém as diferentes partes do URI rotuladas de acordo com as variáveis no modelo.You can call Match() with a candidate URI, which uses a template to break up a candidate URI into its constituent parts and returns a dictionary that contains the different parts of the URI labeled according to the variables in the template.

  • Bind() e Match () são inversos para que você possa chamar Match ( Bind (x)) e voltar com o mesmo ambiente com o qual começou.Bind() and Match() are inverses so that you can call Match( Bind( x ) ) and come back with the same environment you started with.

Há muitas vezes (especialmente no servidor, em que a expedição de uma solicitação para uma operação de serviço baseada no URI é necessária) que você deseja manter o controle de um conjunto de UriTemplate objetos em uma estrutura de dados que possa tratar de forma independente cada um dos modelos contidos.There are many times (especially on the server, where dispatching a request to a service operation based on the URI is necessary) that you want to keep track of a set of UriTemplate objects in a data structure that can independently address each of the contained templates. UriTemplateTable representa um conjunto de modelos de URI e seleciona a melhor correspondência de acordo com um conjunto de modelos e um URI candidato.UriTemplateTable represents a set of URI templates and selects the best match given a set of templates and a candidate URI. Isso não é afiliado a nenhuma pilha de rede específica (WCF incluída) para que você possa usá-la sempre que necessário.This is not affiliated with any particular networking stack (WCF included) so you can use it wherever necessary.

O modelo de serviço do WCF usa UriTemplate e UriTemplateTable para associar operações de serviço com um conjunto de URIs descritos por um UriTemplate .The WCF Service Model makes use of UriTemplate and UriTemplateTable to associate service operations with a set of URIs described by a UriTemplate. Uma operação de serviço é associada a um UriTemplate , usando o WebGetAttribute ou o WebInvokeAttribute .A service operation is associated with a UriTemplate, using either the WebGetAttribute or the WebInvokeAttribute. Para obter mais informações sobre o UriTemplate e o UriTemplateTable , consulte UriTemplate e UriTemplateTableFor more information about UriTemplate and UriTemplateTable, see UriTemplate and UriTemplateTable

Atributos WebGet e WebInvokeWebGet and WebInvoke Attributes

Os serviços HTTP WEB do WCF fazem uso de verbos de recuperação (por exemplo, HTTP GET) Além de vários verbos de invocação (por exemplo, HTTP POST, PUT e DELETE).WCF WEB HTTP services make use of retrieval verbs (for example HTTP GET) in addition to various invoke verbs (for example HTTP POST, PUT, and DELETE). O modelo de programação WEB HTTP do WCF permite que os desenvolvedores de serviço controlem o modelo de URI e o verbo associados a suas operações de serviço com o WebGetAttribute e o WebInvokeAttribute .The WCF WEB HTTP programming model allows service developers to control the both the URI template and verb associated with their service operations with the WebGetAttribute and WebInvokeAttribute. O WebGetAttribute e o WebInvokeAttribute permitem que você controle como as operações individuais são associadas a URIs e os métodos http associados a esses URIs.The WebGetAttribute and the WebInvokeAttribute allow you to control how individual operations get bound to URIs and the HTTP methods associated with those URIs. Por exemplo, adicionar WebGetAttribute e WebInvokeAttribute no código a seguir.For example, adding WebGetAttribute and WebInvokeAttribute in the following code.

[ServiceContract]  
interface ICustomer  
{  
  //"View It"  
  
  [WebGet]  
  Customer GetCustomer():  
  
  //"Do It"  
    [WebInvoke]  
  Customer UpdateCustomerName( string id,
                               string newName );  
}  

O código anterior permite que você faça as seguintes solicitações HTTP.The preceding code allows you to make the following HTTP requests.

GET /GetCustomer

POST /UpdateCustomerName

WebInvokeAttribute o padrão é POST, mas você também pode usá-lo para outros verbos.WebInvokeAttribute defaults to POST but you can use it for other verbs too.

[ServiceContract]  
interface ICustomer  
{  
  //"View It" -> HTTP GET  
    [WebGet( UriTemplate="customers/{id}" )]  
  Customer GetCustomer( string id ):  
  
  //"Do It" -> HTTP PUT  
  [WebInvoke( UriTemplate="customers/{id}", Method="PUT" )]  
  Customer UpdateCustomer( string id, Customer newCustomer );  
}  

Para ver um exemplo completo de um serviço WCF que usa o modelo de programação WEB HTTP do WCF, consulte como: criar um serviço http Web do WCF básicoTo see a complete sample of a WCF service that uses the WCF WEB HTTP programming model, see How to: Create a Basic WCF Web HTTP Service

URLs e parâmetros de cadeia de consulta do UriTemplateUriTemplate Query String Parameters and URLs

Os serviços de estilo da Web podem ser chamados de um navegador da Web, digitando uma URL associada a uma operação de serviço.Web-style services can be called from a Web browser by typing a URL that is associated with a service operation. Essas operações de serviço podem pegar parâmetros de cadeia de caracteres de consulta que devem ser especificados em um formulário de cadeia de caracteres dentro da URL.These service operations may take query string parameters that must be specified in a string form within the URL. A tabela a seguir mostra os tipos que podem ser passados dentro de uma URL e o formato usado.The following table shows the types that can be passed within a URL and the format used.

TypeType FormatFormat
Byte 0 - 2550 - 255
SByte -128-127-128 - 127
Int16 -32768-32767-32768 - 32767
Int32 -2.147.483.648-2.147.483.647-2,147,483,648 - 2,147,483,647
Int64 -9.223.372.036.854.775.808-9.223.372.036.854.775.807-9,223,372,036,854,775,808 - 9,223,372,036,854,775,807
UInt16 0 - 655350 - 65535
UInt32 0-4.294.967.2950 - 4,294,967,295
UInt64 0-184467440737095516150 - 18,446,744,073,709,551,615
Single -3.402823 e38-3.402823 e38 (a notação exponencial não é necessária)-3.402823e38 - 3.402823e38 (exponent notation is not required)
Double -1.79769313486232 e308-1.79769313486232 e308 (a notação exponencial não é necessária)-1.79769313486232e308 - 1.79769313486232e308 (exponent notation is not required)
Char Qualquer caractere únicoAny single character
Decimal Qualquer decimal na notação padrão (sem expoente)Any decimal in standard notation (no exponent)
Boolean True ou false (não diferencia maiúsculas de minúsculas)True or False (case insensitive)
String Qualquer cadeia de caracteres (cadeia de caracteres nula não tem suporte e nenhuma saída é feita)Any string (null string is not supported and no escaping is done)
DateTime MM/DD/AAAAMM/DD/YYYY

MM/DD/AAAA HH: MM: SS [AM|PM]MM/DD/YYYY HH:MM:SS [AM|PM]

Mês dia anoMonth Day Year

Mês dia ano HH: MM: SS [AM|PM]Month Day Year HH:MM:SS [AM|PM]
TimeSpan DD. HH: MM: SSDD.HH:MM:SS

Onde DD = dias, HH = horas, MM = minutos, SS = segundosWhere DD = Days, HH = Hours, MM = minutes, SS = Seconds
Guid Um GUID, por exemplo:A GUID, for example:

936DA01F-9ABD-4d9d-80C7-02AF85C822A8936DA01F-9ABD-4d9d-80C7-02AF85C822A8
DateTimeOffset MM/DD/AAAA HH: MM: SS MM: SSMM/DD/YYYY HH:MM:SS MM:SS

Onde DD = dias, HH = horas, MM = minutos, SS = segundosWhere DD = Days, HH = Hours, MM = minutes, SS = Seconds
EnumeraçõesEnumerations O valor de enumeração, por exemplo, que define a enumeração, conforme mostrado no código a seguir.The enumeration value for example, which defines the enumeration as shown in the following code.

public enum Days{ Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, Saturday };

Qualquer um dos valores de enumeração individuais (ou seus valores inteiros correspondentes) pode ser especificado na cadeia de caracteres de consulta.Any of the individual enumeration values (or their corresponding integer values) may be specified in the query string.
Tipos que têm um TypeConverterAttribute que podem converter o tipo de e para uma representação de cadeia de caracteres.Types that have a TypeConverterAttribute that can convert the type to and from a string representation. Depende do conversor de tipo.Depends on the Type Converter.

Formatos e o modelo de programação WEB HTTP do WCFFormats and the WCF WEB HTTP Programming Model

O modelo de programação WEB HTTP do WCF tem novos recursos para trabalhar com vários formatos de dados diferentes.The WCF WEB HTTP programming model has new features to work with many different data formats. Na camada de associação, o WebHttpBinding pode ler e gravar os seguintes tipos diferentes de dados:At the binding layer, the WebHttpBinding can read and write the following different kinds of data:

  • XMLXML

  • JSONJSON

  • Fluxos binários opacosOpaque binary streams

Isso significa que o modelo de programação WEB HTTP do WCF pode lidar com qualquer tipo de dados, mas você pode estar programando Stream .This means the WCF WEB HTTP programming model can handle any type of data but, you may be programming against Stream.

.NET Framework 3,5 fornece suporte para dados JSON (AJAX), bem como feeds de distribuição (incluindo ATOM e RSS)..NET Framework 3.5 provides support for JSON data (AJAX) as well as Syndication feeds (including ATOM and RSS). Para obter mais informações sobre esses recursos, consulte formatação do WCF Web http, visão geral da agregação do WCFe suporte a integração do Ajax e JSON.For more information about these features, see WCF Web HTTP Formatting, WCF Syndication Overview, and AJAX Integration and JSON Support.

Segurança e modelo de programação do WCF WEB HTTPWCF WEB HTTP Programming Model and Security

Como o modelo de programação WEB HTTP do WCF não dá suporte aos protocolos WS-*, a única maneira de proteger um serviço WEB HTTP WCF é expor o serviço por HTTPS usando SSL.Because the WCF WEB HTTP programming model does not support the WS-* protocols, the only way to secure a WCF WEB HTTP service is to expose the service over HTTPS using SSL. Para obter mais informações sobre como configurar o SSL com o IIS 7,0, consulte como implementar o SSL no IIS.For more information about setting up SSL with IIS 7.0, see How to implement SSL in IIS.

Solução de problemas do modelo de programação WEB HTTP do WCFTroubleshooting the WCF WEB HTTP Programming Model

Ao chamar WCF WEB HTTP Services usando um ChannelFactoryBase<TChannel> para criar um canal, o WebHttpBehavior usa o EndpointAddress conjunto no arquivo de configuração, mesmo se um diferente EndpointAddress for passado para o ChannelFactoryBase<TChannel> .When calling WCF WEB HTTP services using a ChannelFactoryBase<TChannel> to create a channel, the WebHttpBehavior uses the EndpointAddress set in the configuration file even if a different EndpointAddress is passed to the ChannelFactoryBase<TChannel>.

Consulte tambémSee also