Примечание.
Для доступа к этой странице требуется авторизация. Вы можете попробовать войти или изменить каталоги.
Для доступа к этой странице требуется авторизация. Вы можете попробовать изменить каталоги.
Средство служебной программы метаданных 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 |
| /Справка | Отображает синтаксис команд и параметров для средства. Краткая форма: /? |
| /nologo | Подавляет сообщение об авторском праве и баннерное сообщение. |
| /svcutilConfig:<configFile> | Задает пользовательский файл конфигурации, который следует использовать вместо файла App.config. С его помощью можно регистрировать расширения system.serviceModel, не изменяя файл конфигурации средства. |
| Тип результата/target:<output> | Задает выходные объекты, которые должны быть созданы с помощью средства. Допустимыми значениями являются код, метаданные или xmlSerializer. Краткая форма: /t |
Создание кода
Svcutil.exe может создавать код для контрактов службы, клиентов и типы данных из документов метаданных. Документы метаданных могут находиться в устойчивом хранилище или извлекаться в оперативном режиме. Извлечение в оперативном режиме происходит либо по протоколу WS-Metadata Exchange, либо по протоколу DISCO (дополнительные сведения см. в разделе "Загрузка метаданных").
С помощью средства SvcUtil.exe можно создавать контракты служб и данных на основе предопределенного документа WSDL. Используйте переключатель /serviceContract и укажите URL-адрес или расположение файла, откуда можно загрузить документ WSDL. Это создает контракты службы и данных, определенные в документе WSDL, который затем можно использовать для реализации службы жалоб. Дополнительные сведения см. в разделе "Практическое руководство . Получение метаданных и реализация соответствующей службы".
Для службы с конечной точкой BasicHttpContextBinding, Svcutil.exe создает BasicHttpBinding с атрибутом allowCookies установленным в true. Файлы cookie используются для создания контекста на сервере. Если необходимо управлять контекстом в клиенте при использовании службой файлов cookie, можно вручную изменить настройки для использования контекстной привязки.
Внимание
Svcutil.exe создает клиент на основе файла WSDL или файла политики, полученного от службы. Имя пользователя (UPN) создается путём объединения имени пользователя, "@", и полностью квалифицированного доменного имени (FQDN). Однако для пользователей, зарегистрированных в Active Directory, этот формат не является допустимым, и создаваемый средством PDN вызывает сбой проверки подлинности 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:<тип> | Указывает тип коллекции списка для клиента WCF. Значение по умолчанию: тип коллекции — System.Array. Сокращенная форма: /ct |
| /config:<файлНастроек> | Задает имя файла для создаваемого файла конфигурации. По умолчанию: output.config |
| /dataContractOnly | Создает код только для типов контрактов данных. Типы сервисных контрактов не были созданы. Для этого параметра следует задавать только локальные файлы метаданных. Сокращенная форма: /dconly |
| /enableDataBinding | Реализует интерфейс INotifyPropertyChanged для всех типов контрактов данных для обеспечения привязки данных. Сокращенная форма: /edb |
| /excludeType:<тип> | Задает полное имя типа или имя типа с указанием на сборку, который необходимо исключить из ссылочных типов контракта. При совместном использовании этого переключателя с /r из отдельных библиотек DLL используется полное имя класса XSD.Сокращенная форма: /et |
| /importXmlTypes | Служит для настройки сериализатора контракта данных для импортирования типов, отличных от типов контракта данных, в качестве типов IXmlSerializable. |
| /внутренний | Создает классы, помеченные как внутренние. По умолчанию: создает только открытые классы. Сокращенная форма: /i |
| /language:<язык> | Задает язык программирования, используемый для создания кода. Необходимо указать имя языка, зарегистрированное в файле Machine.config, или полное имя класса, наследуемого от CodeDomProvider. Значения: c#, cs, csharp, vb, visualbasic, c++, cpp По умолчанию: csharp Краткая форма: /l |
| /объединитьКонфигурацию | Объединяет созданную конфигурацию с существующим файлом (вместо его перезаписи). |
| /messageContract | Создает типы контрактов сообщений. Сокращенная форма: /mc |
| /namespace:<string,string> | Задает сопоставление из targetNamespace в WSDL или схеме XML к пространству имен CLR. Использование "*" для targetNamespace сопоставляет все пространства targetNamespace без явного сопоставления с пространством имен CLR. Чтобы убедиться, что имя контракта сообщения не конфликтует с именем операции, вы должны либо указать ссылку на тип с помощью ::, либо убедиться, что имена уникальны.Значение по умолчанию: производное от целевого пространства имен документа схемы для контрактов данных. Для всех остальных создаваемых типов используется пространство имен по умолчанию. Короткая форма. /nПримечание. При создании типов для использования с XmlSerializer поддерживается только одно сопоставление пространства имен. Все созданные типы будут находиться в пространстве имен по умолчанию или пространстве имен, заданном "*". |
| /noConfig | Не генерируйте файлы конфигурации. |
| /noStdLib | Не ссылайтесь на стандартные библиотеки. По умолчанию: создаются ссылки на файлы Mscorlib.dll и System.servicemodel.dll. |
| /out:<file> | Задает имя файла созданного кода. По умолчанию: наследуется от имени определения WSDL, имени службы WSDL или целевого пространства имен одной из схем. Краткая форма: /o |
| /reference:<путь к файлу> | Ссылается на типы в заданной сборке. При создании клиентов необходимо использовать этот параметр для задания сборок, которые могут содержать типы, представляющие импортируемые метаданные. С помощью этого переключателя невозможно задать контракты сообщений и типы XmlSerializer. При ссылке на DateTimeOffset вместо создания нового типа используется этот тип. Если приложение написано с использованием .NET Framework 3.5, SvcUtil.exe автоматически ссылается на DateTimeOffset. Сокращенная форма: /r |
| /Сериализуемый | Создает классы, помеченные сериализуемым атрибутом. Сокращенная форма: /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. |
| /Завернутый | Определяет, используется ли особый подход для документов со стилем document-literal с параметрами в оболочке. Используйте параметр /wrapped с утилитой метаданных модели службы (Svcutil.exe), чтобы указать обычный регистр. |
Примечание.
Если привязка службы является одной из привязок, предоставленных системой (см. <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 |
| /исключитьТип:<тип> | Задает полное имя типа или имя типа с указанием на сборку, который необходимо исключить из экспорта. Этот параметр можно использовать при экспорте метаданных для службы или набора контрактов службы для запрещения экспорта этих типов. Данный параметр не может использоваться одновременно с параметром /dconly.Если в одной сборке содержится несколько служб, каждая из которых использует отдельные классы с одним и тем же именем XSD, для данного переключателя необходимо задать имя службы вместо имени класса XSD. XSD или типы контрактов данных не поддерживаются. Сокращенная форма: /et |
Проверка сервиса
Валидация может быть использована для обнаружения ошибок в реализациях службы без ее хостинга. Вы должны использовать параметр /serviceName, чтобы указать службу, которую хотите проверить.
svcutil.exe /validate /serviceName:<serviceConfigName> <assemblyPath>*
| Аргумент | Описание |
|---|---|
assemblyPath |
Задает путь к сборке, содержащей типы службы для проверки. Сборка должна содержать связанный файл конфигурации для настройки службы. Для предоставления нескольких сборок можно использовать стандартные подстановочные знаки командной строки. |
| Вариант | Описание |
|---|---|
| /валидировать | Проверяет реализацию службы, заданную параметром /serviceName. При использовании этого параметра в качестве входных данных необходимо передать исполняемую сборку со связанным файлом конфигурации.Сокращенная форма: /v |
| /serviceName:<serviceConfigName> | Задает имя конфигурации службы для проверки. Svcutil.exe осуществляет поиск всех связанных файлов конфигурации всех входных сборок для конфигурации службы. Если файлы конфигурации содержат какие-либо типы расширения, сборки, в состав которых входят эти типы, должны находиться в глобальном кэше сборок или явно предоставляться с использованием параметра /reference. |
| /reference:<путь к файлу> | Добавляет указанную сборку в набор сборок, используемых для разрешения ссылок на типы. При экспорте или проверке службы, которая использует зарегистрированные в конфигурации сторонние расширения (поведения, привязки и элементы привязок), используйте этот параметр для определения местоположения сборок расширений, которые не находятся в глобальном кэше сборок. Сокращенная форма: /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>
| Аргумент | Описание |
|---|---|
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:<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.
Наконец, не стоит использовать это средство на промежуточном уровне приложения, так как это может стать причиной отказа в обслуживании текущего процесса.