Служебное средство ServiceModel Metadata Utility Tool (Svcutil.exe)

Средство служебной программы метаданных ServiceModel используется для создания кода модели службы из документов метаданных и документов метаданных из кода модели службы.

SvcUtil.exe

средство служебной программы метаданных ServiceModel можно найти в расположении установки Windows SDK, в частности %ProgramFiles%\Microsoft sdks \ 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: < Каталог> Каталог, в котором создаются файлы.

По умолчанию: текущий каталог.

Краткая форма: /d
/help Отображает синтаксис команд и параметров для средства.

Краткая форма: /?
/nologo Подавляет вывод логотипа и сообщения об авторском праве.
/Свкутилконфиг: < configFile> Задает пользовательский файл конфигурации, который следует использовать вместо файла App.config. С его помощью можно регистрировать расширения system.serviceModel, не изменяя файл конфигурации средства.
/target: < тип вывода> Задает выходные объекты, которые должны быть созданы с помощью средства.

Допустимыми значениями являются код, метаданные или xmlSerializer.

Краткая форма: /t

Создание кода

Svcutil.exe может создавать код для контрактов службы, клиентов и типы данных из документов метаданных. Документы метаданных могут находиться в устойчивом хранилище или извлекаться в оперативном режиме. Извлечение в оперативном режиме происходит либо по протоколу WS-Metadata Exchange, либо по протоколу DISCO (дополнительные сведения см. в разделе "Загрузка метаданных").

Можно использовать средство SvcUtil.exe для создания контрактов служб и данных на основе предопределенного документа WSDL. Укажите переключатель/erviceContract и URL-адрес, откуда можно загрузить документ WSDL, или расположение файла, где его можно найти. Это создает контракты служб и данных, определенные в документе WSDL, которые затем можно использовать для реализации службы жалоб. Дополнительные сведения см. в разделе как получить метаданные и реализовать соответствующую службу.

Для службы с конечной точкой BasicHttpContextBinding Svcutil.exe создает BasicHttpBinding с атрибутом, для 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,. всполици или. всмекс).

Svcutil следит за ходом импортирования и включает удаленный URL-адрес для метаданных, когда указано пользователем. Однако если файлы метаданных необходимо обработать в локальной файловой системе, все файлы следует задавать в этом аргументе. Таким образом, Svcutil можно использовать в среде построения, где отсутствуют сетевые зависимости. Для этого аргумента можно использовать подстановочные знаки (например, XSD, WSDL).
url URL-адрес конечной точки службы, предоставляющей метаданные, или документа метаданных, размещенного в сети. Дополнительные сведения об извлечении этих документов см. в разделе "Загрузка метаданных".
Параметр Описание
/async Создает сигнатуры как синхронных, так и асинхронных методов.

По умолчанию: создает только сигнатуры синхронных методов.

Сокращенная форма: /a
/Коллектионтипе: < тип> Указывает тип коллекции списка для клиента WCF.

По умолчанию: тип коллекции — System. Array.

Сокращенная форма: /ct
/config: < configFile> Задает имя файла для создаваемого файла конфигурации.

По умолчанию: output.config
/dataContractOnly Создает код только для типов контрактов данных. Типы контрактов службы не созданы.

Для этого параметра следует задавать только локальные файлы метаданных.

Сокращенная форма: /dconly
/enableDataBinding Реализует интерфейс INotifyPropertyChanged для всех типов контрактов данных для обеспечения привязки данных.

Сокращенная форма: /edb
/Ексклудетипе: < тип> Задает полное имя типа или имя типа с указанием на сборку, который необходимо исключить из ссылочных типов контракта.

При использовании этого переключателя вместе с /r из отдельных библиотек DLL создается ссылка на полное имя класса XSD.

Сокращенная форма: /et
/importXmlTypes Служит для настройки сериализатора контракта данных для импортирования типов, отличных от типов контракта данных, в качестве типов IXmlSerializable.
/internal Создает классы, помеченные как внутренние. По умолчанию: создает только открытые классы.

Сокращенная форма: /i
/Language: < язык> Задает язык программирования, используемый для создания кода. Необходимо указать либо имя языка, зарегистрированное в файле Machine.config, либо полное имя класса, наследующего от CodeDomProvider .

Значения: c#, cs, csharp, vb, visualbasic, c++, cpp

По умолчанию: csharp

Краткая форма: /l
/mergeConfig Объединяет созданную конфигурацию с существующим файлом (вместо его перезаписи).
/messageContract Создает типы контрактов сообщений.

Сокращенная форма: /mc
/namespace: < строка, строка> Задает сопоставление атрибута targetNamespace WSDL или схемы XML пространству имен среды CLR. Использование подстановочного знака '*' для атрибута targetNamespace позволяет сопоставить все атрибуты targetNamespace без явного сопоставления пространству имен среды CLR.

Чтобы убедиться, что имя контракта сообщения не конфликтует с именем операции, необходимо дополнить ссылку на тип двойными двоеточиями (::) или задать уникальные имена.

По умолчанию: для контрактов данных выводится из целевого пространства имен документа схемы. Для всех остальных создаваемых типов используется пространство имен по умолчанию.

Краткая форма: /n/n . при создании типов для использования с XmlSerializer поддерживается только одно сопоставление пространства имен. Все созданные типы будут находиться либо в пространстве имен по умолчанию, либо в пространстве имен, указанном параметром "*".
/noConfig Запрещает создавать файлы конфигурации.
/noStdLib Запрещает ссылаться на стандартные библиотеки.

По умолчанию: создаются ссылки на файлы Mscorlib.dll и System.servicemodel.dll.
/out: < файл> Задает имя файла созданного кода.

По умолчанию: наследуется от имени определения WSDL, имени службы WSDL или целевого пространства имен одной из схем.

Краткая форма: /o
/Reference: < путь к файлу> Ссылается на типы в заданной сборке. При создании клиентов необходимо использовать этот параметр для задания сборок, которые могут содержать типы, представляющие импортируемые метаданные.

С помощью этого переключателя невозможно задать контракты сообщений и типы 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.

Сокращенная форма: /tcv

Version30: Используется /tcv:Version30 при создании кода для клиентов, использующих WinFX.

Version35: используйте /tcv:Version35 при создании кода для клиентов, использующих платформа .NET Framework 3,5. При использовании /tcv:Version35 с переключателем /async создаются асинхронные методы как на основе событий, так и на основе обратных вызовов/делегатов. Кроме того, включена поддержка наборов данных с поддержкой LINQ и DateTimeOffset.
/wrapped Определяет, используется ли особый подход для документов со стилем document-literal с параметрами в оболочке. Используйте параметр /враппед со средством служебной программы метаданных модели службы (Svcutil.exe) для указания обычного регистра.

Примечание

Если привязка службы является одной из предоставляемых системой привязок (см. раздел привязки, предоставляемые системой), а свойство имеет значение None или Sign , то Svcutil создает файл конфигурации с помощью None вместо ожидаемого системного элемента. Например, если служба использует элемент <wsHttpBinding>, свойству ProtectionLevel которого задано значение Sign, раздел привязок создаваемой конфигурации будет содержать <customBinding> вместо <wsHttpBinding>. Дополнительные сведения об уровне защиты см. в разделе Основные сведения о уровне защиты.

Экспорт метаданных

При помощи Svcutil.exe можно экспортировать метаданные для служб, контрактов и типов данных в скомпилированных сборках. Чтобы экспортировать метаданные для службы, необходимо использовать параметр /serviceName для задания службы, которую следует экспортировать. Для экспорта всех типов контрактов данных внутри сборки используется параметр /dataContractOnly. По умолчанию метаданные экспортируются для всех контрактов служб во входных сборках.

svcutil.exe [/t:metadata] [/serviceName:<serviceConfigName>] [/dataContractOnly] <assemblyPath>*

Аргумент Описание
assemblyPath Задает путь к сборке, которая содержит службы, контракты или типы контрактов данных для экспорта. Для предоставления нескольких файлов в качестве входных данных можно использовать стандартные подстановочные знаки командной строки.
Параметр Описание
/Сервиценаме: < сервицеконфигнаме> Задает имя конфигурации службы для экспорта. При использовании этого параметра в качестве входных данных необходимо передать исполняемую сборку со связанным файлом конфигурации. Svcutil.exe осуществляет поиск всех связанных файлов конфигурации для конфигурации службы. Если файлы конфигурации содержат какие-либо типы расширения, сборки, в состав которых входят эти типы, должны находиться в глобальном кэше сборок или явно предоставляться с использованием параметра /reference.
/Reference: < путь к файлу> Добавляет заданную сборку в набор сборок, используемых для разрешения ссылок на типы. При экспорте или проверке службы, использующей сторонние расширения (поведения, привязки и элементы привязок), которые зарегистрированы в конфигурации, этот параметр необходимо использовать для определения местоположения сборок расширения, которые находятся не в глобальном кэше сборок.

Сокращенная форма: /r
/dataContractOnly Работает только с типами контрактов данных. Контракты служб не обрабатываются.

Для этого параметра следует задавать только локальные файлы метаданных.

Сокращенная форма: /dconly
/Ексклудетипе: < тип> Задает полное имя типа или имя типа с указанием на сборку, который необходимо исключить из экспорта. Этот параметр можно использовать при экспорте метаданных для службы или набора контрактов службы для запрещения экспорта этих типов. Данный параметр не может использоваться одновременно с параметром /dconly.

Если в одной сборке содержится несколько служб, каждая из которых использует отдельные классы с одним и тем же именем XSD, для данного переключателя необходимо задать имя службы вместо имени класса XSD.

XSD или типы контрактов данных не поддерживаются.

Сокращенная форма: /et

Проверка службы

Проверка проводится для выявления ошибок в реализациях службы без размещения службы. Для указания службы для проверки используется параметр /serviceName.

svcutil.exe /validate /serviceName:<serviceConfigName> <assemblyPath>*

Аргумент Описание
assemblyPath Задает путь к сборке, содержащей типы службы для проверки. Сборка должна содержать связанный файл конфигурации для предоставления конфигурации службы. Для предоставления нескольких сборок можно использовать стандартные подстановочные знаки командной строки.
Параметр Описание
/validate Проверяет реализацию службы, заданную параметром /serviceName. При использовании этого параметра в качестве входных данных необходимо передать исполняемую сборку со связанным файлом конфигурации.

Сокращенная форма: /v
/Сервиценаме: < сервицеконфигнаме> Задает имя конфигурации службы для проверки. Svcutil.exe осуществляет поиск всех связанных файлов конфигурации всех входных сборок для конфигурации службы. Если файлы конфигурации содержат какие-либо типы расширения, сборки, в состав которых входят эти типы, должны находиться в глобальном кэше сборок или явно предоставляться с использованием параметра /reference.
/Reference: < путь к файлу> Добавляет заданную сборку в набор сборок, используемых для разрешения ссылок на типы. При экспорте или проверке службы, использующей сторонние расширения (поведения, привязки и элементы привязок), которые зарегистрированы в конфигурации, этот параметр необходимо использовать для определения местоположения сборок расширения, которые находятся не в глобальном кэше сборок.

Сокращенная форма: /r
/dataContractOnly Работает только с типами контрактов данных. Контракты служб не обрабатываются.

Для этого параметра следует задавать только локальные файлы метаданных.

Сокращенная форма: /dconly
/Ексклудетипе: < тип> Задает полное имя типа или имя типа с указанием на сборку, который необходимо исключить из проверки.

Сокращенная форма: /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
/Ексклудетипе: < тип> Задает полное имя типа или имя типа с указанием на сборку, который необходимо исключить из экспорта или проверки.

Сокращенная форма: /et
/out: < файл> Задает имя файла созданного кода. При передаче в средство нескольких сборок в качестве входных данных этот параметр игнорируется.

По умолчанию: наследуется от имени сборки.

Сокращенная форма: /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 квоты максимального числа символов NameTable (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.

Наконец, не стоит использовать это средство на промежуточном уровне приложения, так как это может стать причиной отказа в обслуживании текущего процесса.

См. также раздел