3.3 IIS Configuration

Platibus applications can be hosted in ASP.NET web applications to take advantage of the more robust pooling and security features provided by IIS. This configuration is recommended for ASP.NET applications or applications that require HTTPS.

Option 1: HTTP Handler

The simplest way of handling Platibus requests is to register the Platibus.IIS.PlatibusHttpHandler in web.config. This handler will initialize itself using the IISConfigurationSection named <platibus.iis> and any configuration hooks present in the assemblies in the app domain base directory.

The name and path are not important; however, the path must agree with the baseUri specified in the Platibus IIS configuration.

To register the Platibus HTTP handler, add an element to the <handlers> collection in the <system.webServer> configuration section:

<system.webServer>
    <handlers>
        <add name="platibus" verb="*" path="platibus" type="Platibus.IIS.PlatibusHttpHandler, Platibus.IIS" />
    </handlers>
</system.webServer>

Option 2: HTTP Module

Requests can also be handled using the PlatibusHttpModule. The module is also initialized with the IISConfigurationSection named <platibus.iis> and any configuration hooks present in the app domain. However, the HTTP module does not require an explicit path and verbs--it identifies Platibus requests by comparing the leftmost portion of the request URL to the baseUri specified in the <platibus.iis> configuration section.

To register the Platibus HTTP handler, add an element to the <handlers> collection in the <system.webServer> configuration section:

<system.webServer>
    <modules>
        <add name="platibus" type="Platibus.IIS.PlatibusHttpModule, Platibus.IIS" />
    </modules>
</system.webServer>

Initializing the HTTP module programmatically

If more control is needed over the HTTP module initialization process (for example, if dependencies need to be injected into the module via a container, or there is a need to subclass or wrap PlatibusHttpModule) the module can be initialized in the Init method of Global.asax:

public class MvcApplication : HttpApplication
{
	private static PlatibusHttpModule _platibusHttpModule;

	protected void Application_Start()
	{
		AreaRegistration.RegisterAllAreas();
		RouteConfig.RegisterRoutes(RouteTable.Routes);
		BundleConfig.RegisterBundles(BundleTable.Bundles);

		// Instantiate in Application_Start to ensure only one
		// instance is created
		_platibusHttpModule = new PlatibusHttpModule();
	}

	public override void Init()
	{
		base.Init();

		// Initialize in Init() method to ensure HttpContext is
		// properly initialized
		_platibusHttpModule.Init(this);
	}

	protected void Application_Shutdown()
	{
		// Ensure background tasks are canceled
		if (_platibusHttpModule != null)
		{
			// Dispose is idempotent and safe to call multiple times
			_platibusHttpModule.Dispose();
		}
	}
}

Authentication

Authentication is handled by IIS and can be configured via the <authentication> element of the <system.web> configuration section. For example, to use Windows authentication, specify the following:

<system.web>
    <authentication mode="Windows" />
</system.web>

Platibus IIS Configuration

The IIS configuration closely resembles the HTTP server configuration sans the authenticationSchemes element. The bootstrap initialization logic in HTTP handler expects the configuration section name to be platibus.iis.

Declarative configuration example:

<configuration>
    <configSections>
        <section name="platibus.iis" type="Platibus.IIS.IISConfigurationSection, Platibus.IIS" />
    </configSections>
    <platibus.iis baseUri="http://crm.example.com:52180/platibus" replyTimeout="00:00:30">
        <queueing provider="SQLite" path="platibus\queues" />
        <subscriptionTracking provider="Filesystem" path="platibus\subscriptions" />
        <endpoints>
            <add name="provisioning" address="http://provisioning.example.com:52180/platibus/" />
        </endpoints>
        <topics>
            <add name="CustomerEvents" />
            <add name="OrderEvents" />
        </topics>
        <sendRules>
            <add namePattern=".*Provision.*" endpoint="provisioning" />
        </sendRules>
        <subscriptions>
            <add endpoint="provisioning" topic="ProvisioningEvents" />
        </subscriptions>
    </platibus.iis>
</configuration>

Authorization Service

The authorization service is an optional component that can be used to restrict a remote caller's ability to send messages or subscribe to topics. If a Basic authentication scheme is used, then an authorization service may be needed to authenticate the supplied credentials (see Platibus.Http.BasicAuthorizationService).

Programmatic example:

public class CustomAuthorizationService : BasicAuthorizationService
{
    public bool Authenticate(string username, string password)
    {
        // Verify credentials against a database, etc.
        return true;
    }
}

public class ConfigurationHook : IConfigurationHook
{
    public void Configure(PlatibusConfiguration configuration)
    {
        var iisConfiguration = configuration as IISConfiguration;
        if (iisConfiguration != null)
        {
            var authorizationService = new CustomAuthorizationService();
            iisConfiguration.AuthorizationService = authorizationService;
        }
    }
}

Message Queueing Service

The message queueing service provides the IIS hosted instance with a means of persisting important messages until they are successfully processed (outbound messages are queued until they are successfully sent; inbound messages are queued until they are acknowledged). The message queueing service can be specified declaratively or programmatically.

See 3.4 Message Queueing for more details.

Declarative example:

<platibus.iis>
    <queueing provider="Filesystem" path="C:\platibus\queues"/>
</platibus.iis>

Programmatic example:

public class ConfigurationHook : IConfigurationHook
{
    public void Configure(PlatibusConfiguration configuration)
    {
        var iisConfiguration = configuration as IISConfiguration;
        if (iisConfiguration != null)
        {
            var path = @"C:\platibus\queues";
            var messageQueueingService = new FilesystemMessageQueueingService(path);
            iisConfiguration.MessageQueueingService = messageQueueingService;
        }
    }
}

A variety of message queueing service implementations are provided. See the message queueing section for configuration details.

Subscription Tracking Service

The subscription tracking service enables the IIS hosted instance to persist subscription information so that copies of published messages can be sent to subscribers. The subscription tracking service can be specified declaratively or programmatically.

Declarative example:

<platibus.iis>
    <subscriptionTracking provider="Filesystem" path="C:\platibus\subscriptions"/>
</platibus.iis>

Programmatic example:

public class ConfigurationHook : IConfigurationHook
{
    public void Configure(PlatibusConfiguration configuration)
    {
        var iisConfiguration = configuration as IISConfiguration;
        if (iisConfiguration != null)
        {
            var path = @"C:\platibus\subscriptions";
            var subscriptionTrackingService = new FilesystemSubscriptionTrackingService(path);
            iisConfiguration.SubscriptionTrackingService = subscriptionTrackingService;
        }
    }
}

A variety of subscription tracking service implementations are provided. See the subscription tracking section for configuration details.