Run Dream as an embedded environment

It's pretty simple to create a custom Dream hosting environment.

First, you will need to link your project to the mindtouch.core.dll assembly.  Then, you should add a using statement to include the MindTouch.Dream namespace.

using MindTouch.Dream;

Now, you need to prepare an XML document to configure the Dream host service.  The following is a sample configuraiton document:

<config>
	<!-- Optional.  The official public uri for the dream environment. (default: http://localhost:8081) -->
	<uri.public>http://localhost/</uri.public>

	<!-- Optional.  The folder location where the service states are stored. (default: location of the dream host executable) -->
	<service-dir>/some/path/on/your/server</service-dir>

	<!-- Optional.  A key used to  access privileged operations to the server. (default: auto-generated 128-bit key) -->
	<apikey>123</apikey>

	<!-- Optional.  A 128-bit hexademical identifier used to uniquely identify the host. (default: auto-generated 128-bit key) -->
	<guid>c47aac17978841a1ae09a73fe4c6d7a7</guid>
</config>

Using the XDoc class, we could produce the above XML configuration very easily.

// lets use the folder this program is running in
string folder = System.IO.Path.GetDirectoryName(System.Reflection.Assembly.GetExecutingAssembly().GetModules()[0].FullyQualifiedName);
string apikey = StringUtil.CreateAlphaNumericKey(32); //generate a random api key

XDoc config = new XDoc("config");
config.Elem("uri.public", "http://localhost:8081/");
config.Elem("service-dir", folder);
config.Elem("apikey", apikey);

With this document created, we're ready to instantiate the Dream environment.

DreamHost host = new DreamHost(config);

Now we can use the host.Self property to interact with the Host service.  The Host service is used to register blueprints and start new service instances.  Let's configure the host to serve the Magic 8-ball sample.

// call the "load" service, with a parameter called "name" and value dream.sample.8ball with a POST and wait for the response
DreamMessage response = host.Self.At("load").With("name", "dream.sample.8ball").Post();

// generate a config file for the 8ball service just loaded
config = new XDoc("config");
config.Elem("path", "8ball");
config.Elem("sid", "http://services.mindtouch.com/dream/tutorial/2007/03/8ball");
            
// send the config file as the content of a POST to the "services" service to activate the new 8ball service.
response = host.Self.At("services").Post(config);
host.WaitUntilShutdown();

Note: the Post method and the other non-async methods will cause a compiler "obsolete" warning to be issued.  They're not really obsolete, but their use is frowned upon for real applications since they will block the curren thread.  These methods are simpler to use, but less efficient.