Hosting Behaviour

LightBlue provides two forms of hosting. Direct hosting runs code inside a LightBlue host process. This is used for Worker roles and the background process of Web roles. Indirect hosting is used the web hosting of Web roles. It uses an IIS Express instance started by the LightBlue web host.

Direct hosting

The process followed to directly host a role is:

1. Remove the Azure Trace Listener from role configuration (if present). This listener will not operate outside actual Azure or the emulator and cannot be removed programmatically.
2. Copy the LightBlue.Host.Stub assembly into the role directory.
3. Create an AppDomain using the role directory and configuration file.
4. Create an instance of HostStub in the AppDomain and call its Run method.
5. Locate the LightBlue.dll and create an instance of HostRunner
6. Configure the AppDomain for LightBlue. This involves setting up global state by calling LightBlueConfiguration.SetAsLightBlue
7. Locate the type in the role assembly that inherits from RoleEntryPoint and create an instance of it.
8. Create a new thread and use that call OnStart and Run on the RoleEntryPoint instance.
9. In the main thread wait for the child thread to complete then call OnStop on the RoleEntryPoint instance.

The use of a child thread is necessary for correct behaviour of the AppDomain.UnhandledException handler. Roles will want to hook up to this handler to provide last chance handling for unhandled exceptions. If the main thread is used then the handler in the role AppDomain is never called, instead the handler in the original AppDomain is called. The role does not have access to the original AppDomain and should not be aware of its existence as it exists only when in LightBlue.

LightBlue must use MarshalByRefObject to communicate across AppDomain boundaries. Limitations in this mechanism mean that whatever type is created in the AppDomain for this purpose must be something that the host process has a reference to when compiled or the necessary methods are not made available. It is undesirable the host references a specific version of the LightBlue assembly. This could cause issues if the version differs as the role will not necessarily run against the version it expects. The solution is the LightBlue.Host.Stub assembly. This is a relatively stable assembly that the host can be built against. It is copied into the role directory and performs minimal bootstrapping by loading the LightBlue assembly that the role uses. This is loaded dynamically which allows different versions to work provided they have the expected contract.

Indirect hosting

Indirect hosting uses IIS Express to host web roles (as OWIN is currently not viable for hosting ASP.NET and WCF). This is started by the web host using the process:

1. Remove the Azure Trace Listener from web.config (if present). This listener will not operate outside actual Azure or the emulator and cannot be removed programmatically.
2. Generate an IIS Express configuration file that specifies the site directory, hostname, port and protocol.
3. Start the IIS Express process passing a number of environment variables:

• LightBlueHost Set to "true" to indicate that the role is operating in a LightBlue context.
• LightBlueConfigurationPath The path to the configuration file. Used to parse the settings.
• LightBlueServiceDefinitionPath The path to the ServiceConfiguration.csdef file. Used to parse the role resources and (depending on host parameters) the hostname and port for the web role from the endpoint.
• LightBlueRoleName The name of the role, used to look up the settings, resources and endpoint.
• TMP and TEMP Set the temporary directory to be a subdirectory of the LightBlue data directory.

Initialisation of LightBlue will be performed on the first access to LightBlueContext (this is performed automatically when performing IoC registration).