Служебное средство ServiceModel Metadata Utility Tool (Svcutil.exe)
Служебное средство ServiceModel Metadata Utility Tool используется для создания кода модели служб из документов метаданных и документов метаданных из кода модели служб.
SvcUtil.exe
Служебное средство ServiceModel Metadata Utility Tool можно найти в папке установки Windows SDK по адресу C:\Program Files\Microsoft SDKs\Windows\v6.0\Bin
Функциональные возможности
В следующей таблице приведены сводные данные о различных функциях, предоставляемых этим средством, а в соответствующем разделе описывается использование этих функций.
Задача | Раздел |
---|---|
Создает код из работающих служб или документов статических метаданных. |
|
Экспортирует документы метаданных из скомпилированного кода. |
Как использовать программу Svcutil.exe для экспорта метаданных из скомпилированного кода службы |
Проверяет скомпилированный код службы. |
Как использовать программу Svcutil.exe для проверки скомпилированного кода службы |
Загружает документы метаданных из работающих служб. |
Как использовать Svcutil.exe для загрузки документов метаданных |
Создает код сериализации. |
Как сократить время запуска клиентских приложений WCF с использованием XmlSerializer |
Внимание! |
---|
Svcutil перезаписывает существующие файлы на диск, если предоставленные в качестве параметров имена идентичны. К этим файлам относятся файлы кода, конфигурации или метаданных. Чтобы отключить эту функцию при создании файлов кода и конфигурации, используйте переключатель /mergeConfig. Кроме того, переключатели /r и /ct для ссылок на типы предназначены для создания контрактов данных. Эти переключатели не работают при использовании XmlSerializer. |
Время ожидания
Время ожидания этого средства при извлечении метаданных составляет 5 минут. Это значение времени ожидания действительно только при извлечении метаданных по сети. Указанное время ожидания не применимо к обработке этих метаданных.
Настройка для различных версий
Программа не поддерживает настройку для различных версий. Если нужно создать артефакт .NET 4 в svcutil.exe, необходимо использовать версию svcutil.exe из пакета SDK платформы .NET 4. Чтобы создать артефакт .NET 3.5, используйте исполняемый файл из пакета SDK платформы .NET 3.5.
Доступ к документам WSDL
При использовании Svcutil для получения доступа к документу WSDL, который содержит ссылку на службу маркеров безопасности (STS), Svcutil осуществляет вызов службы маркеров безопасности по протоколу WS-MetadataExchange. Однако служба может предоставлять документы WSDL с помощью WS-MetadataExchange или запроса HTTP GET. Следовательно, если служба STS предоставила документ WSDL только с помощью запроса HTTP GET, произойдет сбой клиента, созданного в Платформа .NET Framework 3.0. Если клиенты созданы в .NET Framework 3.5, для получения STS WSDL Svcutil попытается использовать и WS-MetadataExchange, и HTTP GET.
Использование программы SvcUtil.exe
Типичные способы использования
В следующей таблице перечислены некоторые наиболее часто используемые параметры этого средства.
Параметр | Описание |
---|---|
/directory:<каталог> |
Каталог, в котором создаются файлы. По умолчанию: текущий каталог. Сокращенная форма: /d |
/help |
Отображает синтаксис команд и параметров для средства. Сокращенная форма: /? |
/nologo |
Подавляет вывод логотипа и сообщения об авторском праве. |
/svcutilConfig:<файл_конфигурации> |
Задает пользовательский файл конфигурации, который следует использовать вместо файла App.config. С его помощью можно регистрировать расширения system.serviceModel, не изменяя файл конфигурации средства. |
/target:<выходной тип> |
Задает выходные объекты, которые должны быть созданы с помощью средства. Допустимыми значениями являются код, метаданные или xmlSerializer. Сокращенная форма: /t |
Создание кода
Svcutil.exe может создавать код для контрактов службы, клиентов и типы данных из документов метаданных. Документы метаданных могут находиться в устойчивом хранилище или извлекаться в оперативном режиме. Извлечение в оперативном режиме происходит либо по протоколу WS-Metadata Exchange, либо по протоколу DISCO (дополнительные сведения см. в разделе "Загрузка метаданных").
Вместо этого для службы с конечной точкой BasicHttpContextbinding Svcutil.exe создает привязку BasicHttpBinding с атрибутом allowCookies с заданным значением true. Файлы cookie используются для создания контекста на сервере. Если необходимо управлять контекстом в клиенте при использовании службой файлов cookie, можно вручную изменить настройки для использования контекстной привязки.
Внимание! |
---|
Svcutil.exe создает клиент на основе файла WSDL или файла политики, полученного от службы. Имя участника-пользователя (UPN) создается добавлением к имени пользователя символа "@" и полного доменного имени (FQDN). Однако для пользователей, зарегистрированных в Active Directory, этот формат не является допустимым, и созданное средством имя участника-пользователя вызывает сбой проверки подлинности Kerberos с выдачей сообщения об ошибке "Сбой попытки входа в систему". Чтобы устранить эту проблему, необходимо вручную исправить файл клиента, созданный средством. |
svcutil.exe [/t:code] <metadataDocumentPath>* | <url>* | <epr>
Аргумент | Описание |
---|---|
epr |
Путь к файлу XML, который содержит ссылку на конечную точку службы WS-Addressing EndpointReference, которая поддерживает WS-Metadata Exchange. Дополнительные сведения см. в разделе "Загрузка метаданных". |
metadataDocumentPath |
Путь к документу метаданных (wsdl или xsd), который содержит контракт для импортирования в код (.wsdl, .xsd, .wspolicy или .wsmex). Svcutil следит за ходом импортирования и включает удаленный URL-адрес для метаданных, когда указано пользователем. Однако если файлы метаданных необходимо обработать в локальной файловой системе, все файлы следует задавать в этом аргументе. Таким образом, Svcutil можно использовать в среде построения, где отсутствуют сетевые зависимости. Для этого аргумента можно использовать подстановочные знаки (например, XSD, WSDL). |
url |
URL-адрес конечной точки службы, предоставляющей метаданные, или документа метаданных, размещенного в сети. Дополнительные сведения об извлечении этих документов см. в разделе "Загрузка метаданных". |
Параметр | Описание |
---|---|
/async |
Создает сигнатуры как синхронных, так и асинхронных методов. По умолчанию: создает только сигнатуры синхронных методов. Сокращенная форма: /a |
/collectionType:<тип> |
Задает полное имя типа или имя типа с указанием на сборку, который должен использоваться в качестве типа данных коллекции, если код создается из схем. Сокращенная форма: /ct |
/config:<файл_конфигурации> |
Задает имя файла для создаваемого файла конфигурации. По умолчанию: output.config |
/dataContractOnly |
Создает код только для типов контрактов данных. Типы контрактов службы не созданы. Для этого параметра следует задавать только локальные файлы метаданных. Сокращенная форма: /dconly |
/enableDataBinding |
Реализует интерфейс INotifyPropertyChanged для всех типов контрактов данных для обеспечения привязки данных. Сокращенная форма: /edb |
/excludeType:<тип> |
Задает полное имя типа или имя типа с указанием на сборку, который необходимо исключить из ссылочных типов контракта. При использовании этого переключателя вместе с /r из отдельных библиотек DLL создается ссылка на полное имя класса XSD. Сокращенная форма: /et |
/importXmlTypes |
Служит для настройки сериализатора контракта данных для импортирования типов, отличных от типов контракта данных, в качестве типов IXmlSerializable. |
/internal |
Создает классы, помеченные как внутренние. По умолчанию: создает только открытые классы. Сокращенная форма: /i |
/language:<язык> |
Задает язык программирования, используемый для создания кода. Необходимо указать либо имя языка, зарегистрированное в файле Machine.config, либо полное имя класса, наследуемого от CodeDomProvider. Значения: c#, cs, csharp, vb, visualbasic, c++, cpp По умолчанию: csharp Сокращенная форма: /l
Примечание
Переключатель поддерживает только С++ для поставщика кода, который поставляется с Visual Studio 2005 SP1.
|
/mergeConfig |
Объединяет созданную конфигурацию с существующим файлом (вместо перезаписи существующего файла). |
/messageContract |
Создает типы контрактов сообщений. Сокращенная форма: /mc |
/namespace:<string,string> |
Задает сопоставление атрибута targetNamespace WSDL или схемы XML пространству имен среды CLR. Использование подстановочного знака '*' для атрибута targetNamespace позволяет сопоставить все атрибуты targetNamespace без явного сопоставления пространству имен среды CLR. Чтобы убедиться, что имя контракта сообщения не конфликтует с именем операции, необходимо дополнить ссылку на тип двойными двоеточиями (::) или задать уникальные имена. По умолчанию: для контрактов данных выводится из целевого пространства имен документа схемы. Для всех остальных создаваемых типов используется пространство имен по умолчанию. Сокращенная форма: /n |
/noConfig |
Запрещает создавать файлы конфигурации. |
/noStdLib |
Запрещает ссылаться на стандартные библиотеки. По умолчанию: создаются ссылки на файлы Mscorlib.dll и System.servicemodel.dll. |
/out:<файл> |
Задает имя файла созданного кода. По умолчанию: наследуется от имени определения WSDL, имени службы WSDL или целевого пространства имен одной из схем. Сокращенная форма: /o |
/serializable |
Создает классы, помеченные сериализуемым атрибутом. Сокращенная форма: /s |
/targetClientVersion |
Указывает, на какую версию .NET Framework нацелено приложение. Допустимые значения: Version30 и Version35. Значением по умолчанию является Version30. Сокращенная форма: /tcv Version30: при создании кода для клиентов, работающих с Платформа .NET Framework 3.0, следует использовать Version35: при создании кода для клиентов, работающих с .NET Framework 3.5, следует использовать |
/reference:<путь к файлу> |
Ссылается на типы в заданной сборке. При создании клиентов необходимо использовать этот параметр для задания сборок, которые могут содержать типы, представляющие импортируемые метаданные. С помощью этого переключателя невозможно задать контракты сообщений и типы XmlSerializer. При ссылке на DateTimeOffset вместо создания нового типа используется этот тип. Если приложение создано с использованием .NET Framework 3.5, SvcUtil.exe автоматически ссылается на DateTimeOffset. Сокращенная форма: /r |
/serializer:Auto |
Автоматически выбирает сериализатор. В данном случае используется сериализатор контракта данных. Если использовать этот сериализатор не удается, используется сериализатор XmlSerializer. Сокращенная форма: /ser:Auto |
/serializer:DataContractSerializer |
Создает типы данных, использующие сериализатор контракта данных для сериализации и десериализации. Сокращенная форма: /ser:DataContractSerializer |
/serializer:XmlSerializer |
Создает типы данных, использующие для сериализации и десериализации сериализатор XmlSerializer. Сокращенная форма: /ser:XmlSerializer |
/wrapped |
Определяет, используется ли особый подход для документов со стилем document-literal с параметрами в оболочке. Используйте ключ /wrapped со средством Служебное средство ServiceModel Metadata Utility Tool (Svcutil.exe), чтобы задать стандартный подход. |
Примечание |
---|
Если привязка службы предоставляется системой (см. раздел Привязки, предоставляемые системой) и свойству ProtectionLevel задано значение None или Sign, Svcutil создает файл конфигурации с использованием элемента <customBinding>, а не элемента, предоставляемого системой. Например, если служба использует элемент <wsHttpBinding>, свойству ProtectionLevel которого задано значение Sign, раздел привязок создаваемой конфигурации будет содержать <customBinding> вместо <wsHttpBinding>. Дополнительную информацию об уровне защиты можно найти в разделе Основные сведения об уровне защиты. |
Экспорт метаданных
При помощи Svcutil.exe можно экспортировать метаданные для служб, контрактов и типов данных в скомпилированных сборках. Чтобы экспортировать метаданные для службы, необходимо использовать параметр /serviceName для задания службы, которую следует экспортировать. Для экспорта всех типов контрактов данных внутри сборки используется параметр /dataContractOnly. По умолчанию метаданные экспортируются для всех контрактов служб во входных сборках.
svcutil.exe [/t:metadata] [/serviceName:<serviceConfigName>] [/dataContractOnly] <assemblyPath>*
Аргумент | Описание |
---|---|
assemblyPath |
Задает путь к сборке, которая содержит службы, контракты или типы контрактов данных для экспорта. Для предоставления нескольких файлов в качестве входных данных можно использовать стандартные подстановочные знаки командной строки. |
Параметр | Описание |
---|---|
/serviceName:<serviceConfigName> |
Задает имя конфигурации службы для экспорта. При использовании этого параметра в качестве входных данных необходимо передать исполняемую сборку со связанным файлом конфигурации. Svcutil.exe осуществляет поиск всех связанных файлов конфигурации для конфигурации службы. Если файлы конфигурации содержат какие-либо типы расширения, сборки, в состав которых входят эти типы, должны находиться в глобальном кэше сборок или явно предоставляться с использованием параметра /reference. |
/reference:<путь к файлу> |
Добавляет заданную сборку в набор сборок, используемых для разрешения ссылок на типы. При экспорте или проверке службы, использующей сторонние расширения (поведения, привязки и элементы привязок), которые зарегистрированы в конфигурации, этот параметр необходимо использовать для определения местоположения сборок расширения, которые находятся не в глобальном кэше сборок. Сокращенная форма: /r |
/dataContractOnly |
Работает только с типами контрактов данных. Контракты служб не обрабатываются. Для этого параметра следует задавать только локальные файлы метаданных. Сокращенная форма: /dconly |
/excludeType:<тип> |
Задает полное имя типа или имя типа с указанием на сборку, который необходимо исключить из экспорта. Этот параметр можно использовать при экспорте метаданных для службы или набора контрактов службы для запрещения экспорта этих типов. Данный параметр не может использоваться одновременно с параметром /dconly. Если в одной сборке содержится несколько служб, каждая из которых использует отдельные классы с одним и тем же именем XSD, для данного переключателя необходимо задать имя службы вместо имени класса XSD. XSD или типы контрактов данных не поддерживаются. Сокращенная форма: /et |
Проверка службы
Проверка проводится для выявления ошибок в реализациях службы без размещения службы. Для указания службы для проверки используется параметр /serviceName.
svcutil.exe /validate /serviceName:<serviceConfigName> <assemblyPath>*
Аргумент | Описание |
---|---|
assemblyPath |
Задает путь к сборке, содержащей типы службы для проверки. Сборка должна содержать связанный файл конфигурации для предоставления конфигурации службы. Для предоставления нескольких сборок можно использовать стандартные подстановочные знаки командной строки. |
Параметр | Описание |
---|---|
/validate |
Проверяет реализацию службы, заданную параметром /serviceName. При использовании этого параметра в качестве входных данных необходимо передать исполняемую сборку со связанным файлом конфигурации. Сокращенная форма: /v |
/serviceName:<serviceConfigName> |
Задает имя конфигурации службы для проверки. Svcutil.exe осуществляет поиск всех связанных файлов конфигурации всех входных сборок для конфигурации службы. Если файлы конфигурации содержат какие-либо типы расширения, сборки, в состав которых входят эти типы, должны находиться в глобальном кэше сборок или явно предоставляться с использованием параметра /reference. |
/reference:<путь к файлу> |
Добавляет заданную сборку в набор сборок, используемых для разрешения ссылок на типы. При экспорте или проверке службы, использующей сторонние расширения (поведения, привязки и элементы привязок), которые зарегистрированы в конфигурации, этот параметр необходимо использовать для определения местоположения сборок расширения, которые находятся не в глобальном кэше сборок. Сокращенная форма: /r |
/dataContractOnly |
Работает только с типами контрактов данных. Контракты служб не обрабатываются. Для этого параметра следует задавать только локальные файлы метаданных. Сокращенная форма: /dconly |
/excludeType:<тип> |
Задает полное имя типа или имя типа с указанием на сборку, который необходимо исключить из проверки. Сокращенная форма: /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>
Аргумент | Описание |
---|---|
url |
URL-адрес конечной точки службы, предоставляющей метаданные, или документа метаданных, размещенного в сети. |
epr |
Путь к файлу XML, который содержит ссылку на конечную точку службы WS-Addressing EndpointReference, которая поддерживает WS-Metadata Exchange. |
Создание типа XmlSerializer
Службы и клиентские приложения, использующие типы данных, сериализуемые с помощью сериализатора XmlSerializer, создают и компилируют код сериализации для этих типов данных во время выполнения, что может привести к снижению производительности при запуске.
Примечание |
---|
Предварительно созданный код сериализации может использоваться только в клиентских приложениях, но не в службах. |
Svcutil.exe может улучшить производительность при запуске этих приложений путем создания необходимого кода сериализации C# из компилированных сборок для приложения. Дополнительные сведения см. в разделе Как сократить время запуска клиентских приложений WCF с использованием XmlSerializer.
Примечание |
---|
Svcutil.exe создает код только для типов, которые используются контрактами служб, найденными во входных сборках. |
svcutil.exe /t:xmlSerializer <assemblyPath>*
Аргумент | Описание |
---|---|
assemblyPath |
Задает путь к сборке, содержащей типы контрактов служб. Типы сериализации создаются для всех сериализуемых в формат Xml типов в каждом контракте. |
Параметр | Описание |
---|---|
/reference:<путь к файлу> |
Добавляет заданную сборку в набор сборок, используемых для разрешения ссылок на типы. Сокращенная форма: /r |
/excludeType:<тип> |
Задает полное имя типа или имя типа с указанием на сборку, который необходимо исключить из экспорта или проверки. Сокращенная форма: /et |
/out:<файл> |
Задает имя файла созданного кода. При передаче в средство нескольких сборок в качестве входных данных этот параметр не учитывается. По умолчанию: наследуется от имени сборки. Сокращенная форма: /o |
/UseSerializerForFaults |
Указывает, что вместо сериализатора по умолчанию DataContractSerializer для чтения и записи ошибок следует использовать сериализатор XmlSerializer. |
Примеры
Следующая команда используется для создания кода клиента из работающей службы или документов метаданных в сети.
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 используется для создания метаданных для службы, может выводиться следующее сообщение:
«Ошибка: не удается получить метаданные из https://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.
Наконец, не стоит использовать это средство на промежуточном уровне приложения, так как это может стать причиной отказа в обслуживании текущего процесса.
См. также
Задачи
Как создать клиент Windows Communication Foundation