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

  • Artigo

A ferramenta de Utilitário de Metadados ServiceModel é usada para gerar código de modelo de serviço a partir de documentos de metadados e documentos de metadados a partir do código de modelo de serviço.

SvcUtil.exe

A ferramenta de Utilitário de Metadados ServiceModel 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:

Tarefa Tópico
Gera código de serviços em execução ou documentos estáticos de metadados. Gerando um cliente do WCF de metadados de serviço
Exporta documentos de metadados de código compilado. Como: usar Svcutil.exe para exportar metadados de código de serviço compilado
Validates código compilado de serviço. 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 dos aplicativos do cliente WCF usando o XmlSerializer

Cuidado

Svcutil substitui os 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 de configuração, use a opção /mergeConfig.

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

Tempo limite

A ferramenta tem um tempo limite de cinco minutos ao recuperar metadados. Esse tempo limite somente se aplica para recuperar metadados pela rede. Ele não se aplica a nenhum processamento desses metadados.

Multiplataforma

A ferramenta não dá suporte à multiplataforma. Se quiser gerar um artefato do .NET Framework 4 a partir do svcutil.exe, use o svcutil.exe a partir 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 o Svcutil para acessar um documento WSDL que tem uma referência para um serviço de token de segurança (STS), o 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 somente tiver exposto o documento WSDL usando o HTTP GET, um cliente gravado no WinFX falhará. Para clientes gravados no .NET Framework 3.5, o Svcutil tenta usar WS-MetadataExchange e HTTP GET para obter o STS WSDL.

Usando SvcUtil.exe

Usos comuns

A tabela a seguir mostra algumas opções de uso geral para essa ferramenta:

Opção Descrição
/directory:<directory> Diretório no qual criar arquivos.

Padrão: o diretório atual.

Forma abreviada: /d
/help Exibe a sintaxe de comando e as opções para a ferramenta.

Forma abreviada: /?
/noLogo Suprime a mensagem de copyright e de banner.
/svcutilConfig:<configFile> Especifica um arquivo de configuração personalizado para usar 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:<output type> Especifica a saída a ser gerada pela ferramenta.

Os valores válidos são código, metadados ou xmlSerializer.

Forma abreviada: /t

Geração de código

Svcutil.exe pode gerar código para contratos de serviço, clientes e tipos de dados a partir de documentos de metadados. Esses documentos de metadados podem estar em um armazenamento durável, ou serem recuperados online. A recuperação online 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 local do arquivo de onde o documento WSDL pode ser baixado ou localizado. Isso gera os contratos de serviço e de dados definidos no documento WSDL que pode ser usado 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, o Svcutil.exe gera um BasicHttpBinding com o atributo allowCookies definido como true. Os cookies são usados para o contexto no servidor. Se você quiser gerenciar o contexto no cliente quando o serviço usa cookies, poderá modificar manualmente a configuração para usar uma associação de contexto.

Cuidado

O Svcutil.exe gera o cliente com base no WSDL ou no arquivo de políticas recebido do serviço. O nome principal do usuário (UPN) é gerado concatenando o nome de usuário, "@" e um nome de domínio totalmente qualificado (FQDN). Entretanto, para os usuários registrados no Active Directory, esse formato é inválido e o UPN gerado pela ferramenta causa uma falha na autenticação Kerberos com a mensagem de erro “Falha ao tentar fazer logon”. Para resolver esse problema, você deve corrigir manualmente o arquivo cliente gerado por essa ferramenta.

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

Argumento Descrição
epr O caminho para um arquivo XML que contém um WS-Addressing EndpointReference para um ponto de extremidade de serviço que dá suporte a 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 para importar para o código (.wsdl, .xsd, .wspolicy ou .wsmex).

O Svcutil segue as importações e inclui quando você especifica uma URL remota para metadados. Entretanto, se você quiser processar os arquivos de metadados no sistema de arquivos local, deverá especificar todos os arquivos nesse argumento. Dessa maneira, você poderá usar o Svcutil em um ambiente de compilação onde não poderá 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 Descrição
/async Gera assinaturas de método síncronas e assíncronas.

Padrão: gerar apenas assinaturas de método síncronas.

Forma abreviada: /a
/collectionType:<type> 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 para o arquivo de configuração gerado.

Padrão: output.config
/dataContractOnly Gera código somente para tipos de contrato de dados. Os tipos de contrato de serviço não são gerados.

Você deve especificar somente arquivos dos metadados locais para essa opção.

Forma abreviada: /dconly
/enableDataBinding Implementa a interface INotifyPropertyChanged em todos os tipos de Contrato de Dados para habilitar a vinculação de dados.

Forma abreviada: /edb
/excludeType:<type> Especifica um nome de tipo totalmente qualificado ou qualificado do assembly a ser excluído dos tipos de contrato referenciados.

Ao usar essa opção junto com /r de DLL separadas, o nome completo da classe XSD é referenciado.

Forma abreviada: /et
/importXmlTypes Configurar o serializador do Contrato de Dados para importar tipos de Contrato de não Dados como tipos IXmlSerializable.
/internal Gera as classes que são marcadas como internas. Padrão: gerar somente classes públicas.

Forma abreviada: /i
/language:<language> Especifica a linguagem de programação a ser usada para gerar o código. Você deve fornecer um nome de linguagem registrado no arquivo Machine.config ou 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 WSDL ou do esquema XML para um namespace de CLR. Usar '*' para o targetNamespace mapeia todos os targetNamespaces sem um mapeamento explícito para o namespace CLR.

Para garantir que o nome do contrato da mensagem não colida com o nome da operação, você deverá qualificar a referência de tipo com :: ou verificar se 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: /nObservação: ao gerar tipos a serem usados com XmlSerializer, há suporte apenas para um único mapeamento de namespace. Todos os tipos gerados estarão no namespace padrão ou no namespace especificado por '*'.
/noConfig Não gera arquivos de configuração.
/noStdLib Não faz referência às bibliotecas padrão.

Padrão: Mscorlib.dll e System.servicemodel.dll são referenciados.
/out:<file> Especifica o nome do arquivo para o código gerado.

Padrão: derivado do nome de definição WSDL, serviço WSDL ou namespace de destino de um dos esquemas.

Forma abreviada: /o
/reference:<file path> Os tipos de referência no assembly especificado. Ao gerar clientes, use esta opção para especificar os assemblies que podem conter tipos que representam os metadados que estão sendo importados.

Você não pode especificar os contratos de mensagem e os tipos XmlSerializer usando essa opção.

Se DateTimeOffset for referenciado, esse tipo é usado em vez de gerar um novo tipo. Se o aplicativo estiver gravado usando o .NET Framework 3.5, o SvcUtil.exe referenciará DateTimeOffset automaticamente.

Forma abreviada: /r
/serializable Gera classes marcadas com o atributo Serializable.

Forma abreviada: /s
/serviceContract Gerar código somente para contratos de serviço. A classe e a configuração do cliente não serão geradas

Forma abreviada: /sc
/serializer:Auto 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 os tipos de dados que usam o serializador Contrato de Dados para serialização e desserialização.

Forma abreviada: /ser:DataContractSerializer
/serializer:XmlSerializer Gera os tipos de dados que usam o XmlSerializer para serialização e desserialização.

Forma abreviada: /ser:XmlSerializer
/targetClientVersion Especifique para qual versão do .NET Framework o aplicativo está destinado. Os valores válidos são Version30 e Version35. O valor padrão é Version30.

Forma abreviada: /tcv

Version30: use /tcv:Version30 se você estiver gerando o código para clientes que usam WinFX.

Version35: use /tcv:Version35 se você estiver gerando o código para clientes que usam o .NET Framework 3.5. Ao usar /tcv:Version35 com a opção /async, os métodos assíncronos baseados em evento e baseados em retorno de chamada/representante são gerados. Além disso, o suporte para DataSets habilitados para LINQ e DateTimeOffset está habilitado.
/wrapped Controla se a diferença entre maiúsculas e minúsculas é usada para documentos de estilo literal com parâmetros encapsulados. Use a opção /wrapped com a Ferramenta de Utilitário de Metadados do Modelo de Serviço (Svcutil.exe) para especificar maiúsculas e minúsculas normal.

Observação

Quando a associação de serviço é uma das associações fornecidas pelo sistema (consulte Associações fornecidas pelo sistema) e a propriedade ProtectionLevel é definida como None ou Sign, o 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 elemento <wsHttpBinding> com ProtectionLevel definido como Sign, a configuração gerada tem <customBinding> na seção de associação em vez de <wsHttpBinding>. Para obter mais informações sobre nível de proteção, consulte Noções básicas de nível de proteção.

Exportação de metadados

O Svcutil.exe pode exportar os metadados para serviços, contratos e tipos de dados em assemblies compilados. Para exportar metadados para um serviço, você deve usar a opção /serviceName para especificar o serviço que você gostaria de exportar. Para exportar todos os tipos de contrato de dados dentro de um assembly, você deverá usar a opção /dataContractOnly. 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 Descrição
assemblyPath Especifica o caminho para um assembly que contém serviços, contratos ou tipos de contrato de dados para ser exportados. Curingas padrão de linha de comando podem ser usados para fornecer vários arquivos como entrada.
Opção Descrição
/serviceName:<serviceConfigName> Especifica o nome da configuração de um serviço a ser exportado. Se esta opção for usada, um assembly executável com um arquivo de configuração associado deverá ser passado como entrada. O Svcutil.exe procura todos os arquivos de configuração associados para a configuração do serviço. Se os arquivos de configuração contiverem tipos de extensão, os assemblies que contêm esses tipos deverão estar no GAC ou ser fornecidos explicitamente usando a opção /reference.
/reference:<file path> 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, associações e BindingElements) registradas em configuração, use esta opção para localizar assemblies de extensão que não estão no GAC.

Forma abreviada: /r
/dataContractOnly Opera somente em tipos de contrato de dados. Contratos de serviço não são processados.

Você deve especificar somente arquivos dos metadados locais para essa opção.

Forma abreviada: /dconly
/excludeType:<type> Especifica o nome totalmente qualificado ou qualificado do assembly 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 usada junto com a opção /dconly.

Quando você tiver um único assembly contendo vários serviços, e cada um usar classes separadas com o mesmo nome XSD, deverá 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 têm suporte.

Forma abreviada: /et

Validação de serviço

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

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

Argumento Descrição
assemblyPath Especifica o caminho para um assembly que contém os 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 padrão de linha de comando podem ser usados para fornecer vários assemblies.
Opção Descrição
/validate Valida uma implementação de serviço especificada pela opção /serviceName. Se esta 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 da configuração de um serviço a ser validado. O Svcutil.exe procura 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 tipos de extensão, os assemblies que contêm esses tipos deverão estar no GAC ou ser fornecidos explicitamente usando a opção /reference.
/reference:<file path> 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, associações e BindingElements) registradas em configuração, use esta opção para localizar assemblies de extensão que não estão no GAC.

Forma abreviada: /r
/dataContractOnly Opera somente em tipos de contrato de dados. Contratos de serviço não são processados.

Você deve especificar somente arquivos dos metadados locais para essa opção.

Forma abreviada: /dconly
/excludeType:<type> Especifica o nome totalmente qualificado ou qualificado do assembly de um tipo a ser excluído da validação.

Forma abreviada: /et

Download de metadados

O 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ê deverá especificar a opção /t:metadata. Caso contrário, o código do cliente será gerado. Para os esquemas de URL de HTTP e HTTPS, o Svcutil.exe tenta recuperar metadados usando WS-Metadata Exchange e DISCO. Para todos os outros esquemas de URL, o Svcutil.exe usa apenas WS-Metadata Exchange.

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

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

  • A solicitação de MEX para o endereço fornecido com /mex adicionado

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

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

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

Argumento Descrição
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 dá suporte a WS-Metadata Exchange.

Geração de tipo de XmlSerializer

Os aplicativos de serviços e de cliente que usam tipos de dados serializados usando o XmlSerializer geram e compilam o código de serialização para esses tipos de dados em tempo de execução, o que pode resultar em um desempenho lento da inicialização.

Observação

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

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

Observação

O Svcutil.exe somente gera código para os tipos usados por contratos de serviço localizados em assemblies de entrada.

svcutil.exe /t:xmlSerializer <assemblyPath>*

Argumento Descrição
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 serializáveis em cada contrato.
Opção Descrição
/reference:<file path> Adiciona o assembly especificado ao conjunto de assemblies usados para resolver referências de tipo.

Forma abreviada: /r
/excludeType:<type> Especifica o nome totalmente qualificado ou qualificado do assembly de um tipo a ser excluído da exportação ou validação.

Forma abreviada: /et
/out:<file> Especifica o nome do arquivo para o código gerado. Essa opção será 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 ler e gravar falhas, em vez do DataContractSerializer padrão.

Exemplos

O comando a seguir gera o código do cliente 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 de documentos de metadados locais.

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

O comando a seguir gera os tipos de contrato de dados no Visual Basic de documentos de esquema locais.

svcutil /dconly *.xsd /language:VB

O comando a seguir baixa os 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 os tipos XmlSerializer usados por todos os contratos de serviço no assembly.

svcutil /t:xmlserializer myContractLibrary.exe

Cota máxima da conta de caracteres Nametable

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

Erro: não é possível obter metadados de http://localhost:8000/somesservice/mex A cota máxima da cota de caracteres do nametable (16384) foi excedida durante a leitura de dados XML. Nametable é uma estrutura de dados usada para armazenar cadeias de caracteres encontradas durante o processamento do XML - documentos XML longos com nomes de elementos, nomes de atributos e valores de atributos não repetidos, podem disparar essa cota. Essa cota pode ser aumentada com a alteração da propriedade MaxNameTableCharCount no objeto XmlDictionaryReaderQuotas usado na criação da leitora XML.

Este 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 foi 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 o svcutil.

O arquivo de configuração a seguir mostra como configurar as cotas do leitor para o 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 nele. Em seguida, coloque o arquivo no mesmo diretório que svcutil.exe. Na próxima vez que svcutil.exe é executado, ele utilizará as novas configurações.

Problemas de segurança

Você deverá usar a lista de controle de acesso (ACL) apropriado para proteger a pasta de instalação do Svcutil.exe, Svcutil.config, e os arquivos que estão sendo apontados por /svcutilConfig. Isso pode impedir as extensões mal-intencionadas de serem registradas e executadas.

Além disso, para minimizar a possibilidade de que a segurança seja comprometida, você não deverá adicionar extensões não confiáveis para fazerem parte do sistema nem usar provedores de código não confiáveis com Svcutil.exe.

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

Confira também