Discover Mono Web Services Safely with disco

Someone hands you a SOAP endpoint and says the WSDL is "somewhere behind the discovery URL". Mono's disco command fetches a DISCO document and the WSDL, XML schema and other DISCO documents it references. The normal run saves them to a directory, and a dry inspection can skip saving altogether. Allow about ten minutes for a first run, plus time to get the correct DISCO URL and any credentials from the service owner.

The route

Jump straight to the step you need, or tick off Done means at the end.

1. Check the installed command
2. Inspect without writing files
3. Save a discovery result in a dedicated directory
4. Use HTTP credentials carefully
5. Recover from a bad or unwanted run
6. Diagnose the usual failures

This guide covers the disco shipped by Ubuntu's mono-devel package, version 6.8.0.105+dfsg-3.6ubuntu2 on the machine used for these examples. The installed tool identifies itself as Mono Web Service Discovery Tool 6.8.0.105. Older or newer Mono releases may differ, so check the local help before you put a command in a script.

1. Check the installed command

Run these as your ordinary user. Discovery is normally a read and write job, not an administrative one:

$ command -v disco
/usr/bin/disco
$ disco --help
Mono Web Service Discovery Tool 6.8.0.105
Usage: disco [options] url

The manual calls the positional argument url. It must point to a DISCO document, not just a service's home page or an arbitrary WSDL. If the service owner gave you a discovery URL, use that exact URL.

Checkpoint

You have a readable DISCO URL and disco --help reports the installed version. If either is missing, stop and fix that first.

2. Inspect without writing files

Use -nosave to test access without leaving downloaded documents in the current directory. The URL below is a placeholder, so replace it with the real endpoint:

$ disco -nologo -nosave https://services.example.invalid/discovery.disco

-nologo removes the startup logo from terminal output. It does not change discovery.
-nosave stops the discovered documents being saved. The command still has to retrieve and process the DISCO document and its references.
A successful exit is the useful result. The diagnostic output depends on the remote server and the installed Mono libraries.

Tip

A failed connection does not prove the URL is valid but empty. Check the hostname, path, proxy requirement and server access separately, and do not add credentials just because an endpoint failed to resolve.

3. Save a discovery result in a dedicated directory

By default, disco saves documents in the current directory. That is easy to miss, and it can scatter WSDL and schema files among your source code. Create an empty working directory and send the output there:

$ mkdir -p "$PWD/mono-discovery"
$ disco -nologo -out:"$PWD/mono-discovery" https://services.example.invalid/discovery.disco
$ find "$PWD/mono-discovery" -maxdepth 1 -type f -print

The long option is -out:directory, and the manual also accepts -o:directory. The installed help shows the same option in a shortened form. Quote a directory containing spaces, and use an absolute or deliberately chosen path in scripts.

The result depends on the DISCO document. Expect referenced WSDL documents, XML schemas and possibly more DISCO documents, but do not assume particular filenames. Inspect the files before passing them to another tool:

$ find "$PWD/mono-discovery" -maxdepth 1 -type f -exec file -- {} \;
$ find "$PWD/mono-discovery" -maxdepth 1 -type f -exec sed -n '1,8p' -- {} \;

The second command suits text XML files, but it can be noisy if the directory holds non-XML content.

Warning

Do not treat a file's name as proof that it is trustworthy. Discovery downloads content from the endpoint and its references. Review the URLs and files before you use them to generate client code.

Checkpoint

The output directory holds only the documents you expected, and you have checked the exit status. If it is empty after a successful-looking run, rerun with the directory explicitly set and inspect the endpoint response.

4. Use HTTP credentials carefully

The tool supports a username, password and domain for the remote connection:

$ disco -nologo \
    -out:"$PWD/mono-discovery" \
    -user:ACCOUNT -password:'REPLACE_WITH_PASSWORD' -domain:EXAMPLE \
    https://services.example.invalid/discovery.disco

The syntax is a colon followed by the value, for example -user:ACCOUNT.

Security warning

The password is exposed in the process argument list and may be recorded by shell history or process-monitoring tools. Do not paste a real password into a shared terminal, a ticket, a script or a command copied into source control. If the service supports a safer non-interactive authentication method, use that as its own documentation describes. If you must use this option temporarily, remove the command from shell history by your shell's normal procedure, and rotate the credential if it was exposed.

-proxy:url, -proxyusername:username, -proxypassword:password and -proxydomain:domain configure an HTTP proxy. The proxy credentials carry the same exposure risk. A proxy setting does not replace service authentication, and service credentials do not replace proxy authentication.

5. Recover from a bad or unwanted run

Discovery does not modify the remote service, but it does create local files when saving is on. If the output is wrong, keep the original input and remove only the dedicated output directory, after checking its path:

$ find "$PWD/mono-discovery" -maxdepth 1 -type f -print
$ rm -rf -- "$PWD/mono-discovery"
$ test ! -e "$PWD/mono-discovery" && echo 'discovery directory removed'

Warning

rm -rf is irreversible. Do not run it with an unreviewed variable, a broad path or your working directory. If the files may be useful, move the directory to a clearly named archive instead, or keep it and run the next attempt in a new directory.

For a repeatable run, use a new output directory and compare the documents before replacing anything a build or client generator already consumes. A non-zero exit status means the run did not complete. Discard the partial output or quarantine it. Do not treat it as a complete service description.

6. Diagnose the usual failures

Unknown option. Compare the command with disco --help. The manpage documents short and long spellings for several options, including -o:directory and -out:directory, and -u:username and -user:username. Use the long spelling in shared instructions, because it makes the value's purpose clearer.
Connection failure. Verify the URL with the service owner, confirm DNS and proxy access, and check whether the endpoint needs credentials.
Authentication failure. Do not keep guessing passwords. Confirm the account, domain and server authentication scheme, then retry once with a credential-handling method approved for that environment.
References fail after the first document loads. The DISCO file may contain inaccessible or incorrect URLs. Inspect the saved XML, ask the owner for a corrected document, and do not silently substitute unrelated WSDL files.
Unexpected remote locations in the output. Stop before you generate code from it.

Done means

Tool known: disco is installed and you know its local version and options.
Dry run first: you tested the correct DISCO URL with -nosave before saving files.
Contained output: saved documents went into a dedicated, reviewed directory.
Secrets safe: service or proxy credentials never appeared as real secrets in shared commands.
Checked downstream: you checked the exit status and reviewed referenced documents before using them.
Clean exit route: you can quarantine or remove partial output without touching unrelated files.