Where’s Lou

Hello again! Now let’s talk about Ghost.exe.

As you may be aware – OWIN can be thought of as a port of Rack or WSGI specification to .NET, and Gate can be thought of as a reference implementation the of Rack utility and middleware library.

If you’ve used Rack then you’re probably familiar with the rackup executable. It provides a way to load a web site and run it on a web server that doesn’t provide it’s own executable. That is more or less the role Ghost.exe plays in the overall OWIN/Gate suite.

By now you’re thinking, “That’s awesome, stop typing and tell me how to get some of that!” and the easiest way is with Chocolatey – a nuget-based software distribution mechanism. The easiest way to get Chocolatey is from the VS Package Manager Console.

Step one: get Chocolatey

PM> Install-Package chocolatey
Successfully installed 'chocolatey 0.9.8.14'.

PM> Initialize-Chocolatey
The repository is set up at 'C:\NuGet'.
The packages themselves go to 'C:\NuGet\lib' (i.e. C:\NuGet\lib\yourPackageName).
Run chocolatey /? for a list of functions.

PM> Uninstall-Package chocolatey
Successfully uninstalled 'chocolatey 0.9.8.14'.

The output text is heavily edited down – it does mention you may need to restart powershell for path changes to take effect. Actually – let’s leave VS and jump right to a new command prompt which should avoid that problem.

Step two: install ghost

C:\Users\lodejard>chocolatey install ghost
=====================================================
Chocolatey (0.9.8.14) is installing ghost (from http://chocolatey.org/api/feeds/
 OR https://go.microsoft.com/fwlink/?LinkID=206669) to "C:\NuGet\lib"
=====================================================

Step three: run ghost

This is using the OWIN web app we made in the last post.

C:\Users\lodejard>cd \Projects\Experiments\HelloEverything\HelloEverything

C:\Projects\Experiments\HelloEverything\HelloEverything>ghost --server kayak
Started at http://+:8080/

Press Esc when you want to exit the Ghost.exe – but other than that you can browse to http://localhost:8080 and see the quickstart web site we created in the last blog post in all its glory. This should work if you run Ghost with the current directory at the base path for a “web app” or “class library” project which (a) compiles it’s output to a bin directory, and (b) one of the assemblies has a public Startup class in that assembly’s base namespace.

You need to follow the (b) convention if you don’t name the Startup method on the command line. Otherwise you can start an alternate environment by providing that. In fact – let’s add simple trace logging to the Startup.Debug method. This can be edited right into the example file the quickstart added to the project.

public void Debug(IAppBuilder builder)
{
    // added to trace some request values as they pass through
    builder.Use(ShowRequests);

    builder.UseShowExceptions();
    Configuration(builder);
}

// simple user-middleware
AppDelegate ShowRequests(AppDelegate app)
{
    // this delegate is called per request
    return (env, result, fault) =>
    {
        // use a light wrapper class to access env dictionary as properties
        var req = new Request(env);

        // trace out some info
        req.TraceOutput.WriteLine(
            "{0} {1}{2} {3}", req.Method, req.PathBase, req.Path, req.QueryString);

        // and then pass all request along
        app(env, result, fault);
    };
}

You can select that configuration by running it as follows. Let’s use the firefly server this time.

C:\...\HelloEverything>ghost --server firefly HelloEverything.Startup.Debug
Started at http://+:8080/
GET /
GET /wilson
GET /wilson flip=crash

Also be sure to run Ghost /? to check out the options as well. Currently supported http servers include the default HttpListener (the default), Kayak, and Firefly. Remember to set the url acls for your port if you’re going to be using HttpListener.

C:\Projects\Experiments\HelloEverything\HelloEverything>ghost /?
Usage: Ghost [options] [<application>]
Runs <application> on an http server
Example: Ghost -p8080 HelloWorld.Startup

Options:
  -s, --server=VALUE         Load assembly named "Gate.Hosts.TYPE.dll" to
                               determine http server to use. TYPE defaults to
                               HttpListener.
  -u, --url=VALUE            May be used to set --scheme, --host, --port, and
                               --path options with a combined URIPREFIX value.
                               Format is '<scheme>://<host>[:<port>]<path>/'.
  -S, --scheme=VALUE         Determine which socket protocol server should
                               bind with. SCHEME may be 'http' or 'https'.
                               Defaults to 'http'.
  -h, --host=VALUE           Which host name or IP address to listen on. NAME
                               defaults to '+' for all IP addresses.
  -p, --port=VALUE           Which TCP port to listen on. NUMBER defaults to
                               8080.
  -P, --path=VALUE           Determines the virtual directory to run use as
                               the base path for <application> requests. PATH
                               must start with a '/'.
  -o, --output=VALUE         Writes any errors and trace logging to FILE.
                               Default is stderr.
  -v, --verbose              Increase the output verbosity.
  -?, --help                 Show this message and exit.

Environment Variables:
PORT                         Changes the default TCP port to listen on when
                               both --port and --url options are not provided.
OWIN_SERVER                  Changes the default server TYPE to use when
                               the --server option is not provided.