Nota
O acesso a esta página requer autorização. Pode tentar iniciar sessão ou alterar os diretórios.
O acesso a esta página requer autorização. Pode tentar alterar os diretórios.
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:
| Tarefa | 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 |
| Descarrega 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 desenvolvidos no .NET Framework 3.5, o Svcutil tenta utilizar tanto o WS-MetadataExchange como o 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 | Descrição |
|---|---|
| /directory:<diretório> | Diretório para criar arquivos. Padrão: Diretório atual. Forma abreviada: /d |
| /Ajuda | Exibe a sintaxe do comando e as opções da ferramenta. Forma abreviada: /? |
| /noLogo | Suprima os direitos autorais e a mensagem do banner. |
| /svcutilConfig:<ficheiro de configuração> | 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 |
Geração de código
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 atributo allowCookies ajustado para true como alternativa. 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 | Descrição |
|---|---|
epr |
O caminho para um ficheiro 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 caracteres universais (*.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í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:<ficheiroDeConfiguração> | 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 INotifyPropertyChanged em todos os tipos de Contrato de Dados para habilitar a 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. |
| /contratoDeMensagem | 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. Ao usar o '*' para o targetNamespace, mapeia todos os 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: /nNota: 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 '*'. |
| /semConfiguraçã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 na assemblagem especificada. 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 a aplicação for escrita usando o .NET Framework 3.5, o SvcUtil.exe faz referência a 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: /tcvVersion30: Use /tcv:Version30 se estiver a gerar 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 /async, são gerados tanto métodos assíncronos baseados em eventos quanto métodos baseados em callback/delegado. Além disso, o suporte para DataSets compatíveis com LINQ e DateTimeOffset está ativo. |
| /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 o enlace de serviço é uma das ligações fornecidas pelo sistema (consulte Associações Fornecidas pelo Sistema), e a propriedade ProtectionLevel está definida para None ou Sign, o Svcutil gera um ficheiro de configuração usando o elemento <customBinding> em vez do elemento de sistema fornecido esperado. Por exemplo, se o serviço usa o elemento <wsHttpBinding> com o ProtectionLevel definido como Sign, a configuração gerada tem <customBinding> na secção de ligações 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 num assembly, 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 | Descrição |
|---|---|
assemblyPath |
Especifica o caminho para um assembly que contém serviços, contratos ou tipos de contrato de dados a serem exportados. Caracteres curinga padrão na linha de comando podem ser usados para fornecer vários ficheiros como entrada. |
| Opção | Descrição |
|---|---|
| /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 ser explicitamente fornecidos usando a opção /reference. |
| /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 | Descrição |
|---|---|
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árias bibliotecas de código compilado. |
| Opção | Descrição |
|---|---|
| /validar | Valida uma implementação de serviço especificada pela opção /serviceName. 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 ou no GAC ou ser explicitamente fornecidos usando a opção /reference. |
| /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 ligação usada para o WS-Metadata Exchange, deve-se definir um ponto de extremidade do cliente na configuração que utiliza 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 | 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 ficheiro 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 Tipos para XmlSerializer
Serviços e aplicações clientes que utilizam tipos de dados serializáveis geram e compilam o código de serialização para esses tipos de dados em tempo de execução usando o XmlSerializer, o que pode resultar num desempenho lento durante o arranque.
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 | 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 Serializable em cada contrato. |
| Opção | Descrição |
|---|---|
| /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 os contratos de serviço e os tipos associados em uma assembly.
svcutil myAssembly.dll
O seguinte comando gera documentos de metadados para um serviço, assim como todos os contratos de serviço e tipos de dados associados em um conjunto.
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 em qualquer contrato de serviço no assembly.
svcutil /t:xmlserializer myContractLibrary.exe
Contagem máxima de caracteres na 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 http://localhost:8000/somesservice/mex A cota máxima de contagem de caracteres da tabela de nomes (16384) foi excedida durante a leitura de 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.