Generate a C# Web Service Proxy with Mono wsdl

Nobody wants to hand-write SOAP client code, and Mono's wsdl turns a WSDL document into a C# proxy in one command. You choose the namespace and the output path, and can inspect the result before it ever compiles. The examples use the wsdl command from Mono 6.8.0.105, supplied by mono-devel on this machine.

Allow about fifteen minutes for a first generation and review. You need a readable WSDL file, the Mono development tools, and a writable working directory. The command can also read a URL, but a checked local copy is easier to review and gives you a stable input for a build.

Scope: this is Mono's generator for the 1.x API. The manual directs 2.x API work to wsdl2. Do not silently substitute one for the other in a build.

1. Check the installed tool

Confirm which executable your shell will run and record the package version. These are ordinary, read-only commands and do not need sudo:

$ command -v wsdl
/usr/bin/wsdl
$ dpkg-query -W -f='${Package} ${Version}\n' mono-devel
mono-devel 6.8.0.105+dfsg-3.6ubuntu2
$ wsdl --version
Error: Unknown option version

That last result is useful: this installed program has no --version option. Identify it through the package manager instead. Its normal startup text reports the Mono Framework version when generation begins.

2. Keep the input and output separate

Choose a new output filename. Shell redirection is not involved, because wsdl writes the generated source itself when you use -out or -o:

$ mkdir -p ~/src/generated
$ test -r /path/to/service.wsdl && echo 'WSDL is readable'
WSDL is readable

Replace /path/to/service.wsdl with the actual path. Do not edit the source WSDL in place while testing. If it came from a supplier or a build artefact, keep an untouched copy so a later comparison can tell an input change from a generator change.

3. Generate a namespaced C# proxy

Run the generator with the input path, an explicit namespace, and a fresh output path:

$ wsdl \
    -n:Example.Client \
    -o:$HOME/src/generated/ExampleProxy.cs \
    /path/to/service.wsdl
Web Services Description Language Utility
Mono Framework v4.0.30319.42000
Writing file '/home/you/src/generated/ExampleProxy.cs'

-n:name sets the namespace for generated classes. -o:filename chooses the target file. The option values are attached with a colon, as shown; the long forms are -namespace:name and -out:filename. The exact startup and path text may vary, but a zero exit status and a written file are the checks that matter.

$ test -s "$HOME/src/generated/ExampleProxy.cs" && echo 'proxy source exists and is non-empty'
proxy source exists and is non-empty
$ sed -n '1,24p' "$HOME/src/generated/ExampleProxy.cs"
//------------------------------------------------------------------------------
// <auto-generated>
//     This code was generated by a tool.
// ...
namespace Example.Client {

The generated file is source code, not a compiled client and not a server. It normally contains types such as SoapHttpClientProtocol derivatives and XML serialisation metadata. Review the service endpoint, operations and types before compiling or calling anything.

4. Select the protocol deliberately

SOAP is the default protocol. Keep the default for an ordinary SOAP WSDL, or select one of the alternatives explicitly:

$ wsdl -l:CS -p:Soap -n:Example.Client \
    -o:$HOME/src/generated/ExampleProxy.cs /path/to/service.wsdl

-l:language selects the output language: CS is the default, with Boo and VB also listed by the manual. -p:protocol accepts Soap, HttpGet or HttpPost. An option like this can change the shape of generated calls and sample messages, so do not pick HTTP GET or POST merely because the service happens to have an HTTP URL.

5. Treat credentials and remote input as sensitive

The -u, -p and -d options supply a username, password and domain while connecting to a server. A password on a command line can be exposed through shell history, process inspection or CI logs. Prefer a protected execution context and a short-lived account if the remote WSDL requires authentication; never paste a production password into a shared transcript.

A URL input can cause the tool to download referenced schemas or other WSDL documents. Review the URL and the resulting files before generation, and use a local copy when reproducibility matters. Network access is not a reason to run the generator as root.

6. Recover from a bad generation

$ cp --preserve=all "$HOME/src/generated/ExampleProxy.cs" \
    "$HOME/src/generated/ExampleProxy.cs.bak"
$ wsdl -n:Example.Client \
    -o:$HOME/src/generated/ExampleProxy.cs.new \
    /path/to/service.wsdl
$ test -s "$HOME/src/generated/ExampleProxy.cs.new"
$ mv "$HOME/src/generated/ExampleProxy.cs.new" \
    "$HOME/src/generated/ExampleProxy.cs"

If generation fails, the .new file is the disposable candidate. Leave the previous proxy in place, inspect the error and check that the WSDL and every referenced schema are readable. To undo the replacement, restore the backup with mv after checking its path. Remove the backup only once the new source has compiled and passed your tests.