Общие сведения о модели программирования WCF Web HTTPWCF Web HTTP Programming Model Overview

Модель программирования веб-сервера HTTP Windows Communication Foundation (WCF) предоставляет основные элементы, необходимые для сборки веб-служб HTTP с помощью WCF.The Windows Communication Foundation (WCF) WEB HTTP programming model provides the basic elements required to build WEB HTTP services with WCF. Службы WCF WEB HTTP предназначены для доступа к широкому спектру возможных клиентов, включая веб-браузеры, и имеют следующие уникальные требования.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:

  • URI и обработка URI Универсальные коды ресурсов (URI) играют центральную роль в разработке веб-служб HTTP.URIs and URI Processing URIs play a central role in the design of WEB HTTP services. Модель программирования WCF WEB HTTP использует UriTemplate UriTemplateTable классы и для предоставления возможностей обработки URI.The WCF WEB HTTP programming model uses the UriTemplate and UriTemplateTable classes to provide URI processing capabilities.

  • Поддержка операций Get и POST ВЕБ-службы HTTP используют команду GET для получения данных в дополнение к различным командам Invoke для изменения данных и удаленного вызова.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. Модель программирования WCF WEB HTTP использует WebGetAttribute и WebInvokeAttribute для связывания операций службы с Get и другими КОМАНДАми HTTP, такими как помещение, публикация и удаление.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.

  • Несколько форматов данных Веб-службы обрабатывают множество типов данных в дополнение к сообщениям SOAP.Multiple data formats Web-style services process many kinds of data in addition to SOAP messages. Модель программирования WCF WEB HTTP использует WebHttpBinding и WebHttpBehavior для поддержки множества различных форматов данных, включая XML-документы, объекты данных JSON и потоки двоичного содержимого, такие как изображения, видеофайлы или обычный текст.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.

Модель программирования WCF WEB HTTP расширяет возможности WCF для использования веб-сценариев, в том числе веб-служб HTTP, AJAX и служб JSON, а также каналов синдикации (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. Дополнительные сведения о службах AJAX и JSON см. в разделе Интеграция Ajax и поддержка JSON.For more information about AJAX and JSON services, see AJAX Integration and JSON Support. Дополнительные сведения об синдикации см. в разделе Обзор синдикации WCF.For more information about Syndication, see WCF Syndication Overview.

Какие-либо дополнительные ограничения на типы данных, которые могут быть возвращены из веб-службы HTTP, отсутствуют.There are no extra restrictions on the types of data that can be returned from a WEB HTTP service. При работе веб-службы HTTP могут быть возвращены любые сериализуемые данные.Any serializable type can be returned from an WEB HTTP service operation. Операции веб-службы HTTP могут быть вызваны веб-браузером, поэтому предусмотрены ограничения, касающиеся того, какие типы данных могут указываться в 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. Дополнительные сведения о типах, поддерживаемых по умолчанию, см. в разделе Параметры строки запроса UriTemplate и URL-адреса ниже.For more information on what types are supported by default see the UriTemplate Query String Parameters and URLs section below. Это поведение по умолчанию можно изменить, предоставив собственную реализацию объекта T:System.ServiceModel.Dispatcher.QueryStringConverter, которая определяет, как преобразовывать параметры, заданные в URL-адресе, в фактические типы параметров.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. Дополнительные сведения см. в разделе QueryStringConverter.For more information, see QueryStringConverter

Внимание!

Службы, написанные с помощью модели программирования WCF WEB HTTP, не используют сообщения SOAP.Services written with the WCF WEB HTTP programming model do not use SOAP messages. Поскольку протокол SOAP не используется, функции безопасности, предоставляемые WCF, использовать нельзя.Because SOAP is not used, the security features provided by WCF cannot be used. Однако можно использовать безопасность уровня транспорта, разместив службу через HTTPS.You can, however use transport-based security by hosting your service with HTTPS. Дополнительные сведения о безопасности WCF см. в разделе Общие сведения о безопасности .For more information about WCF security, see Security Overview

Предупреждение

Установка расширения WebDAV для служб IIS может привести к тому, что веб-службы HTTP будут возвращать ошибку HTTP 405, поскольку расширение WebDAV пытается обрабатывать все запросы 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. Для решения этой проблемы расширение WebDAV можно удалить либо отключить его для данного веб-узла.To work around this issue you can uninstall the WebDAV extension or disable the WebDAV extension for your web site. Дополнительные сведения см. в разделе IIS и WebDAV .For more information, see IIS and WebDav

Обработка универсального кода ресурса (URI) с помощью UriTemplate и UriTemplateTableURI Processing with UriTemplate and UriTemplateTable

Шаблоны URI предоставляют эффективный синтаксис представления больших наборов URI или схожих по структуре URI.URI templates provide an efficient syntax for expressing large sets of structurally similar URIs. Например, следующий шаблон представляет набор всех трехсегментных URI, начинающихся с "a" и заканчивающихся на "c", независимо от значения промежуточного сегмента: a/{segment}/c.For 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

Данный шаблон описывает универсальные коды ресурса, подобные следующим:This template describes URIs like the following:

  • a/x/ca/x/c

  • a/y/ca/y/c

  • a/z/ca/z/c

  • и другие возможности.and so on.

В этом шаблоне запись в фигурных скобках ("{segment}") обозначает переменный сегмент, а не литеральное значение.In this template, the curly brace notation ("{segment}") indicates a variable segment instead of a literal value.

Платформа .NET Framework предусматривает API для работы с шаблонами URI, который называется UriTemplate..NET Framework provides an API for working with URI templates called UriTemplate. UriTemplates позволяет выполнять следующие действия.UriTemplates allow you to do the following:

  • Можно вызвать один из Bind методов с набором параметров, чтобы получить полностью закрытый URI , соответствующий шаблону.You can call one of the Bind methods with a set of parameters to produce a fully-closed URI that matches the template. Это означает, что все переменные в шаблоне URI заменяются фактическими значениями.This means all variables within the URI template are replaced with actual values.

  • Можно вызвать Match() с потенциальным URI, который использует шаблон для разбиения потенциального URI на составные части и возвращает словарь, содержащий различные части URI, помеченные в соответствии с переменными в шаблоне.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() и Match() являются инверсиями, поэтому можно вызвать Match( Bind( x ) ) и вернуться к той среде, в которой была начата работа.Bind() and Match() are inverses so that you can call Match( Bind( x ) ) and come back with the same environment you started with.

Очень часто (особенно на стороне сервера, где необходимо направить запрос операции службы на основе URI), бывает необходимо отслеживать набор объектов UriTemplate в структуре данных, которые могут независимо обращаться к каждому из включенных шаблонов.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 представляет набор шаблонов URI и выбирает самый подходящий заданный набор шаблонов и потенциальный URI.UriTemplateTable represents a set of URI templates and selects the best match given a set of templates and a candidate URI. Это не связано с каким-либо конкретным сетевым стеком (включенным в WCF), поэтому его можно использовать везде, где это необходимо.This is not affiliated with any particular networking stack (WCF included) so you can use it wherever necessary.

Для связывания операций службы с набором URI, который описывается шаблоном UriTemplate, модель службы WCF использует шаблон UriTemplateTable и таблицу шаблонов UriTemplate.The WCF Service Model makes use of UriTemplate and UriTemplateTable to associate service operations with a set of URIs described by a UriTemplate. Операция службы связывается с шаблоном UriTemplate с помощью атрибута WebGetAttribute или WebInvokeAttribute.A service operation is associated with a UriTemplate, using either the WebGetAttribute or the WebInvokeAttribute. Дополнительные сведения о UriTemplate и см. в UriTemplateTable разделе UriTemplate и UriTemplateTable .For more information about UriTemplate and UriTemplateTable, see UriTemplate and UriTemplateTable

Атрибуты WebGet и WebInvokeWebGet and WebInvoke Attributes

Службы WCF WEB HTTP используют команды извлечения (например, HTTP GET) в дополнение к различным командам вызова (например, HTTP POST, WHERE и 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). Модель программирования WCF WEB HTTP позволяет разработчикам служб управлять шаблоном и командой URI, связанными с операциями службы, с помощью WebGetAttribute и 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. Атрибуты WebGetAttribute и WebInvokeAttribute позволяют управлять привязкой отдельных операций к URI и методам HTTP, связанным с этими URI.The WebGetAttribute and the WebInvokeAttribute allow you to control how individual operations get bound to URIs and the HTTP methods associated with those URIs. Например, добавление атрибутов WebGetAttribute и WebInvokeAttribute продемонстрировано в следующем примере кода.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 );  
}  

Предыдущий код позволяет создавать следующие HTTP-запросы.The preceding code allows you to make the following HTTP requests.

GET /GetCustomer

POST /UpdateCustomerName

Атрибут WebInvokeAttribute по умолчанию имеет значение POST, но его можно использовать и для других команд.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 );  
}  

Полный пример службы WCF, использующей модель программирования WCF WEB HTTP, см. в разделе как создать базовую веб-службу HTTP WCFTo 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

Параметры строки запроса UriTemplate и URL-адресаUriTemplate Query String Parameters and URLs

Веб-службы можно вызвать из веб-браузера, введя URL-адрес, связанный с операцией службы.Web-style services can be called from a Web browser by typing a URL that is associated with a service operation. Эти операции службы могут принимать параметры строки запроса, которые необходимо указывать в URL-адресе в строковом формате.These service operations may take query string parameters that must be specified in a string form within the URL. В таблице ниже представлены типы, которые могут передаваться внутри URL-адреса и используемого формата.The following table shows the types that can be passed within a URL and the format used.

ТипType ФорматFormat
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 - 18,446,744,073,709,551,6150 - 18,446,744,073,709,551,615
Single -3.402823e38–3.402823e38 (экспоненциальная запись не требуется)-3.402823e38 - 3.402823e38 (exponent notation is not required)
Double -1.79769313486232e308–1.79769313486232e308 (экспоненциальная запись не требуется)-1.79769313486232e308 - 1.79769313486232e308 (exponent notation is not required)
Char Любой отдельный символAny single character
Decimal Любое десятичное число в стандартной записи (без экспоненты)Any decimal in standard notation (no exponent)
Boolean True или False (с учетом регистра)True or False (case insensitive)
String Любая строка (пустая строка не поддерживается, преобразование не производится)Any string (null string is not supported and no escaping is done)
DateTime ММ/ДД/ГГГГMM/DD/YYYY

ММ/ДД/ГГГГ ЧЧ: ММ: СС [AM|PM]MM/DD/YYYY HH:MM:SS [AM|PM]

Месяц, день, годMonth Day Year

Месяц, год, чч: мм: СС [AM|PM]Month Day Year HH:MM:SS [AM|PM]
TimeSpan ДД.ЧЧ:ММ:СС,DD.HH:MM:SS

где ДД = дни, ЧЧ = часы, ММ = минуты, СС = секунды.Where DD = Days, HH = Hours, MM = minutes, SS = Seconds
Guid Например, идентификатор GUID:A GUID, for example:

936DA01F-9ABD-4d9d-80C7-02AF85C822A8936DA01F-9ABD-4d9d-80C7-02AF85C822A8
DateTimeOffset ММ/ДД/ГГГГ ЧЧ:ММ:СС ММ:СС,MM/DD/YYYY HH:MM:SS MM:SS

где ДД = дни, ЧЧ = часы, ММ = минуты, СС = секунды.Where DD = Days, HH = Hours, MM = minutes, SS = Seconds
ПеречисленияEnumerations Значение перечисления, которое, например, определяет перечисление, как показано в следующем примере кода.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 };

В строке запроса можно указать любое отдельное значение перечисления (или соответствующее ему целочисленное значение).Any of the individual enumeration values (or their corresponding integer values) may be specified in the query string.
Типы, содержащие TypeConverterAttribute, который может преобразовать типы в строковое представление и обратно.Types that have a TypeConverterAttribute that can convert the type to and from a string representation. Зависит от преобразователя типов.Depends on the Type Converter.

Форматы и модель программирования WCF WEB HTTPFormats and the WCF WEB HTTP Programming Model

Модель программирования WCF WEB HTTP обладает новыми возможностями для работы с различными форматами данных.The WCF WEB HTTP programming model has new features to work with many different data formats. На уровне привязки WebHttpBinding может считывать и записывать следующие различные типы данных.At the binding layer, the WebHttpBinding can read and write the following different kinds of data:

  • XMLXML

  • JSONJSON

  • Непрозрачные двоичные потокиOpaque binary streams

Это означает, что модель программирования WCF WEB HTTP может обрабатывать любые типы данных, но может быть написана в программировании 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 обеспечивает поддержку данных JSON (AJAX), а также каналов синдикации (включая ATOM и RSS)..NET Framework 3.5 provides support for JSON data (AJAX) as well as Syndication feeds (including ATOM and RSS). Дополнительные сведения об этих возможностях см. в статьях Форматирование веб-HTTP WCF, Обзор синдикации WCFи Интеграция Ajax и поддержка JSON.For more information about these features, see WCF Web HTTP Formatting, WCF Syndication Overview, and AJAX Integration and JSON Support.

Модель программирования WCF WEB HTTP и безопасностьWCF WEB HTTP Programming Model and Security

Так как модель программирования WCF WEB HTTP не поддерживает протоколы WS-*, единственным способом защиты веб-службы HTTP WCF является предоставление службы по протоколу HTTPS с помощью 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. Дополнительные сведения о настройке SSL с помощью IIS 7,0 см. в статье Реализация SSL в IIS.For more information about setting up SSL with IIS 7.0, see How to implement SSL in IIS.

Устранение неполадок в модели программирования WCF WEB HTTPTroubleshooting the WCF WEB HTTP Programming Model

Когда службы WCF WEB HTTP вызываются с помощью ChannelFactoryBase<TChannel> для создания канала, WebHttpBehavior использует адрес EndpointAddress, заданный в файле конфигурации, даже в случае, когда в EndpointAddress передается другой 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>.

См. такжеSee also