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

Статья
02/28/2011

Модель программирования Windows Communication Foundation (WCF) WEB HTTP предоставляет основные элементы, необходимые для построения служб WEB HTTP с помощью WCF. Службы WCF WEB HTTP рассчитаны на доступ со стороны широкого диапазона возможных клиентов, включая веб-обозреватели, и обладают следующими уникальными требованиями.

URI и обработка URI. URI играют центральную роль в проектировании служб WEB HTTP. Для предоставления возможностей обработки URI модель программирования WCF WEB HTTP использует классы UriTemplate и UriTemplateTable.
Поддержка операций GET и POST. Службы WEB HTTP используют команду GET для получения данных, а также различные команды вызова для изменения данных и удаленного вызова. В модели программирования WCF WEB HTTP используются атрибуты WebGetAttribute и WebInvokeAttribute для сопоставления операций службы с командой GET и другими командами HTTP, такими как PUT, POST и DELETE.
Несколько форматов данных. Веб-службы обрабатывают много типов данных, помимо сообщений SOAP. Для поддержки нескольких различных форматов данных (включая документы XML, объекты данных JSON и потоки двоичного содержимого, такие как изображения, видеофайлы или обычный текст) модель программирования WCF WEB HTTP использует привязку WebHttpBinding и поведение WebHttpBehavior.

Модель программирования WEB HTTP WCF расширяет возможности WCF и делает возможной поддержку веб-сценариев, включающих службы WEB HTTP, AJAX и JSON, а также каналы синдикации (ATOM/RSS). Дополнительные сведения службах AJAX и JSON см. в разделе Интеграция с AJAX и поддержка JSON. Дополнительные сведения синдикации см. в разделе Общие сведения о синдикации WCF.

Какие-либо дополнительные ограничения на типы данных, которые могут быть возвращены из веб-службы HTTP, отсутствуют. При работе веб-службы HTTP могут быть возвращены любые сериализуемые данные. Операции веб-службы HTTP могут быть вызваны веб-обозревателем, поэтому предусмотрены ограничения, касающиеся того, какие типы данных могут указываться в URL-адресах. Дополнительные сведения о том, какие типы поддерживаются по умолчанию, см. в приведенном далее разделе Параметры и URL-адреса строки запроса UriTemplate. Это поведение по умолчанию можно изменить, предоставив собственную реализацию объекта T:System.ServiceModel.Dispatcher.QueryStringConverter, которая определяет, как преобразовывать параметры, заданные в URL-адресе, в фактические типы параметров. Дополнительные сведения см. в разделе QueryStringConverter

Внимание!
Службы, написанные по модели программирования WCF WEB HTTP, не используют сообщения SOAP. Поскольку SOAP не используется, то нельзя использовать средства безопасности, предоставляемые WCF, однако можно использовать транспортную безопасность, размещая службу с помощью HTTPS. Дополнительные сведения о безопасности WCF см. в разделе Общие сведения о безопасности.

Службы, написанные по модели программирования WCF WEB HTTP, не используют сообщения SOAP. Поскольку SOAP не используется, то нельзя использовать средства безопасности, предоставляемые WCF, однако можно использовать транспортную безопасность, размещая службу с помощью HTTPS. Дополнительные сведения о безопасности WCF см. в разделе Общие сведения о безопасности.

Внимание!
Установка расширения WebDAV для служб IIS может привести к тому, что веб-службы HTTP будут возвращать ошибку HTTP 405, поскольку расширение WebDAV пытается обрабатывать все запросы PUT. Для решения этой проблемы расширение WebDAV можно удалить либо отключить его для данного веб-узла. Дополнительные сведения см. в разделе IIS и WebDav

Установка расширения WebDAV для служб IIS может привести к тому, что веб-службы HTTP будут возвращать ошибку HTTP 405, поскольку расширение WebDAV пытается обрабатывать все запросы PUT. Для решения этой проблемы расширение WebDAV можно удалить либо отключить его для данного веб-узла. Дополнительные сведения см. в разделе IIS и WebDav

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

Шаблоны URI предоставляют эффективный синтаксис представления больших наборов URI или схожих по структуре URI. Например, следующий шаблон представляет набор всех трехсегментных URI, начинающихся с "a" и заканчивающихся на "c", независимо от значения промежуточного сегмента: a/{segment}/c.

Данный шаблон описывает универсальные коды ресурса, подобные следующим:

a/x/c
a/y/c
a/z/c
и т. д.

В этом шаблоне запись в фигурных скобках ("{segment}") обозначает переменный сегмент, а не литеральное значение.

.NET Framework предоставляет API для работы с шаблонами URI, называемыми UriTemplate. Шаблоны UriTemplates позволяют выполнять следующие действия.

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

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

Для связывания операций службы с набором URI, который описывается шаблоном UriTemplate, модель службы WCF использует шаблон UriTemplate и таблицу шаблонов UriTemplateTable. Операция службы связывается с шаблоном UriTemplate с помощью атрибута WebGetAttribute или WebInvokeAttribute. Дополнительные сведения о UriTemplate и UriTemplateTable см. в разделе UriTemplate и UriTemplateTable.

Атрибуты WebGet и WebInvoke

Службы WCF WEB HTTP используют команды получения (например, HTTP GET), а также различные команды вызова (например, HTTP POST, PUT и DELETE). Модель программирования WCF WEB HTTP позволяет разработчикам службы управлять шаблоном URI и командой, связанной с операциями службы, с помощью атрибутов WebGetAttribute и WebInvokeAttribute. Атрибуты WebGetAttribute и WebInvokeAttribute позволяют управлять привязкой отдельных операций к URI и методам HTTP, связанным с этими URI. Например, добавление атрибутов WebGetAttribute и WebInvokeAttribute продемонстрировано в следующем примере кода.

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

Предыдущий код позволяет создавать следующие HTTP-запросы.

GET /GetCustomer

POST /UpdateCustomerName

Атрибут WebInvokeAttribute по умолчанию имеет значение POST, но его можно использовать и для других команд.

[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, см. в разделе Как создать простую веб-службу WCF HTTP.

Параметры строки запроса UriTemplate и URL-адреса

Веб-службы можно вызвать из веб-обозревателя, введя URL-адрес, связанный с операцией службы. Эти операции службы могут принимать параметры строки запроса, которые необходимо указывать в URL-адресе в строковом формате. В таблице ниже представлены типы, которые могут передаваться внутри URL-адреса и используемого формата.

Тип	Формат
Byte	0 - 255
SByte	-128 - 127
Int16	-32768 - 32767
Int32	-2,147,483,648 - 2,147,483,647
Int64	-9,223,372,036,854,775,808 - 9,223,372,036,854,775,807
UInt16	0 - 65535
UInt32	0 - 4,294,967,295
UInt64	0 - 18,446,744,073,709,551,615
Single	-3.402823e38–3.402823e38 (экспоненциальная запись не требуется)
Double	-1.79769313486232e308–1.79769313486232e308 (экспоненциальная запись не требуется)
Char	Любой отдельный знак
Decimal	Любое десятичное число в стандартной записи (без экспоненты)
Boolean	True или False (с учетом регистра)
String	Любая строка (пустая строка не поддерживается, преобразование не производится)
DateTime	ММ/ДД/ГГГГ ММ/ДД/ГГГГ ЧЧ:ММ:СС [AM\|PM] Месяц, день, год Месяц, день, год, ЧЧ:ММ:СС [AM\|PM]
TimeSpan	ДД.ЧЧ:ММ:СС, где ДД = дни, ЧЧ = часы, ММ = минуты, СС = секунды.
Guid	Например, идентификатор GUID: 936DA01F-9ABD-4d9d-80C7-02AF85C822A8
DateTimeOffset	ММ/ДД/ГГГГ ЧЧ:ММ:СС ММ:СС, где ДД = дни, ЧЧ = часы, ММ = минуты, СС = секунды.
Enumerations	Значение перечисления, которое, например, определяет перечисление, как показано в следующем примере кода. `public enum Days{ Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, Saturday };` В строке запроса можно указать любое отдельное значение перечисления (или соответствующее ему целочисленное значение).
Типы, содержащие атрибут TypeConverterAttribute, который может преобразовывать типы в строковое представление и обратно.	Зависит от преобразователя типов.

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

Модель программирования WCF WEB HTTP содержит новые функции для работы с несколькими различными форматами данных. На уровне привязки WebHttpBinding может считывать и записывать следующие различные типы данных.

XML
JSON
Непрозрачные двоичные потоки

Это означает, что модель программирования WCF WEB HTTP может обрабатывать любой тип данных, но при этом возможно программирование объектов Stream.

.NET Framework 3.5 поддерживает данные JSON (AJAX) и веб-каналы синдикации (в том числе ATOM и RSS). Дополнительные сведения об этих функциях см. в разделах Форматирование веб-объектов HTTP WCF, Общие сведения о синдикации WCF и Интеграция с AJAX и поддержка JSON.

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

Поскольку модель программирования WCF WEB HTTP не поддерживает протоколы WS-*, единственным способом защиты службы WCF WEB HTTP является предоставление доступа к ней через HTTPS с использованием SSL. Дополнительные сведения о настройке SSL с IIS 7.0 см. в разделе Как реализовать SSL в службах IIS (на английском языке).

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

Когда службы WCF WEB HTTP вызываются с помощью ChannelFactory для создания канала, WebHttpBehavior использует адрес EndpointAddress, заданный в файле конфигурации, даже в случае, когда в ChannelFactory передается другой EndpointAddress.

См. также

Основные понятия

Объектная модель программирования WCF Web HTTP

Другие ресурсы

Синдикация WCF
Модель веб-программирования HTTP WCF

Поделиться через