Ferramenta Utilitário de Metadados ServiceModel (Svcutil.exe)

A ferramenta ServiceModel Metadata Utility é usada para gerar código de modelo de serviço a partir de documentos de metadados e documentos de metadados a partir de código de modelo de serviço.

SvcUtil.exe

A ServiceModel Metadata Utility Tool pode ser encontrada no local de instalação do SDK do Windows, especificamente %ProgramFiles%\Microsoft SDKs\Windows\v6.0\Bin.

Funcionalidades

A tabela a seguir resume as várias funcionalidades fornecidas por essa ferramenta e o tópico correspondente que discute como ela é usada:

Task	Tópico
Gera código a partir de serviços em execução ou documentos de metadados estáticos.	Gerando um cliente WCF a partir de metadados de serviço
Exporta documentos de metadados de código compilado.	Como: Usar Svcutil.exe para exportar metadados do código de serviço compilado
Valida o código de serviço compilado.	Como: Usar Svcutil.exe para validar o código de serviço compilado
Baixa documentos de metadados de serviços em execução.	Como: Usar Svcutil.exe para baixar documentos de metadados
Gera código de serialização.	Como: Melhorar o tempo de inicialização de aplicativos cliente WCF usando o XmlSerializer

Atenção

Svcutil substitui arquivos existentes em um disco se os nomes fornecidos como parâmetros forem idênticos. Isso pode incluir arquivos de código, configuração ou arquivos de metadados. Para evitar isso ao gerar arquivos de código e configuração, use o /mergeConfig switch.

Além disso, os /r e /ct switches para tipos de referência são para gerar contratos de dados. Essas opções não funcionam ao usar XmlSerializer.

Limite de tempo excedido

A ferramenta tem um tempo limite de cinco minutos ao recuperar metadados. Esse tempo limite só se aplica à recuperação de metadados pela rede. Não se aplica a qualquer tratamento desses metadados.

Multi-segmentação

A ferramenta não suporta multi-targeting. Se você quiser gerar um artefato do .NET Framework 4 a partir do svcutil.exe, use o svcutil.exe do SDK do .NET Framework 4. Para gerar um artefato do .NET Framework 3.5, use o executável do SDK do .NET Framework 3.5.

Acessando documentos WSDL

Quando você usa Svcutil para acessar um documento WSDL que tem uma referência a um serviço de token de segurança (STS), Svcutil faz uma chamada WS-MetadataExchange para o STS. No entanto, o serviço pode expor seus documentos WSDL usando WS-MetadataExchange ou HTTP GET. Portanto, se o STS só tiver exposto o documento WSDL usando HTTP GET, um cliente escrito no WinFX falhará. Para clientes escritos no .NET Framework 3.5, o Svcutil tenta usar o WS-MetadataExchange e HTTP GET para obter o STS WSDL.

Usando SvcUtil.exe

Usos comuns

A tabela a seguir mostra algumas opções comumente usadas para essa ferramenta:

Opção	Description
/directory:<diretório>	Diretório para criar arquivos. Padrão: O diretório atual. Forma abreviada: /d
/help	Exibe a sintaxe do comando e as opções da ferramenta. Forma abreviada: /?
/noLogo	Suprima os direitos autorais e a mensagem do banner.
/svcutilConfig:<configFile>	Especifica um arquivo de configuração personalizado a ser usado em vez do arquivo App.config. Isso pode ser usado para registrar extensões system.serviceModel sem alterar o arquivo de configuração da ferramenta.
/target:<tipo de saída>	Especifica a saída a ser gerada pela ferramenta. Os valores válidos são código, metadados ou xmlSerializer. Forma abreviada: /t

Code Generation

Svcutil.exe pode gerar código para contratos de serviços, clientes e tipos de dados a partir de documentos de metadados. Esses documentos de metadados podem estar em um armazenamento durável ou ser recuperados on-line. A recuperação on-line segue o protocolo WS-Metadata Exchange ou o protocolo DISCO (para obter detalhes, consulte a seção Download de metadados).

Você pode usar a ferramenta SvcUtil.exe para gerar contratos de serviço e dados com base em um documento WSDL predefinido. Use a opção /serviceContract e especifique uma URL ou um local de arquivo onde o documento WSDL pode ser baixado ou encontrado. Isso gera os contratos de serviço e dados definidos no documento WSDL que podem ser usados para implementar um serviço de reclamação. Para obter mais informações, consulte Como recuperar metadados e implementar um serviço compatível.

Para um serviço com um ponto de extremidade BasicHttpContextBinding, Svcutil.exe gera um BasicHttpBinding com o allowCookies atributo definido como true em vez disso. Os cookies são usados para contexto no servidor. Se você gostaria de gerenciar o contexto no cliente quando o serviço usa cookies, você pode modificar manualmente a configuração para usar uma ligação de contexto.

Atenção

Svcutil.exe gera o cliente com base no WSDL ou no arquivo de política recebido do serviço. O nome principal do usuário (UPN) é gerado pela concatenação do nome de usuário, "@" e um nome de domínio totalmente qualificado (FQDN). No entanto, para usuários que se registraram no Ative Directory, esse formato não é válido e o UPN gerado pela ferramenta causa uma falha na autenticação Kerberos com a mensagem de erro "A tentativa de logon falhou". Para resolver esse problema, você deve corrigir manualmente o arquivo de cliente gerado por essa ferramenta.

svcutil.exe [/t:code] <metadataDocumentPath>* | <url>* | <epr>

Argumento	Description
epr	O caminho para um arquivo XML que contém um WS-Addressing EndpointReference para um ponto de extremidade de serviço que oferece suporte ao WS-Metadata Exchange. Para obter mais informações, consulte a seção Download de metadados.
metadataDocumentPath	O caminho para um documento de metadados (wsdl ou xsd) que contém o contrato a ser importado para o código (.wsdl, .xsd, .wspolicy ou .wsmex). Svcutil segue as importações e inclui quando você especifica uma URL remota para metadados. No entanto, se você deseja processar arquivos de metadados no sistema de arquivos local, você deve especificar todos os arquivos neste argumento. Desta forma, você pode usar Svcutil em um ambiente de compilação onde você não pode ter dependências de rede. Você pode usar curingas (*.xsd, *.wsdl) para esse argumento.
url	A URL para um ponto de extremidade de serviço que fornece metadados ou para um documento de metadados hospedado online. Para obter mais informações sobre como esses documentos são recuperados, consulte a seção Download de metadados.

Opção	Description
/assíncrono	Gera assinaturas de método síncronas e assíncronas. Padrão: gerar apenas assinaturas de método síncrono. Forma abreviada: /a
/collectionType:<tipo>	Especifica o tipo de coleção de lista para um cliente WCF. Padrão: o tipo de coleção é System.Array. Forma abreviada: /ct
/config:<configFile>	Especifica o nome do arquivo de configuração gerado. Padrão: output.config
/dataContractOnly	Gera código apenas para tipos de contrato de dados. Os tipos de Contrato de Serviço não são gerados. Você só deve especificar arquivos de metadados locais para essa opção. Forma abreviada: /dconly
/enableDataBinding	Implementa a interface em todos os tipos de Contrato de Dados para habilitar a INotifyPropertyChanged vinculação de dados. Forma abreviada: /edb
/excludeType:<tipo>	Especifica um nome de tipo totalmente qualificado ou qualificado para montagem a ser excluído dos tipos de contrato referenciados. Ao usar esse switch junto com /r DLLs separadas, o nome completo da classe XSD é referenciado. Forma abreviada: /et
/importXmlTypes	Configura o serializador de Contrato de Dados para importar tipos que não sejam de Contrato de Dados como tipos IXmlSerializable.
/interno	Gera classes marcadas como internas. Padrão: gerar somente classes públicas. Forma abreviada: /i
/language:<idioma>	Especifica a linguagem de programação a ser usada para a geração de código. Você deve fornecer um nome de idioma registrado no arquivo Machine.config ou o nome totalmente qualificado de uma classe que herda de CodeDomProvider. Valores: c#, cs, csharp, vb, visualbasic, c++, cpp Padrão: csharp Forma abreviada: /l
/mergeConfig	Mescla a configuração gerada em um arquivo existente, em vez de substituir o arquivo existente.
/messageContract	Gera tipos de contrato de mensagem. Forma abreviada: /mc
/namespace:<string,string>	Especifica um mapeamento de um targetNamespace do esquema WSDL ou XML para um namespace CLR. Usar '*' para targetNamespace mapeia todos targetNamespaces sem um mapeamento explícito para esse namespace CLR. Para certificar-se de que o nome do contrato de mensagem não colide com o nome da operação, você deve qualificar a referência de tipo com ::, ou certificar-se de que os nomes são exclusivos. Padrão: Derivado do namespace de destino do documento de esquema para Contratos de Dados. O namespace padrão é usado para todos os outros tipos gerados. Formulário curto: /n Nota: Ao gerar tipos para usar com XmlSerializer, apenas um único mapeamento de namespace é suportado. Todos os tipos gerados estarão no namespace padrão ou no namespace especificado por '*'.
/noConfiguração	Não gere arquivos de configuração.
/noStdLib	Não faça referência a bibliotecas padrão. Padrão: Mscorlib.dll e System.servicemodel.dll são referenciados.
/out:<arquivo>	Especifica o nome do arquivo para o código gerado. Padrão: Derivado do nome da definição WSDL, nome do serviço WSDL ou namespace de destino de um dos esquemas. Forma abreviada: /o
/reference:<caminho do arquivo>	Tipos de referência no assembly especificado. Ao gerar clientes, use essa opção para especificar assemblies que podem conter tipos que representam os metadados que estão sendo importados. Não é possível especificar contratos e XmlSerializer tipos de mensagens usando essa opção. Se DateTimeOffset referenciado, esse tipo é usado em vez de gerar um novo tipo. Se o aplicativo for escrito usando o .NET Framework 3.5, SvcUtil.exe referências DateTimeOffset automaticamente. Forma abreviada: /r
/serializável	Gera classes marcadas com o atributo serializável. Forma abreviada: /s
/serviceContract	Gere código apenas para contratos de serviço. A classe e a configuração do cliente não serão geradas Forma abreviada: /sc
/serializer:Automático	Selecione automaticamente o serializador. Isso tenta usar o serializador de contrato de dados e usa o XmlSerializer se isso falhar. Forma abreviada: /ser
/serializer:DataContractSerializer	Gera tipos de dados que usam o Data Contract Serializer para serialização e desserialização. Forma abreviada: /ser:DataContractSerializer
/serializer:XmlSerializer	Gera tipos de dados que usam o XmlSerializer para serialização e desserialização. Forma abreviada: /ser:XmlSerializer
/targetClientVersion	Especifique qual versão do .NET Framework o aplicativo está direcionando. Os valores válidos são Version30 e Version35. O valor predefinido é Version30. Forma abreviada: /tcv Version30: Use /tcv:Version30 se você estiver gerando código para clientes que usam WinFX. Version35: Use /tcv:Version35 se você estiver gerando código para clientes que usam o .NET Framework 3.5. Ao usar /tcv:Version35 com o switch, são gerados métodos assíncronos /async baseados em eventos e de retorno de chamada/delegado. Além disso, o suporte para DataSets habilitados para LINQ e DateTimeOffset está habilitado.
/embrulhado	Controla se a caixa especial é usada para documentos com estilo literal de documento com parâmetros encapsulados. Use a opção /wrapped com a ferramenta Service Model Metadata Utility Tool (Svcutil.exe) para especificar o invólucro normal.

Nota

Quando a associação de serviço é uma das associações fornecidas pelo sistema (consulte Ligações fornecidas pelo sistema) e a ProtectionLevel propriedade é definida como ou None Sign, Svcutil gera um arquivo de configuração usando o< elemento customBinding> em vez do elemento esperado fornecido pelo sistema. Por exemplo, se o serviço usa o <wsHttpBinding> elemento com o ProtectionLevel conjunto como Sign, a configuração gerada tem <customBinding> na seção bindings em vez de <wsHttpBinding>. Para obter mais informações sobre o nível de proteção, consulte Noções básicas sobre o nível de proteção.

Exportação de metadados

Svcutil.exe pode exportar metadados para serviços, contratos e tipos de dados em assemblies compilados. Para exportar metadados para um serviço, você deve usar a /serviceName opção para especificar o serviço que deseja exportar. Para exportar todos os tipos de contrato de dados em um assembly, você deve usar a /dataContractOnly opção. Por padrão, os metadados são exportados para todos os contratos de serviço nos assemblies de entrada.

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

Argumento	Description
assemblyPath	Especifica o caminho para um assembly que contém serviços, contratos ou tipos de contrato de dados a serem exportados. Curingas de linha de comando padrão podem ser usados para fornecer vários arquivos como entrada.

Opção	Description
/serviceName:<serviceConfigName>	Especifica o nome de configuração de um serviço a ser exportado. Se essa opção for usada, um assembly executável com um arquivo de configuração associado deverá ser passado como entrada. Svcutil.exe pesquisa todos os arquivos de configuração associados para a configuração do serviço. Se os arquivos de configuração contiverem quaisquer tipos de extensão, os assemblies que contêm esses tipos devem estar no GAC ou explicitamente fornecidos usando a /reference opção.
/reference:<caminho do arquivo>	Adiciona o assembly especificado ao conjunto de assemblies usados para resolver referências de tipo. Se você estiver exportando ou validando um serviço que usa extensões de terceiros (Comportamentos, Ligações e BindingElements) registradas na configuração, use essa opção para localizar assemblies de extensão que não estão no GAC. Forma abreviada: /r
/dataContractOnly	Opera apenas em tipos de contrato de dados. Os Contratos de Serviços não são processados. Você só deve especificar arquivos de metadados locais para essa opção. Forma abreviada: /dconly
/excludeType:<tipo>	Especifica o nome totalmente qualificado ou qualificado para montagem de um tipo a ser excluído da exportação. Essa opção pode ser usada ao exportar metadados para um serviço ou um conjunto de contratos de serviço para excluir tipos de serem exportados. Esta opção não pode ser utilizada em conjunto com a /dconly opção. Quando você tem um único assembly contendo vários serviços e cada um usa classes separadas com o mesmo nome XSD, você deve especificar o nome do serviço em vez do nome da classe XSD para essa opção. XSD ou tipos de contrato de dados não são suportados. Forma abreviada: /et

Validação do Serviço

A validação pode ser usada para detetar erros em implementações de serviço sem hospedar o serviço. Você deve usar a /serviceName opção para indicar o serviço que deseja validar.

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

Argumento	Description
assemblyPath	Especifica o caminho para um assembly que contém tipos de serviço a serem validados. O assembly deve ter um arquivo de configuração associado para fornecer a configuração do serviço. Curingas de linha de comando padrão podem ser usados para fornecer vários assemblies.

Opção	Description
/validar	Valida uma implementação de /serviceName serviço especificada pela opção. Se essa opção for usada, um assembly executável com um arquivo de configuração associado deverá ser passado como entrada. Forma abreviada: /v
/serviceName:<serviceConfigName>	Especifica o nome de configuração de um serviço a ser validado. Svcutil.exe pesquisa todos os arquivos de configuração associados de todos os assemblies de entrada para a configuração do serviço. Se os arquivos de configuração contiverem quaisquer tipos de extensão, os assemblies que contêm esses tipos devem estar no GAC ou explicitamente fornecidos usando a /reference opção.
/reference:<caminho do arquivo>	Adiciona o assembly especificado ao conjunto de assemblies usados para resolver referências de tipo. Se você estiver exportando ou validando um serviço que usa extensões de terceiros (Comportamentos, Ligações e BindingElements) registradas na configuração, use essa opção para localizar assemblies de extensão que não estão no GAC. Forma abreviada: /r
/dataContractOnly	Opera apenas em tipos de contrato de dados. Os Contratos de Serviços não são processados. Você só deve especificar arquivos de metadados locais para essa opção. Forma abreviada: /dconly
/excludeType:<tipo>	Especifica o nome totalmente qualificado ou qualificado para montagem de um tipo a ser excluído da validação. Forma abreviada: /et

Download de metadados

Svcutil.exe pode ser usado para baixar metadados de serviços em execução e salvar os metadados em arquivos locais. Para baixar metadados, você deve especificar a /t:metadata opção. Caso contrário, o código do cliente será gerado. Para esquemas de URL HTTP e HTTPS, Svcutil.exe tenta recuperar metadados usando WS-Metadata Exchange e DISCO. Para todos os outros esquemas de URL, Svcutil.exe usa apenas o WS-Metadata Exchange.

O Svcutil emite as seguintes solicitações de metadados simultaneamente para recuperar metadados.

• Solicitação MEX (WS-Transfer) para o endereço fornecido

• Pedido MEX para o endereço fornecido com /mex anexado

• Solicitação DISCO (usando o DiscoveryClientProtocol do ASMX) para o endereço fornecido.

Por padrão, Svcutil.exe usa as associações definidas na MetadataExchangeBindings classe para fazer solicitações MEX. Para configurar a associação usada para o WS-Metadata Exchange, você deve definir um ponto de extremidade do cliente na configuração que usa o contrato IMetadataExchange. Isso pode ser definido no arquivo de configuração do Svcutil.exe ou em outro arquivo de configuração especificado usando a /svcutilConfig opção.

svcutil.exe /t:metadata <url>* | <epr>

Argumento	Description
url	A URL para um ponto de extremidade de serviço que fornece metadados ou para um documento de metadados hospedado online.
epr	O caminho para um arquivo XML que contém um WS-Addressing EndpointReference para um ponto de extremidade de serviço que oferece suporte ao WS-Metadata Exchange.

Geração de tipo XmlSerializer

Serviços e aplicativos cliente que usam tipos de dados que são serializáveis usando o código de serialização gerar e compilar para esses tipos de dados em tempo de execução, o XmlSerializer que pode resultar em desempenho de inicialização lento.

Nota

O código de serialização pré-gerado só pode ser usado em aplicativos cliente e não em serviços.

Svcutil.exe pode gerar o código de serialização C# necessário a partir dos assemblies compilados para o aplicativo, melhorando assim o desempenho de inicialização para esses aplicativos. Para obter mais informações, consulte Como: Melhorar o tempo de inicialização de aplicativos cliente WCF usando o XmlSerializer.

Nota

Svcutil.exe só gera código para tipos usados por contratos de serviço encontrados nos assemblies de entrada.

svcutil.exe /t:xmlSerializer <assemblyPath>*

Argumento	Description
assemblyPath	Especifica o caminho para um assembly que contém tipos de contrato de serviço. Os tipos de serialização são gerados para todos os tipos Xml Serializable em cada contrato.

Opção	Description
/reference:<caminho do arquivo>	Adiciona o assembly especificado ao conjunto de assemblies usados para resolver referências de tipo. Forma abreviada: /r
/excludeType:<tipo>	Especifica o nome totalmente qualificado ou qualificado para montagem de um tipo a ser excluído da exportação ou validação. Forma abreviada: /et
/out:<arquivo>	Especifica o nome do arquivo para o código gerado. Essa opção é ignorada quando vários assemblies são passados como entrada para a ferramenta. Padrão: Derivado do nome do assembly. Forma abreviada: /o
/UseSerializerForFaults	Especifica que o XmlSerializer deve ser usado para falhas de leitura e gravação, em vez do padrão DataContractSerializer.

Exemplos

O comando a seguir gera o código do cliente a partir de um serviço em execução ou documentos de metadados online.

svcutil http://service/metadataEndpoint

O comando a seguir gera o código do cliente a partir de documentos de metadados locais.

svcutil *.wsdl *.xsd /language:C#

O comando a seguir gera tipos de contrato de dados no Visual Basic a partir de documentos de esquema local.

svcutil /dconly *.xsd /language:VB

O comando a seguir baixa documentos de metadados de serviços em execução.

svcutil /t:metadata http://service/metadataEndpoint

O comando a seguir gera documentos de metadados para contratos de serviço e tipos associados em um assembly.

svcutil myAssembly.dll

O comando a seguir gera documentos de metadados para um serviço e todos os contratos de serviço associados e tipos de dados em um assembly.

svcutil myServiceHost.exe /serviceName:myServiceName

O comando a seguir gera documentos de metadados para tipos de dados em um assembly.

svcutil myServiceHost.exe /dconly

O comando a seguir verifica a hospedagem do serviço.

svcutil /validate /serviceName:myServiceName myServiceHost.exe

O comando a seguir gera tipos de serialização para XmlSerializer tipos usados por quaisquer contratos de serviço no assembly.

svcutil /t:xmlserializer myContractLibrary.exe

Cota máxima de contagem de caracteres Nametable

Ao usar svcutil para gerar metadados para um serviço, você pode receber a seguinte mensagem:

Erro: Não é possível obter metadados de A cota máxima de contagem de caracteres nametable (16384) foi excedida durante a leitura de http://localhost:8000/somesservice/mex dados XML. A tabela de nomes é uma estrutura de dados usada para armazenar cadeias de caracteres encontradas durante o processamento XML - documentos XML longos com nomes de elementos não repetitivos, nomes de atributos e valores de atributos podem acionar essa cota. Essa cota pode ser aumentada alterando a propriedade MaxNameTableCharCount no objeto XmlDictionaryReaderQuotas usado ao criar o leitor XML.

Esse erro pode ser causado por um serviço que retorna um arquivo WSDL grande quando você solicita seus metadados. O problema é que a cota de caracteres para a ferramenta svcutil.exe é excedida. Esse valor é definido para ajudar a evitar ataques de negação de serviço (dos). Você pode aumentar essa cota especificando o seguinte arquivo de configuração para svcutil.

O seguinte arquivo de configuração mostra como definir as cotas de leitor para 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>

Crie um novo arquivo chamado svcutil.exe.config e copie o código de exemplo XML para ele. Em seguida, coloque o arquivo no mesmo diretório que svcutil.exe. Da próxima vez que svcutil.exe for executado, ele pegará as novas configurações.

Preocupações de segurança

Você deve usar a Lista de Controle de Acesso (ACL) apropriada para proteger a pasta de instalação do Svcutil.exe, Svcutil.config, e os arquivos que estão sendo apontados pelo /svcutilConfig. Isso pode impedir que extensões maliciosas sejam registradas e executadas.

Além disso, para minimizar a chance de a segurança ser comprometida, você não deve adicionar extensões não confiáveis para fazer parte do sistema ou usar provedores de código não confiáveis com Svcutil.exe.

Finalmente, você não deve usar a ferramenta na camada intermediária do seu aplicativo, pois ela pode causar negação de serviço para o processo atual.

Consulte também

• DataContractAttribute
• DataMemberAttribute
• Como: Criar um cliente