Strumento ServiceModel Metadata Utility Tool (Svcutil.exe)
Lo strumento ServiceModel Metadata Utility Tool viene utilizzato per generare il codice del modello di servizi da documenti di metadati e documenti di metadati dal codice di modello di servizi.
Osservazioni
Lo strumento ServiceModel Metadata Utility Tool si trova nel percorso di installazione Windows SDK, specificamente, in C:\Program Files\Microsoft SDKs\Windows\v6 .0 \Bin
Nella tabella seguente sono riepilogate le varie funzionalità fornite da questo strumento e l'argomento corrispondente che ne descrive le modalità di utilizzo.
| Attività | Argomento |
|---|---|
Consente di generare codice dai servizi in esecuzione o dai documenti di metadati statici. |
|
Consente di esportare documenti di metadati da codice compilato. |
How to: Use Svcutil.exe to Export Metadata from Compiled Service Code |
Consente di convalidare codice di servizio compilato. |
|
Consente di scaricare documenti di metadati dai servizi in esecuzione. |
|
Consente di generare codice di serializzazione. |
.gif) Attenzione: |
|---|
| Lo strumento Svcutil sovrascriverà i file esistenti su un disco se i nomi forniti come parametri sono identici. Tali risorse possono includere file di codice, di configurazione o di metadati. Per evitare questo problema durante la generazione di file di codice e di configurazione, utilizzare il commutatore /mergeConfig. Inoltre, è possibile utilizzare i commutatori /r e /ct per tipi di riferimento per generare contratti dati. Questi commutatori non funzionano in caso di utilizzo di XmlSerializer. |
Lo strumento ha un timeout di 5 minuti nel recupero di metadati. Questo timeout si applica solo al recupero di metadati sulla rete. Non si applica a qualsiasi elaborazione dei metadati.
Quando si utilizza Svcutil per accedere a un documento WSDL che presenti un riferimento al servizio token di protezione (STS), Svcutil effettua una chiamata di WS-MetadataExchange a STS. Tuttavia, il servizio può esporre il proprio documento WSDL utilizzando sia WS-MetadataExchange, sia HTTP GET. Pertanto, se STS ha solamente esposto il documento WSDL utilizzando HTTP GET, un client scritto in .NET Framework 3.0 avrà esito negativo. Per i client scritti in .NET Framework 3.5, Svcutil tenterà di utilizzare sia WS-MetadataExchange che HTTP GET per ottenere il documento WSDL di STS .
Utilizzi comuni
Nella tabella seguente vengono illustrate alcune opzioni comunemente usate per questo strumento.
| Opzione | Descrizione |
|---|---|
/directory:<directory> |
Directory nella quale creare file. Impostazione predefinita: directory corrente. Forma abbreviata: /d |
/help |
Visualizza la sintassi e le opzioni dei comandi dello strumento. Forma abbreviata: /? |
/noLogo |
Eliminare le informazioni di copyright e il messaggio di avvio. |
/svcutilConfig:<configFile> |
Consente di specificare un file di configurazione personalizzato da utilizzare in sostituzione del file App.config. Questo file può essere utilizzato per registrare estensioni system.serviceModel senza alterare il file di configurazione dello strumento. |
/target:<output type> |
Consente di specificare l’output che verrà generato dallo strumento. I valori validi sono codice, metadati o xmlSerializer. Forma abbreviata: /t |
Generazione di codice
Lo strumento Svcutil.exe è in grado di generare codice per contratti di servizio, client e tipi di dati dai documenti di metadati. Questi documenti di metadati possono essere salvati in modo permanente o recuperati in linea. Il recupero in linea segue il protocollo WS-Metadata Exchange o il protocollo DISCO (per i dettagli vedere la sezione Download dei metadati).
Per un servizio con un endpoint BasicHttpContextbinding, Svcutil.exe genera un BasicHttpBinding con l'attributo allowCookies impostato su true. I cookie vengono utilizzati come contesto sul server. Se si desidera gestire il contesto sul client quando il servizio utilizza cookie, è possibile modificare la configurazione per utilizzare un elemento di associazione del contesto.
| Attenzione: |
|---|
| Lo strumento Svcutil.exe consente di generare il client in base al WSDL o al file dei criteri ricevuto dal servizio. Il nome dell’entità utente (UPN) è generato concatenando nome utente, "@" e un nome di dominio completo (FQDN). Per utenti registrati su Active Directory, questo formato non è tuttavia valido e l’UPN generato dallo strumento provoca un errore di autenticazione Kerberos con il messaggio di errore che “Tentativo di accesso non riuscito”. Per risolvere questo problema è necessario correggere manualmente il file client generato da questo strumento. |
svcutil.exe [/t:code] <metadataDocumentPath>* | <url>* | <epr>
| Argomento | Descrizione |
|---|---|
epr |
Percorso di un file XML contenente un EndpointReference WS-Addressing per un endpoint di servizio che supporta WS-MetadataExchange. Per ulteriori informazioni, vedere la sezione Download dei metadati. |
metadataDocumentPath |
Percorso per un documento di metadati (wsdl o xsd) contenente il contratto da importare in codice (.wsdl, .xsd, .wspolicy o .wsmex). Lo strumento Svcutil consente di importare e includere quando si specifica un URL remoto per metadati. Tuttavia, se si desidera elaborare file di metadati sul file system locale, è necessario specificare tutti i file di questo argomento. In questo modo, è possibile utilizzare Svcutil in un ambiente di compilazione dove non è possibile avere dipendenze della rete. È possibile utilizzare caratteri jolly (ad esempio, * .xsd, * .wsdl) per questo argomento. |
url |
URL a un endpoint di servizio che fornisce metadati o a un documento di metadati ospitato in linea. Per ulteriori informazioni sulla modalità di recupero di questi documenti, vedere la sezione Download dei metadati. |
| Opzione | Descrizione |
|---|---|
/async |
Genera firme di metodi sincrone e asincrone. Impostazione predefinita: generare solo firme di metodi sincrone. Forma abbreviata: /a |
/collectionType:<type> |
Specifica un nome tipo completo o un nome completo del tipo dell'assembly da utilizzare come tipo di dati di raccolta, quando il codice viene generato da schemi. Forma abbreviata: /ct |
/config:<configFile> |
Specifica il nome file per il file di configurazione generato. Impostazione predefinita: output.config |
/dataContractOnly |
Genera solo codice per tipi di contratto dati. I tipi di contratto di servizio non vengono generati. Per questa opzione è necessario specificare soltanto file di metadati locali. Forma abbreviata: /dconly |
/enableDataBinding |
Implementa l'interfaccia INotifyPropertyChanged su tutti i tipi di contratto dati per consentire l'associazione dati. Forma abbreviata: /edb |
/excludeType:<type> |
Specifica un nome tipo completo o un nome completo del tipo dell’assembly da escludere dai tipi di contratto a cui si fa riferimento. Se si utilizza questo commutatore insieme con /r di DLL distinte, viene fatto riferimento al nome completo della classe XSD. Forma abbreviata: /et |
/importXmlTypes |
Configura il serializzatore DataContract per l'importazione di tipi diversi da DataContract come tipi IXmlSerializable. |
/internal |
Genera classi contrassegnate come interne. Impostazione predefinita: generare soltanto classi pubbliche. Forma abbreviata: /i |
/language:<language> |
Specifica il linguaggio di programmazione da utilizzare per la generazione del codice. È necessario fornire un nome di linguaggio registrato nel file Machine.config o il nome completo di una classe che eredita da CodeDomProvider. Values: c#, cs, csharp, vb, visualbasic, c++, cpp Impostazione predefinita: csharp Forma abbreviata: /l Nota Il commutatore supporta solo C++ per il provider di codice fornito con Visual Studio 2005 SP1. |
/mergeConfig |
Incorpora la configurazione generata in un file esistente, anziché sovrascrivere il file esistente. |
/messageContract |
Genera tipi di contratto di messaggio. Forma abbreviata: /mc |
/namespace:<string,string> |
Specifica un mapping da WSDL o Schema XML targetNamespace a uno spazio dei nomi CLR. L’utilizzo di '*' per il targetNamespace consente di eseguire il mapping di ogni targetNamespaces senza un mapping esplicito a quel determinato spazio dei nomi CLR. Per assicurarsi che il nome del contratto di messaggio non entri in conflitto con il nome dell'operazione, è necessario qualificare il riferimento al tipo con :: o verificare che i nomi siano univoci. Impostazione predefinita: derivata dallo spazio dei nomi di destinazione del documento dello schema per i Contratti dati. Lo spazio dei nomi predefinito viene utilizzato per tutti gli altri tipi generati. Forma abbreviata: /n |
/noConfig |
Non generare file di configurazione. |
/noStdLib |
Non fare riferimento a librerie standard. Impostazione predefinita: viene fatto riferimento a Mscorlib.dll e System.servicemodel.dll. |
/out:<file> |
Specifica il nome del file per il codice generato. Impostazione predefinita: derivata dal nome della definizione di WSDL, dal nome del servizio WSDL o dallo spazio dei nomi di destinazione di uno degli schemi. Forma abbreviata: /o |
/serializable |
Genera classi contrassegnate con Attributo serializzabile. Forma abbreviata: /s |
/targetClientVersion |
Specificare a quale versione di .NET Framework è destinata l'applicazione. I valori validi sono Version30 e Version35. Il valore predefinito è Version30il che significa che lo strumento SvcUtil.exe fa riferimento a .NET Framework 3.0 per impostazione predefinita. Forma abbreviata: /tcv Version30: utilizzare Version35: utilizzare |
/reference:<file path> |
Fa riferimento a tipi nell'assembly specificato. Quando si generano client, utilizzare questa opzione per specificare assembly che potrebbero contenere tipi che rappresentano i metadati importati. Non è possibile specificare contratti di messaggio e tipi XmlSerializer utilizzando questo commutatore. Se DateTimeOffset fa riferimento, viene utilizzato questo tipo invece di generare un tipo nuovo. Se l'applicazione viene scritta utilizzando .NET Framework 3.5, SvcUtil.exe fa automaticamente riferimento a DateTimeOffset. Forma abbreviata: /r |
/serializer:Auto |
Seleziona automaticamente il serializzatore. Utilizza il serializzatore del Contratto dati. In caso di errore, viene utilizzato XmlSerializer. Forma abbreviata: /ser:Auto |
/serializer:DataContractSerializer |
Genera tipi di dati che utilizzano DataContract Serializer per la serializzazione e la deserializzazione. Forma abbreviata: /ser:DataContractSerializer |
/serializer:XmlSerializer |
Genera tipi di dati che utilizzano XmlSerializerXmlSerializer per la serializzazione e la deserializzazione. Forma abbreviata: /ser:XmlSerializer |
Nota
Quando l'associazione al servizio è una delle associazioni fornite dal sistema (vedere System-Provided Bindings) e la proprietà ProtectionLevel è impostata su None o Sign, Svcutil genera un file di configurazione utilizzando l'elemento <customBinding> anziché l'elemento fornito dal sistema previsto. Ad esempio, se il servizio utilizza l'elemento <wsHttpBinding> con ProtectionLevel impostato su Sign, la configurazione generata ha <customBinding> nella sezione delle associazioni anziché <wsHttpBinding>. Per ulteriori informazioni sul livello di protezione, vedere Understanding Protection Level.
Esportazione dei metadati
Svcutil.exe è in grado di esportare metadati per servizi, contratti e tipi di dati in assembly compilati. Per esportare metadati per un servizio, è necessario utilizzare l'opzione /serviceName per specificare il servizio che si desidera esportare. Per esportare tutti i tipi di contratto dati all'interno di un assembly, utilizzare l'opzione /dataContractOnly. Per impostazione predefinita, i metadati vengono esportati per tutti i contratti di servizio negli assembly di input.
svcutil.exe [/t:metadata] [/serviceName:<serviceConfigName>] [/dataContractOnly] <assemblyPath>*
| Argomento | Descrizione |
|---|---|
assemblyPath |
Specifica il percorso per un assembly contenente servizi, contratti o tipi di contratto dati da esportare. È possibile utilizzare caratteri jolly della riga di comando standard per fornire più file come input. |
| Opzione | Descrizione |
|---|---|
/serviceName:<serviceConfigName> |
Specifica il nome della configurazione di un servizio da esportare. Se viene utilizzata questa opzione, deve essere passato come input un assembly eseguibile con un file di configurazione associato. Svcutil.exe esegue la ricerca in tutti i file di configurazione associati per la configurazione del servizio. Se i file di configurazione contengono qualsiasi tipo di estensione, gli assembly contenenti questi tipi devono essere in GAC o devono essere forniti in modo esplicito utilizzando l'opzione /reference. |
/reference:<file path> |
Aggiunge l'assembly specificato all'insieme di assembly utilizzato per la risoluzione di riferimenti del tipo. Se si sta esportando o convalidando un servizio che utilizza estensioni di terzi (Comportamenti, Associazioni e BindingElements) registrate in configurazione, utilizzare questa opzione per ricercare assembly di estensione che non si trovano in GAC. Forma abbreviata: /r |
/dataContractOnly |
Opera soltanto su tipi di contratto dati. I contratti di servizio non vengono elaborati. Per questa opzione è necessario specificare soltanto file di metadati locali. Forma abbreviata: /dconly |
/excludeType:<type> |
Specifica il nome completo o il nome completo dell’assembly del tipo da escludere dall’esportazione. Questa opzione può essere utilizzata quando si esportano metadati per un servizio o un insieme di contratti di servizio per escludere tipi dall'esportazione. Non è possibile utilizzare questa opzione con l'opzione /dconly. Quando si ha un solo assembly contenente più servizi che utilizzano classi separate con lo nome XSD, è necessario specificare il nome del servizio anziché il nome della classe XSD per questo commutatore. Non vengono supportati tipi XSD o tipi di contratto dati. Forma abbreviata: /et |
Convalida del servizio
È possibile utilizzare la convalida per rilevare errori in implementazioni del servizio senza ospitare il servizio. È necessario utilizzare l'opzione /serviceName per indicare il servizio che si desidera convalidare.
svcutil.exe /validate /serviceName:<serviceConfigName> <assemblyPath>*
| Argomento | Descrizione |
|---|---|
assemblyPath |
Specifica il percorso per un assembly contenente tipi di contratto di servizio da convalidare. L'assembly deve avere un file di configurazione associato per fornire la configurazione del servizio. È possibile utilizzare caratteri jolly della riga di comando standard per fornire più assembly. |
| Opzione | Descrizione |
|---|---|
/validate |
Convalida un'implementazione del servizio specificata dall'opzione /serviceName. Se viene utilizzata questa opzione, deve essere passato come input un assembly eseguibile con un file di configurazione associato. Forma abbreviata: /v |
/serviceName:<serviceConfigName> |
Specifica il nome della configurazione di un servizio da convalidare. Svcutil.exe esegue la ricerca in tutti i file di configurazione associati di tutti gli assembly di input per la configurazione del servizio. Se i file di configurazione contengono qualsiasi tipo di estensione, gli assembly contenenti questi tipi devono essere in GAC o devono essere forniti in modo esplicito utilizzando l'opzione /reference. |
/reference:<file path> |
Aggiunge l'assembly specificato all'insieme di assembly utilizzato per la risoluzione di riferimenti del tipo. Se si sta esportando o convalidando un servizio che utilizza estensioni di terzi (Comportamenti, Associazioni e BindingElements) registrate in configurazione, utilizzare questa opzione per ricercare assembly di estensione che non si trovano in GAC. Forma abbreviata: /r |
/dataContractOnly |
Opera soltanto su tipi di contratto dati. I contratti di servizio non vengono elaborati. Per questa opzione è necessario specificare soltanto file di metadati locali. Forma abbreviata: /dconly |
/excludeType:<type> |
Specifica il nome completo o il nome completo dell’assembly del tipo da escludere dalla convalida. Forma abbreviata: /et |
Download dei metadati
È possibile utilizzare Svcutil.exe per scaricare i metadati dai servizi in esecuzione e salvarli in file locali. Per scaricare i metadati, è necessario specificare l'opzione /t:metadata. In caso contrario, viene generato il codice client. Per schemi URL HTTP e HTTPS, Svcutil.exe tenta di recuperare i metadati mediante WS-Metadata Exchange e DISCO. Per tutti gli altri schemi URL, Svcutil.exe utilizza solo WS-Metadata Exchange.
Svcutil genera le richieste di metadati seguenti simultaneamente per recuperare metadati.
- Richiesta MEX (WS-Transfer) all'indirizzo fornito
- Richiesta MEX all'indirizzo fornito con /mex accodati
- Richiesta DISCO (utilizzo di DiscoveryClientProtocol da ASMX) all'indirizzo fornito.
Per impostazione predefinita, Svcutil.exe utilizza le associazioni definite nella classe MetadataExchangeBindings per generare richieste MEX. Per configurare l'associazione utilizzata per WS-Metadata Exchange è necessario definire un endpoint client in configurazione che utilizza il contratto IMetadataExchange. Ciò può essere definito nel file di configurazione di Svcutil.exe o in un altro file di configurazione specificato utilizzando l'opzione /svcutilConfig.
svcutil.exe /t:metadata <url>* | <epr>
| Argomento | Descrizione |
|---|---|
url |
URL a un endpoint di servizio che fornisce metadati o a un documento di metadati ospitato in linea. |
epr |
Percorso di un file XML contenente un EndpointReference WS-Addressing per un endpoint di servizio che supporta WS-MetadataExchange. |
Generazione del tipo XmlSerializer
I servizi e le applicazioni client che utilizzano tipi di dati serializzabili tramite XmlSerializer generano e compilano il codice di serializzazione per tali dati in fase di esecuzione, il che può rallentare le prestazioni all'avvio.
Nota
Un codice di serializzazione pregenerato può essere utilizzato solamente nelle applicazioni client e non nei servizi.
Svcutil.exe può generare il codice di serializzazione C# necessario dagli assembly compilati per l’applicazione, migliorando le prestazioni all'avvio per queste applicazioni. Per ulteriori informazioni, vedere How to: Improve the Startup Time of WCF Client Applications using the XmlSerializer.
Nota
Svcutil.exe genera soltanto codice per tipi utilizzati dai Contratti di Servizio che si trovano negli assembly di input.
svcutil.exe /t:xmlSerializer <assemblyPath>*
| Argomento | Descrizione |
|---|---|
assemblyPath |
Specifica il percorso per un assembly contenente tipi di contratto di servizio. I tipi di serializzazione vengono generati per tutti i tipi serializzabili in Xml in ogni contratto. |
| Opzione | Descrizione |
|---|---|
/reference:<file path> |
Aggiunge l'assembly specificato all'insieme di assembly utilizzato per la risoluzione di riferimenti del tipo. Forma abbreviata: /r |
/excludeType:<type> |
Specifica il nome completo o il nome completo dell’assembly del tipo da escludere dall’esportazione o convalida. Forma abbreviata: /et |
/out:<file> |
Specifica il nome file per il codice generato. Questa opzione è ignorata quando più assembly vengono passati come input allo strumento. Impostazione predefinita: derivata dal nome dell'assembly. Forma abbreviata: /o |
/UseSerializerForFaults |
Specifica che per la lettura e la scrittura degli errori deve essere utilizzato XmlSerializer anziché l'oggetto predefinito DataContractSerializer. |
Esempi
Il comando seguente consente di generare il codice client da un servizio in esecuzione o da documenti di metadati in linea.
svcutil http://service/metadataEndpoint
Il comando seguente consente di generare il codice client da documenti di metadati locali.
svcutil *.wsdl *.xsd /language:C#
Il comando seguente consente di generare tipi di contratto dati in Visual Basic dai documenti di schema locali.
svcutil /dconly *.xsd /language:VB
Il comando seguente consente di scaricare i documenti di metadati da servizi in esecuzione.
svcutil /t:metadata http://service/metadataEndpoint
Il comando seguente consente di generare i documenti di metadati per contratti di servizio tipi associati in un assembly.
svcutil myAssembly.dll
Il comando seguente consente di generare documenti di metadati per un servizio e tutti i contratti di servizio e tipi di dati associati in un assembly.
svcutil myServiceHost.exe /serviceName:myServiceName
Il comando seguente consente di generare documenti di metadati per tipi di dati in un assembly.
svcutil myServiceHost.exe /dconly
Il comando seguente consente di verificare l’host del servizio.
svcutil /validate /serviceName:myServiceName myServiceHost.exe
Il comando seguente consente di generare tipi di serializzazione per i tipi XmlSerializer utilizzati da qualsiasi contratto di servizio nell'assembly.
svcutil /t:xmlserializer myContractLibrary.exe
Problemi di protezione
È necessario utilizzare l'Elenco di controllo di accesso appropriato (ACL, Access Control List) per proteggere la cartella di installazione di Svcutil.exe, Svcutil.config e i file ai quali fa riferimento /svcutilConfig. Ciò può impedire la registrazione ed esecuzione di codice dannoso.
Per ridurre inoltre le probabilità che la sicurezza sia compromessa, non è necessario aggiungere estensioni non attendibili che entrino a far parte del sistema o utilizzare provider di codice non attendibili con Svcutil.exe.
Infine, non è necessario utilizzare lo strumento al livello intermedio dell'applicazione, in quanto ciò può provocare l’attacco Denial of Service al processo corrente.
Vedere anche
Riferimenti
DataContractAttribute
DataMemberAttribute
Altre risorse
How To: Create a Windows Communication Foundation Client Class