Служебное средство ServiceModel Metadata Utility Tool (Svcutil.exe)
Средство служебной программы метаданных ServiceModel используется для создания кода модели службы из документов метаданных и документов метаданных из кода модели службы.
SvcUtil.exe
Средство служебной программы метаданных ServiceModel можно найти в расположении установки пакета SDK для Windows, в частности %ProgramFiles%\Microsoft SDK\Windows\v6.0\Bin.
Функциональные возможности
В следующей таблице перечислены различные функциональные возможности, предоставляемые этим средством, и соответствующий раздел, в котором описывается использование:
| Задача | Раздел |
|---|---|
| Создает код из работающих служб или документов статических метаданных. | Создание клиента WCF из метаданных службы |
| Экспортирует документы метаданных из скомпилированного кода. | Практическое руководство. Использование программы Svcutil.exe для экспорта метаданных из скомпилированного кода службы |
| Проверяет скомпилированный код службы. | Практическое руководство. Использование программы Svcutil.exe для проверки скомпилированного кода службы |
| Загружает документы метаданных из работающих служб. | Практическое руководство. Использование Svcutil.exe для загрузки документов метаданных |
| Создает код сериализации. | Практическое руководство. Сокращение времени запуска клиентских приложений WCF с использованием XmlSerializer |
Внимание
Svcutil перезаписывает существующие файлы на диске, если имена, указанные в качестве параметров, идентичны. К ним могут относиться файлы кода, конфигурации или файлы метаданных. Чтобы избежать этого при создании файлов кода и конфигурации, используйте /mergeConfig параметр.
Кроме того, /r параметры для /ct ссылочных типов предназначены для создания контрактов данных. Эти переключатели не работают при использовании XmlSerializer.
Время ожидания
Средство имеет пять минут времени ожидания при получении метаданных. Это значение времени ожидания действительно только при извлечении метаданных по сети. Указанное время ожидания не применимо к обработке этих метаданных.
Настройка для различных версий
Программа не поддерживает настройку для различных версий. Если вы хотите создать артефакт платформа .NET Framework 4 из svcutil.exe, используйте svcutil.exe из пакета SDK платформа .NET Framework 4. Чтобы создать артефакт платформа .NET Framework 3.5, используйте исполняемый файл из пакета SDK платформа .NET Framework 3.5.
Доступ к документам WSDL
При использовании Svcutil для получения доступа к документу WSDL, который содержит ссылку на службу маркеров безопасности (STS), Svcutil осуществляет вызов службы маркеров безопасности по протоколу WS-MetadataExchange. Однако служба может предоставлять документы WSDL с помощью WS-MetadataExchange или запроса HTTP GET. Таким образом, если служба STS предоставила только документ WSDL с помощью HTTP GET, клиент, написанный в WinFX, завершится ошибкой. Для клиентов, написанных в платформа .NET Framework 3.5, Svcutil пытается использовать WS-MetadataExchange и HTTP GET для получения WSDL STS.
Использование программы SvcUtil.exe
Типичные способы использования
В следующей таблице показаны некоторые часто используемые параметры для этого средства:
| Вариант | Описание |
|---|---|
| /directory:<directory> | Каталог, в котором создаются файлы. По умолчанию: текущий каталог. Краткая форма: /d |
| /help | Отображает синтаксис команд и параметров для средства. Краткая форма: /? |
| /nologo | Подавляет вывод логотипа и сообщения об авторском праве. |
| /svcutilConfig:<configFile> | Задает пользовательский файл конфигурации, который следует использовать вместо файла App.config. С его помощью можно регистрировать расширения system.serviceModel, не изменяя файл конфигурации средства. |
| Тип /target:<output> | Задает выходные объекты, которые должны быть созданы с помощью средства. Допустимыми значениями являются код, метаданные или xmlSerializer. Краткая форма: /t |
Создание кода
Svcutil.exe может создавать код для контрактов службы, клиентов и типы данных из документов метаданных. Документы метаданных могут находиться в устойчивом хранилище или извлекаться в оперативном режиме. Извлечение в оперативном режиме происходит либо по протоколу WS-Metadata Exchange, либо по протоколу DISCO (дополнительные сведения см. в разделе "Загрузка метаданных").
С помощью средства SvcUtil.exe можно создавать контракты служб и данных на основе предопределенного документа WSDL. Укажите переключатель/erviceContract и URL-адрес, откуда можно загрузить документ WSDL, или расположение файла, где его можно найти. Это создает контракты службы и данных, определенные в документе WSDL, который затем можно использовать для реализации службы жалоб. Дополнительные сведения см. в разделе "Практическое руководство . Получение метаданных и реализация соответствующей службы".
Для службы с конечной точкой BasicHttpContextBinding Svcutil.exe создает BasicHttpBinding с набором allowCookiestrue атрибутов. Файлы cookie используются для создания контекста на сервере. Если необходимо управлять контекстом в клиенте при использовании службой файлов cookie, можно вручную изменить настройки для использования контекстной привязки.
Внимание
Svcutil.exe создает клиент на основе файла WSDL или файла политики, полученного от службы. Имя субъекта-пользователя (UPN) создается путем объединения имени пользователя, "@" и полного доменного имени (FQDN). Однако для пользователей, зарегистрированных в Active Directory, этот формат не является допустимым, и созданное средством имя участника-пользователя вызывает сбой проверки подлинности Kerberos с выдачей сообщения об ошибке "Сбой попытки входа в систему". Чтобы устранить эту проблему, необходимо вручную исправить файл клиента, созданный средством.
svcutil.exe [/t:code] <metadataDocumentPath>* | <url>* | <epr>
| Аргумент | Description |
|---|---|
epr |
Путь к файлу XML, который содержит ссылку на конечную точку службы WS-Addressing EndpointReference, которая поддерживает WS-Metadata Exchange. Дополнительные сведения см. в разделе "Загрузка метаданных". |
metadataDocumentPath |
Путь к документу метаданных (wsdl или xsd), который содержит контракт для импорта в код (WSDL, XSD, WSPOLICY или WSMEX). Svcutil следит за ходом импортирования и включает удаленный URL-адрес для метаданных, когда указано пользователем. Однако если файлы метаданных необходимо обработать в локальной файловой системе, все файлы следует задавать в этом аргументе. Таким образом, Svcutil можно использовать в среде построения, где отсутствуют сетевые зависимости. Для этого аргумента можно использовать дикие карта s (*.xsd, *.wsdl). |
url |
URL-адрес конечной точки службы, предоставляющей метаданные, или документа метаданных, размещенного в сети. Дополнительные сведения об извлечении этих документов см. в разделе "Загрузка метаданных". |
| Вариант | Описание |
|---|---|
| /async | Создает сигнатуры как синхронных, так и асинхронных методов. По умолчанию: создает только сигнатуры синхронных методов. Сокращенная форма: /a |
| /collectionType:<type> | Указывает тип коллекции списка для клиента WCF. Значение по умолчанию: тип коллекции — System.Array. Сокращенная форма: /ct |
| /config:<configFile> | Задает имя файла для создаваемого файла конфигурации. По умолчанию: output.config |
| /dataContractOnly | Создает код только для типов контрактов данных. Типы контрактов службы не созданы. Для этого параметра следует задавать только локальные файлы метаданных. Сокращенная форма: /dconly |
| /enableDataBinding | Реализует интерфейс INotifyPropertyChanged для всех типов контрактов данных для обеспечения привязки данных. Сокращенная форма: /edb |
| /excludeType:<type> | Задает полное имя типа или имя типа с указанием на сборку, который необходимо исключить из ссылочных типов контракта. При использовании этого переключателя вместе с /r из отдельных библиотек DLL создается ссылка на полное имя класса XSD.Сокращенная форма: /et |
| /importXmlTypes | Служит для настройки сериализатора контракта данных для импортирования типов, отличных от типов контракта данных, в качестве типов IXmlSerializable. |
| /internal | Создает классы, помеченные как внутренние. По умолчанию: создает только открытые классы. Сокращенная форма: /i |
| /language:<language> | Задает язык программирования, используемый для создания кода. Необходимо указать имя языка, зарегистрированное в файле Machine.config, или полное имя класса, наследуемого от CodeDomProvider. Значения: c#, cs, csharp, vb, visualbasic, c++, cpp По умолчанию: csharp Краткая форма: /l |
| /mergeConfig | Объединяет созданную конфигурацию с существующим файлом (вместо его перезаписи). |
| /messageContract | Создает типы контрактов сообщений. Сокращенная форма: /mc |
| /namespace:<string,string> | Задает сопоставление атрибута targetNamespace WSDL или схемы XML пространству имен среды CLR. Использование "*" для целевого пространстваNamespace сопоставляет все пространства targetNamespace без явного сопоставления с этим пространством имен CLR. Чтобы убедиться, что имя контракта сообщения не конфликтует с именем операции, необходимо дополнить ссылку на тип двойными двоеточиями ( ::) или задать уникальные имена.По умолчанию: для контрактов данных выводится из целевого пространства имен документа схемы. Для всех остальных создаваемых типов используется пространство имен по умолчанию. Короткая форма. /nПримечание. При создании типов для использования с XmlSerializer поддерживается только одно сопоставление пространства имен. Все созданные типы будут находиться в пространстве имен по умолчанию или пространстве имен, заданном "*". |
| /noConfig | Запрещает создавать файлы конфигурации. |
| /noStdLib | Запрещает ссылаться на стандартные библиотеки. По умолчанию: создаются ссылки на файлы Mscorlib.dll и System.servicemodel.dll. |
| /out:<file> | Задает имя файла созданного кода. По умолчанию: наследуется от имени определения WSDL, имени службы WSDL или целевого пространства имен одной из схем. Краткая форма: /o |
| /reference:<file path> | Ссылается на типы в заданной сборке. При создании клиентов необходимо использовать этот параметр для задания сборок, которые могут содержать типы, представляющие импортируемые метаданные. С помощью этого переключателя невозможно задать контракты сообщений и типы XmlSerializer. При ссылке на DateTimeOffset вместо создания нового типа используется этот тип. Если приложение записывается с помощью платформа .NET Framework 3.5, SvcUtil.exe автоматически ссылаетсяDateTimeOffset. Сокращенная форма: /r |
| /serializable | Создает классы, помеченные сериализуемым атрибутом. Сокращенная форма: /s |
| /serviceContract | Сформировать код только для контрактов службы. Клиентский класс и конфигурация создаваться не будут Сокращенная форма: /sc |
| /serializer:Auto | Автоматически выберите сериализатор. Это пытается использовать сериализатор контракта данных и использует xmlSerializer в случае сбоя. Сокращенная форма: /ser |
| /serializer:DataContractSerializer | Создает типы данных, использующие сериализатор контракта данных для сериализации и десериализации. Сокращенная форма: /ser:DataContractSerializer |
| /serializer:XmlSerializer | Формирует типы данных, использующих для сериализации и десериализации сериализатор XmlSerializer. Сокращенная форма: /ser:XmlSerializer |
| /targetClientVersion | Укажите, какая версия платформа .NET Framework предназначено для приложения. Допустимые значения — Version30 и Version35. Значение по умолчанию — Version30.Сокращенная форма: /tcvVersion30: используйте, /tcv:Version30 если вы создаете код для клиентов, использующих WinFX.Version35: используйте, /tcv:Version35 если вы создаете код для клиентов, использующих платформа .NET Framework 3.5. При использовании /tcv:Version35 с переключателем /async создаются асинхронные методы как на основе событий, так и на основе обратных вызовов/делегатов. Кроме того, включена поддержка наборов данных с поддержкой LINQ и DateTimeOffset. |
| /wrapped | Определяет, используется ли особый подход для документов со стилем document-literal с параметрами в оболочке. Используйте параметр /оболочки с помощью средства служебной программы метаданных модели (Svcutil.exe), чтобы указать обычный регистр. |
Примечание.
Если привязка службы является одной из системных привязок (см . предоставленные системой привязки), а ProtectionLevel свойство имеет значение None или SignSvcutil создает файл конфигурации с помощью <пользовательского элементаBinding> вместо ожидаемого системного элемента. Например, если служба использует элемент <wsHttpBinding>, свойству ProtectionLevel которого задано значение Sign, раздел привязок создаваемой конфигурации будет содержать <customBinding> вместо <wsHttpBinding>. Дополнительные сведения об уровне защиты см. в разделе "Общие сведения о уровне защиты".
Экспорт метаданных
При помощи Svcutil.exe можно экспортировать метаданные для служб, контрактов и типов данных в скомпилированных сборках. Чтобы экспортировать метаданные для службы, необходимо использовать параметр /serviceName для задания службы, которую следует экспортировать. Для экспорта всех типов контрактов данных внутри сборки используется параметр /dataContractOnly. По умолчанию метаданные экспортируются для всех контрактов служб во входных сборках.
svcutil.exe [/t:metadata] [/serviceName:<serviceConfigName>] [/dataContractOnly] <assemblyPath>*
| Аргумент | Description |
|---|---|
assemblyPath |
Задает путь к сборке, которая содержит службы, контракты или типы контрактов данных для экспорта. Для предоставления нескольких файлов в качестве входных данных можно использовать стандартные подстановочные знаки командной строки. |
| Вариант | Описание |
|---|---|
| /serviceName:<serviceConfigName> | Задает имя конфигурации службы для экспорта. При использовании этого параметра в качестве входных данных необходимо передать исполняемую сборку со связанным файлом конфигурации. Svcutil.exe осуществляет поиск всех связанных файлов конфигурации для конфигурации службы. Если файлы конфигурации содержат какие-либо типы расширения, сборки, в состав которых входят эти типы, должны находиться в глобальном кэше сборок или явно предоставляться с использованием параметра /reference. |
| /reference:<file path> | Добавляет заданную сборку в набор сборок, используемых для разрешения ссылок на типы. При экспорте или проверке службы, использующей сторонние расширения (поведения, привязки и элементы привязок), которые зарегистрированы в конфигурации, этот параметр необходимо использовать для определения местоположения сборок расширения, которые находятся не в глобальном кэше сборок. Сокращенная форма: /r |
| /dataContractOnly | Работает только с типами контрактов данных. Контракты служб не обрабатываются. Для этого параметра следует задавать только локальные файлы метаданных. Сокращенная форма: /dconly |
| /excludeType:<type> | Задает полное имя типа или имя типа с указанием на сборку, который необходимо исключить из экспорта. Этот параметр можно использовать при экспорте метаданных для службы или набора контрактов службы для запрещения экспорта этих типов. Данный параметр не может использоваться одновременно с параметром /dconly.Если в одной сборке содержится несколько служб, каждая из которых использует отдельные классы с одним и тем же именем XSD, для данного переключателя необходимо задать имя службы вместо имени класса XSD. XSD или типы контрактов данных не поддерживаются. Сокращенная форма: /et |
Проверка службы
Проверка проводится для выявления ошибок в реализациях службы без размещения службы. Для указания службы для проверки используется параметр /serviceName.
svcutil.exe /validate /serviceName:<serviceConfigName> <assemblyPath>*
| Аргумент | Description |
|---|---|
assemblyPath |
Задает путь к сборке, содержащей типы службы для проверки. Сборка должна содержать связанный файл конфигурации для предоставления конфигурации службы. Для предоставления нескольких сборок можно использовать стандартные подстановочные знаки командной строки. |
| Вариант | Описание |
|---|---|
| /validate | Проверяет реализацию службы, заданную параметром /serviceName. При использовании этого параметра в качестве входных данных необходимо передать исполняемую сборку со связанным файлом конфигурации.Сокращенная форма: /v |
| /serviceName:<serviceConfigName> | Задает имя конфигурации службы для проверки. Svcutil.exe осуществляет поиск всех связанных файлов конфигурации всех входных сборок для конфигурации службы. Если файлы конфигурации содержат какие-либо типы расширения, сборки, в состав которых входят эти типы, должны находиться в глобальном кэше сборок или явно предоставляться с использованием параметра /reference. |
| /reference:<file path> | Добавляет заданную сборку в набор сборок, используемых для разрешения ссылок на типы. При экспорте или проверке службы, использующей сторонние расширения (поведения, привязки и элементы привязок), которые зарегистрированы в конфигурации, этот параметр необходимо использовать для определения местоположения сборок расширения, которые находятся не в глобальном кэше сборок. Сокращенная форма: /r |
| /dataContractOnly | Работает только с типами контрактов данных. Контракты служб не обрабатываются. Для этого параметра следует задавать только локальные файлы метаданных. Сокращенная форма: /dconly |
| /excludeType:<type> | Задает полное имя типа или имя типа с указанием на сборку, который необходимо исключить из проверки. Сокращенная форма: /et |
Загрузка метаданных
Средство Svcutil.exe можно использовать для загрузки метаданных из работающих служб и сохранения этих метаданных в локальных файлах. Для загрузки метаданных необходимо задать параметр /t:metadata. В противном случае создается код клиента. Для URL-схем HTTP и HTTPS средство Svcutil.exe предпринимает попытку извлечь метаданные с помощью WS-Metadata Exchange и DISCO. Для всех остальных URL-схем Svcutil.exe использует только WS-Metadata Exchange.
Svcutil одновременно направляет следующие запросы метаданных для извлечения метаданных.
Запрос MEX (WS-Transfer) на предоставленный адрес
Запрос MEX на предоставленный адрес с присоединенным /mex
Запрос DISCO (с использованием протокола DiscoveryClientProtocol из ASMX) на предоставленный адрес.
По умолчанию для осуществления запросов MEX Svcutil.exe использует привязки, определенные в классе MetadataExchangeBindings. Для настройки привязки, используемой для WS-Metadata Exchange, необходимо определить в конфигурации, использующей контракт IMetadataExchange, конечную точку клиента. Ее можно определить в файле конфигурации средства Svcutil.exe или в другом файле конфигурации, заданном с помощью параметра /svcutilConfig.
svcutil.exe /t:metadata <url>* | <epr>
| Аргумент | Description |
|---|---|
url |
URL-адрес конечной точки службы, предоставляющей метаданные, или документа метаданных, размещенного в сети. |
epr |
Путь к файлу XML, который содержит ссылку на конечную точку службы WS-Addressing EndpointReference, которая поддерживает WS-Metadata Exchange. |
Создание типа XmlSerializer
Службы и клиентские приложения, использующие типы данных, сериализуемых при помощи сериализатора XmlSerializer, создают и компилируют код сериализации для этих типов данных во время выполнения, что может привести к снижению производительности при запуске.
Примечание.
Предварительно созданный код сериализации может использоваться только в клиентских приложениях, но не в службах.
Svcutil.exe может улучшить производительность при запуске этих приложений путем создания необходимого кода сериализации C# из компилированных сборок для приложения. Дополнительные сведения см. в разделе "Практическое руководство. Улучшение времени запуска клиентских приложений WCF с помощью xmlSerializer".
Примечание.
Svcutil.exe создает код только для типов, которые используются контрактами служб, найденными во входных сборках.
svcutil.exe /t:xmlSerializer <assemblyPath>*
| Аргумент | Description |
|---|---|
assemblyPath |
Задает путь к сборке, содержащей типы контрактов служб. Типы сериализации создаются для всех сериализуемых в формат Xml типов в каждом контракте. |
| Вариант | Описание |
|---|---|
| /reference:<file path> | Добавляет заданную сборку в набор сборок, используемых для разрешения ссылок на типы. Сокращенная форма: /r |
| /excludeType:<type> | Задает полное имя типа или имя типа с указанием на сборку, который необходимо исключить из экспорта или проверки. Сокращенная форма: /et |
| /out:<file> | Задает имя файла созданного кода. При передаче в средство нескольких сборок в качестве входных данных этот параметр игнорируется. По умолчанию: наследуется от имени сборки. Сокращенная форма: /o |
| /UseSerializerForFaults | Указывает, что вместо сериализатора по умолчанию XmlSerializer для чтения и записи ошибок следует использовать сериализатор DataContractSerializer. |
Примеры
Следующая команда используется для создания кода клиента из работающей службы или документов метаданных в сети.
svcutil http://service/metadataEndpoint
Следующая команда используется для создания кода клиента из локальных документов метаданных.
svcutil *.wsdl *.xsd /language:C#
Следующая команда используется для создания типов контрактов данных в Visual Basic из локальных документов схемы.
svcutil /dconly *.xsd /language:VB
Следующая команда используется для загрузки документов метаданных из работающих служб.
svcutil /t:metadata http://service/metadataEndpoint
Следующая команда используется для создания документов метаданных для контрактов служб и связанных типов в сборке.
svcutil myAssembly.dll
Следующая команда используется для создания документов метаданных для службы и всех связанных контрактов службы и типов данных в сборке.
svcutil myServiceHost.exe /serviceName:myServiceName
Следующая команда используется для создания документов метаданных для типов данных в сборке.
svcutil myServiceHost.exe /dconly
С помощью следующей команды проверяется размещение службы.
svcutil /validate /serviceName:myServiceName myServiceHost.exe
Следующая команда создает типы сериализации для типов XmlSerializer, используемых любыми контрактами служб в сборке.
svcutil /t:xmlserializer myContractLibrary.exe
Максимальная квота на количество символов в таблице имен.
Когда программа svcutil используется для создания метаданных для службы, может выводиться следующее сообщение:
Ошибка. Невозможно получить метаданные из http://localhost:8000/somesservice/mex максимальной квоты числа символов имен (16384) при чтении XML-данных. Таблица имен является структурой данных, в которой хранятся строки, обнаруженные при обработке данных XML. Триггером этой квоты могут служить длинные XML-документы с неповторяющимися именами элементов, именами атрибутов и значениями атрибутов. Эту квоту можно увеличить, изменив свойство MaxNameTableCharCount объекта XmlDictionaryReaderQuotas, используемого при создании средства чтения XML.
Эта ошибка может вызываться службой, которая возвращает крупный WSDL-файл на запрос метаданных службы. Проблема состоит в превышении квоты символов для программы svcutil.exe. Это значение задается, чтобы предотвратить атаки типа «отказ в обслуживании». Можно увеличить квоту, указав следующий файл конфигурации для svcutil.
В следующем файле конфигурации показано, как задать квоты модуля чтения для svcutil.
<?xml version="1.0" encoding="utf-8"?>
<configuration>
<system.serviceModel>
<bindings>
<customBinding>
<binding name="MyBinding">
<textMessageEncoding>
<readerQuotas maxDepth="2147483647" maxStringContentLength="2147483647"
maxArrayLength="2147483647" maxBytesPerRead="2147483647" maxNameTableCharCount="2147483647" />
</textMessageEncoding>
<httpTransport maxReceivedMessageSize="2147483647" maxBufferSize="2147483647" />
</binding>
</customBinding>
</bindings>
<client>
<endpoint binding="customBinding" bindingConfiguration="MyBinding"
contract="IMetadataExchange"
name="http" />
</client>
</system.serviceModel>
</configuration>
Создайте новый файл с именем svcutil.exe.config и скопируйте в него пример XML-кода. Затем поместите файл в один каталог с файлом svcutil.exe. При следующем запуске программа svcutil.exe будет использовать новые параметры.
Проблемы безопасности
Для защиты папки установки Svcutil.exe, файла конфигурации Svcutil.config и файлов, на которые указывает /svcutilConfig, необходимо использовать соответствующий список управления доступом (ACL). Это позволит предотвратить регистрацию и выполнение вредоносных расширений.
Кроме того, чтобы свести к минимуму вероятность компрометации безопасности, не следует добавлять ненадежные расширения, чтобы быть частью системы или использовать ненадежные поставщики кода с Svcutil.exe.
Наконец, не стоит использовать это средство на промежуточном уровне приложения, так как это может стать причиной отказа в обслуживании текущего процесса.