Andrew Cherry on Software and Technology

Orchard Shell Activation

2011-09-13T00:00:00-07:00

This is part 3 of a series on Orchard Internals. See the introductory post for previous posts (and a full post listing).

Overview

In part 2 we looked at the initialization of the Orchard host, and how that created new shell contexts and shells to host Orchard sites. We left off at the point where a host was pretty much complete and Orchard was ready to begin serving requests, but we skipped over the activation of our actual shells. We’re going to look in there in this article, and see what happens on that call to Activate on our shell once it’s been created.

DefaultOrchardShell

We can see from our dependency registrations that our instance of IOrchardShell is going to be an instance of DefaultOrchardShell, which is found in Environment/DefaultOrchardShell.cs. We’ll take a look at that now. First of all, let’s look at the constructor:

public DefaultOrchardShell(
    Func<Owned<IOrchardShellEvents>> eventsFactory,
    IEnumerable<IRouteProvider> routeProviders,
    IRoutePublisher routePublisher,
    IEnumerable<IModelBinderProvider> modelBinderProviders,
    IModelBinderPublisher modelBinderPublisher) {
    _eventsFactory = eventsFactory;
    _routeProviders = routeProviders;
    _routePublisher = routePublisher;
    _modelBinderProviders = modelBinderProviders;
    _modelBinderPublisher = modelBinderPublisher;

    Logger = NullLogger.Instance;
}

We wouldn’t normally be too interested in this — it’s standard constructor injection in IoC. But it’s worth remembering that this instance of DefaultOrchardShell was resolved in the shell scope, so those dependencies are shell scoped dependencies. It’s also worth remembering that the dependencies at the shell level aren’t necessarily ones that have been registered in the traditional way, as seen in OrchardStarter. They’ve probably been registered in the Orchard way, by finding dependencies that implement IDependency and the related family of interfaces. This means that we can’t look up dependencies quite as easily, as they’re now being registered dynamically.

For example, let’s look at the instance of IRoutePublisher which is a constructor dependency. That interface looks like this:

namespace Orchard.Mvc.Routes {
    public interface IRoutePublisher : IDependency {
        void Publish(IEnumerable<RouteDescriptor> routes);
    }
}

We can see that it implements IDependency, so that any class which implements that interface will be automatically registered as a dependency. In this case that class is RoutePublisher in the Orchard.Framework project, found in Mvc/Routes/RoutePublisher.cs. It was dynamically registered as a dependency when we were creating our shell lifetime scope, and when we resolved our shell instance, it was resolved from that scope. This is a good thing to remember and be aware of.

Activation

Once we’ve got our DefaultOrchardShell instance, the host is going to call Activate when we’re initializing our host, as we’ve seen in previous posts. Happily, the Activate method looks pretty straightforward, like this:

public void Activate() {
    _routePublisher.Publish(_routeProviders.SelectMany(provider => provider.GetRoutes()));
    _modelBinderPublisher.Publish(_modelBinderProviders.SelectMany(provider => provider.GetModelBinders()));

    using (var events = _eventsFactory()) {
        events.Value.Activated();
    }
}

Not too much going on — publishing the routes and model binders which are part of our site. (We also do some work with events, (IOrchardShellEvents) which we’ll look at later on. Before then, let’s look at how routes work within a shell.

Routes and Shells

As we can see, routes are published on a per shell basis, so routes can be different between tenants. We also know from the first article that routes are not registered as part of our main web application as they often are in ASP.NET MVC web applications.

Routes in Orchard are registered by implementing IRouteProvider in modules. Looking at that interface, unsurprisingly it implements IDependency. This means that DefaultOrchardShell can take a constructor dependency on IEnumerable<IRouteProvider> and get back all of the routes which need to be registered for all modules, thanks to the IoC implementation scanning all of the loaded modules.

It simply calls GetRoutes on each of them and then sends the resulting collection of RouteDescriptor instances off to the route publisher to be published (registered) for our shell.

There’s a bit more though. Routes in an ASP.NET MVC 3 application are global — there’s only one actual site here, despite the multi-tenancy possibilities, so how are we making sure that only the routes for our shell are used to get to our tenant?

This is where Orchard can go back and take advantage of some of the extensibility options built in to the ASP.NET MVC 3 framework. When you register a route in ASP.NET MVC 3, the method signature on the RouteCollection actually takes a RouteBase, which can be extended. So the route publisher actually orders the RouteDescriptor instances it has (by the Priority property which you can set when registering routes — as the order of routes is important in ASP.NET MVC 3) and then turns each route descriptor in to an instance of ShellRoute, which extends RouteBase.

It’s worth seeing what ShellRoute is and how it works as the principle could be applied elsewhere. It can be found in Mvc/Routes/ShellRoute.cs in the Orchard.Framework project.

The crucial points in here are that it overrides GetRouteData and GetVirtualPath to ensure that the route only responds and matches if the request is for the right shell. It does this with the following code at the start of each of those methods:

// locate appropriate shell settings for request
var settings = _runningShellTable.Match(httpContext);

// only proceed if there was a match, and it was for this client
if (settings == null || settings.Name != _shellSettings.Name)
    return null;

It’s checking to see whether there’s a match between the settings of the current request, which it can get from the running shells table which we saw previously, and the shell settings for this particular shell (_shellSettings, which it got as a constructor dependency). If there’s no match, it returns null which tells ASP.NET MVC 3 that this route doesn’t match this request. There’s a bit more cleverness in here around making sure that paths can be found based on the location of the module itself, which you can have a glance at in here if you’re interested!

For now though, we’ll content ourselves with knowing how the routes are registered on a per shell basis and then how they behave during a request to the application, based on which shell the request was for.

Model Binders and Shells

If we go back to our DefaultOrchardHost the next line after publishing our routes was registering model binders. This is another ASP.NET MVC concept and the way we’re doing this looks very similar to the way Orchard handled the routes.

In fact it’s pretty much exactly the same, meaning we don’t need to dive in to this too far, except to note one thing — it isn’t really implemented! Our ModelBinderPublisher actually looks like this:

public class ModelBinderPublisher : IModelBinderPublisher {
    private readonly ModelBinderDictionary _binders;

    public ModelBinderPublisher(ModelBinderDictionary binders) {
        _binders = binders;
    }

    public void Publish(IEnumerable<ModelBinderDescriptor> binders) {
        // MultiTenancy: should hook default model binder instead and rely on shell-specific binders (instead adding to type dictionary)
        foreach (var descriptor in binders) {
            _binders[descriptor.Type] = descriptor.ModelBinder;
        }
    }
}

As you can see, it doesn’t really deal with multi-tenancy for model binders yet — Orchard is only at version 1.2xxx after all! In practice it probably isn’t a problem, but you’ll know where to look if it is, or when it gets implemented.

Orchard Events

The last part of the Activate method in the shell was this:

using (var events = _eventsFactory()) {
    events.Value.Activated();
}

It’s using _eventsFactory, which is a function it acquired as a constructor dependency, to get an instance of IOrchardShellEvents, and calling the Activated method on it.

This can be used to signal changes in application status to allow things like background tasks (which will be covered in another article) to take actions at key points in the application lifecycle.

Activation Complete!

That’s essentially it for the shell activation. As always I’d encourage you to go and dive deeper in to the source around the parts I’ve called out here — there’s a lot of interesting code although I’ve tried to highlight the most relevant parts.

We’ve seen how the shell registers routes and binders when it starts up in such a way as to have them only apply to the correct shell. We also saw how the dependency system influences the design of the framework here — recall how the IoC implementation made it easy for Orchard to get all of the route providers that had been implemented across all relevant modules.

Hopefully you’ll come back for the next article, which is going to start to look at the request lifecycle — now that we’ve got our application up and running. It’ll be linked from the overview once it’s ready.

Orchard Host

2011-09-01T00:00:00-07:00

This is part 2 of a series on Orchard Internals. See the introductory post for previous posts (and a full post listing).

Overview

In part 1 of this series we looked at the startup process in Orchard, as far as obtaining and initializing a host (IOrchardHost, by default an instance of DefaultOrchardHost). We saw it get initialized and become a key root point of the application but we didn’t look inside it and see what’s happening on initialization. Well — now we will.

DefaultOrchardHost

Let’s go and have a look at DefaultOrchardHost — it’s in the Orchard.Framework project in Environment/DefaultOrchardHost.cs. It’s a good job Orchard is using IoC to create instances of this — looking at the constructor it probably wouldn’t be fun to manage that many dependencies manually!

We saw that Initialize gets called as part of the startup process — that’s pretty simple, and aside from some logging it just calls BuildCurrent. That looks a bit more interesting though, like this:

IEnumerable<ShellContext> BuildCurrent() {
    if (_current == null) {
        lock (_syncLock) {
            if (_current == null) {
                SetupExtensions();
                MonitorExtensions();
                _current = CreateAndActivate().ToArray();
            }
        }
    }
    return _current;
}

We’ll ignore the locking as that’s self-explanatory — we only want to initialize _current once regardless of threading. So we’re left with a couple of calls relating to extensions, and then a call which creates “some” ShellContexts. It looks like there’s a lot to this — we’ll take a look at extensions first.

Extensions

Thankfully the naming of the methods in Orchard is generally self-explanatory. SetupExtensions does what we’d expect — it calls a method to setup extensions on _extensionLoaderCoordinator, one of the dependencies that the host acquired on construction. What does that actually do though? First we’ll need to look at what implementation of IExtensionLoaderCoordinator we’re getting and we can see from a look at our dependency registrations (see part 1 for where these are) that this is being implemented by ExtensionLoaderCoordinator which is at Environment/Extensions/ExtensionLoaderCoordinator.cs in the Orchard.Framework project.

Now we can see that it’s starting to get a bit more complex! To sum it up, this is where one of the features of Orchard comes in to play, the dynamic compilation, loading and management of extensions — at runtime. What’s an extension in this case? Well we’re probably more used to saying Modules and Themes, but they’re both a form of extension.

I’m not going to dive in to the details of the extension discovery, compilation and loading mechanisms as part of this article — it’s a big enough area that it needs an article all to itself which will be coming later on. For now we’ll skim over this and say that Orchard is finding any Modules and Themes by looking in some predefined directories and then loading them in to the AppDomain so that they’re available for Orchard to use. MonitorExtensions is part of this same process — it monitors the available extensions on disk (in the previously mentioned directories) and reloads them if they change.

That’s simplifying quite a large and complex process, but it’s enough to give us a feel for what’s happening at the host level. We can now move on to the last key line of BuildCurrent, the call to CreateAndActivate.

Orchard Shells

Let’s start by looking at that CreateAndActivate method:

IEnumerable<ShellContext> CreateAndActivate() {
    Logger.Information("Start creation of shells");

    IEnumerable<ShellContext> result;
    var allSettings = _shellSettingsManager.LoadSettings();
    if (allSettings.Any()) {
        result = allSettings.Select(
        settings => {
            var context = CreateShellContext(settings);
            ActivateShell(context);
            return context;
        });
    }
    else {
       var setupContext = CreateSetupContext();
       ActivateShell(setupContext);
       result = new[] {setupContext};
    }

    Logger.Information("Done creating shells");
    return result;
}

We’ll ignore the obvious bits like logging. We start by getting any ShellSettings instances that the _shellSettingsManager (an instance of IShellSettingsManager that came in as a constructor dependency). If we have any instances, we create one ShellContext for each instance, activating each as we go. We then return that list of activated shell contexts. If we didn’t have any instances of ShellSettings we just create a new shell context (with some default settings), activate it, and return that (as the only member of an array of shell contexts).

We’ll look at what creating a shell entails in a moment but let’s look first at why sometimes we might have some instances of ShellSettings and sometimes not. Our instance of IShellSettingsManager is responsible here, so let’s see what implementation is being used. Looking at our dependencies it’s ShellSettingsManager which can be found in Environment/Configuration/ShellSettingsManager.cs.

Let’s take a look in there and see why we would (or wouldn’t) have any shell settings.

ShellSettingsManager

We get our shell settings by calling the LoadSettings method in this class. Let’s have a look:

IEnumerable<ShellSettings> LoadSettings() {
    var filePaths = _appDataFolder
        .ListDirectories("Sites")
        .SelectMany(path => _appDataFolder.ListFiles(path))
        .Where(path => string.Equals(Path.GetFileName(path), "Settings.txt", StringComparison.OrdinalIgnoreCase));

    foreach (var filePath in filePaths) {
        yield return ParseSettings(_appDataFolder.ReadFile(filePath));
    }
}

While it uses quite a few Orchard classes to do it, what this method is doing is actually quite straightforward. It’s finding all of the directories in the Sites directory in our App_Data folder which contain a file called Settings.txt. For each one that it finds, it parses the Settings.txt file in to a ShellSettings instance and returns it. That’s pretty straightforward, so in what cases would we end up with differing numbers?

The first case, where we have no instances of ShellSettings, is simple. The Orchard installer process has not yet created the default site (a directory called “Default” under the Sites directory). Once that’s been run and the site has gone through the initial setup, you’ll always have at least one instance of ShellSettings when this gets called. So we’d only see no instances of ShellSettings on our first run (or until we’ve got a site set up).

The final case is having more than one instance. For this to happen we’d need to have more than one site set up in our Sites directory. Why would we have this? This would be the case if we were running Orchard with multi-tenancy enabled, and we’d set up multiple tenants for our Orchard site. Each tenant would be another directory in Sites with separate settings. By default Orchard doesn’t load this module, but it can be turned on like any other if it’s installed.

Multi-tenancy is another big topic to cover, and it will get an article all to itself later on, but if you’re curious now, the Orchard.MultiTenancy project (module) is where the magic happens for this. For now, we’ll take it as read that we might have multiple shells running, allowing us to run multiple distinct sites within one instance of Orchard.

Now that we’ve seen where shell settings might come from (and why) let’s take a look at what happens when shells are created and initialized. Back to our DefaultOrchardHost implementation…

ShellContextFactory

We saw earlier that our shell contexts (instances of ShellContext) are created by calling either CreateSetupContext (where we have no shell settings) or CreateShellContext (where we do have shell settings). Both of these methods make calls to _shellContextFactory, an instance of IShellContextFactory, which in this case is implemented by ShellContextFactory. We call either CreateSetupContext or CreateShellContext on that instance, depending on whether or not we have settings (or if the settings we have say they haven’t been initialized yet).

Let’s go and take a look in ShellContextFactory, which can be found in Environment/ShellBuilders/ShellContextFactory.cs. It’s worth looking at what happens in here as it’s key to allowing Orchard to work the way it does with regard to IoC, and understanding that can save avoid confusion and problems down the line, especially when working with multiple tenants.

We’ll take our usual stance of ignoring logging and that kind of thing, but we’ll compare the two methods that are called, CreateShellContext and CreateSetupContext. Let’s look at the start of both.

First CreateShellContext:

Logger.Debug("Creating shell context for tenant {0}", settings.Name);

var knownDescriptor = _shellDescriptorCache.Fetch(settings.Name);
if (knownDescriptor == null) {
    Logger.Information("No descriptor cached. Starting with minimum components.");
    knownDescriptor = MinimumShellDescriptor();
}

and CreateSetupContext:

Logger.Warning("No shell settings available. Creating shell context for setup");

var descriptor = new ShellDescriptor {
    SerialNumber = -1,
    Features = new[] {
        new ShellFeature { Name = "Orchard.Setup" },
        new ShellFeature { Name = "Shapes" },
        new ShellFeature { Name = "Orchard.jQuery" },
    },
};

The obvious point here is that in a setup context we’re creating a new descriptor for the shell we’re creating, with only the features (modules) required to run the setup process, and to create a tenant for future use. Where we already have a tenant set up, we expect that we can get a shell descriptor from our cache, but if not we create one which is the minimum required at this stage. (At this point it’s worth noting that a shell descriptor is basically a list of some metadata about a shell/tenant, such as the name, a unique identifier, and a list of features which should be enabled when available).

Once we’ve got a shell descriptor, let’s see what happens to it:

var blueprint = _compositionStrategy.Compose(settings, descriptor);
var shellScope = _shellContainerFactory.CreateContainer(settings, blueprint);

Those lines are the same in both methods (except for the name of the descriptor instance which is passed in — these lines were taken from CreateSetupContext).

Now we’re getting to the critical part of the shell architecture. First of all, we create a ShellBlueprint, by calling Compose on our _compositionStrategy instance, passing in our settings and the descriptor that we’ve just created or acquired. What is that actually creating at this point? To find out, we’ll have a quick glance in to Environment/ShellBuilders/CompositionStrategy.cs which is where we find CompositionStrategy, the implementation of ICompositionStrategy in use here.

The Compose method looks like this:

public ShellBlueprint Compose(ShellSettings settings, ShellDescriptor descriptor) {
    Logger.Debug("Composing blueprint");

    var enabledFeatures = _extensionManager.EnabledFeatures(descriptor);
    var features = _extensionManager.LoadFeatures(enabledFeatures);

    if (descriptor.Features.Any(feature => feature.Name == "Orchard.Framework"))
        features = features.Concat(BuiltinFeatures());

    var modules = BuildBlueprint(features, IsModule, BuildModule);
    var dependencies = BuildBlueprint(features, IsDependency, (t, f) => BuildDependency(t, f, descriptor));
    var controllers = BuildBlueprint(features, IsController, BuildController);
    var records = BuildBlueprint(features, IsRecord, (t, f) => BuildRecord(t, f, settings));

    var result = new ShellBlueprint {
        Settings = settings,
        Descriptor = descriptor,
        Dependencies = dependencies.Concat(modules).ToArray(),
        Controllers = controllers,
        Records = records,
    };

    Logger.Debug("Done composing blueprint");
    return result;
}

This looks a little bit daunting at first glance — the BuildBlueprint method throwing generics and Func<...> around all over the place but it isn’t as complicated as it seems. In fact almost everything here is about working out what dependencies need to be registered with our IoC container so that the shell can provide any dependencies as they’re needed — for the right tenant and with the right scope. First of all there’s some checking to see which features in our descriptor are actually available through the extension manager (and recording the ones that are). Next we make sure that if Orchard.Framework is required, all of the built in features from that project are recorded as being required too.

Once that’s done, we start to call BuildBlueprint. While it’s called with various arguments and functions, it’s always doing roughly the same thing — building up a specification of what dependencies need to be registered for this shell. It does this through assembly scanning for certain types, with specific bits of logic for the varying things that might need to be registered (checking for a valid controller, a valid dependency). Once that’s done we end up with an aggregation of all of the types of dependencies that this shell is going to need, based on the features that have been described.

This is now what we need to actually build our shell scope through the call we saw earlier to _shellContainerFactory.CreateContainer.

That call to CreateContainer gives us an Autofac ILifetimeScope back, and that becomes a crucial part of our shell context. It means that pretty much anything the tenant needs to resolve (including the shell itself as we create a new ShellContext instance) will be resolved at the level of the shell lifetime scope, giving segregation and the possibility of very different configurations and loaded features between tenants.

ShellContainerFactory

The ShellContainerFactory class (Environment/ShellBuilders/ShellContainerFactory.cs) is the implementation used to build our ILifetimeScope from our shell settings and shell blueprint. It’s worth a read through but I’m not going to go through it all here — there’s quite a lot of code, most of which will be quickly readable if you’re familiar with Autofac. It is worth pulling out one part though, which is where we see how Orchard lets you implement your own dependencies with modules (and control their lifetimes).

This code (around line 66 onwards) is important:

foreach (var interfaceType in item.Type.GetInterfaces()
    .Where(itf => typeof(IDependency).IsAssignableFrom(itf) 
               && !typeof(IEventHandler).IsAssignableFrom(itf))) {
    registration = registration.As(interfaceType);
    if (typeof(ISingletonDependency).IsAssignableFrom(interfaceType)) {
        registration = registration.InstancePerMatchingLifetimeScope("shell");
    } 
    else if (typeof(IUnitOfWorkDependency).IsAssignableFrom(interfaceType)) {
        registration = registration.InstancePerMatchingLifetimeScope("work");
    }
    else if (typeof(ITransientDependency).IsAssignableFrom(interfaceType)) {
        registration = registration.InstancePerDependency();
    }
}

This is where Orchard is looking for the interfaces you would implement when creating your own module containing dependencies that you wish to make available through IoC. We can see clearly here how making our interfaces inherit IDependency, or ISingletonDependency will impact the registration of the type you provide within the scope of the shell. It’s also useful to remember for the future — if you need to one day extend the Orchard core to deal with more complex registrations and scope within the IoC container this would be the place to start (although it’s unlikely that’s going to be needed for most people!)

We can now go back to our ShellContextFactory. When we’re creating a setup context, we’re basically done now. The last part of that method looks like this:

return new ShellContext {
    Settings = settings,
    Descriptor = descriptor,
    Blueprint = blueprint,
    LifetimeScope = shellScope,
    Shell = shellScope.Resolve<IOrchardShell>(),
};

We can see that we’re storing our scope in there, and we’re also creating our actual shell instance by resolving an IOrchardShell — and importantly we’re doing that in our newly created scope, meaning that we’ve got just the right registrations and setup for our tenant, isolated from other tenants and their own shells.

We can finish up looking at shell and shell context creation now by just tying up a loose end — the other difference between a setup context and a normal shell context. The following code appears in CreateShellContext before we return a newly created ShellContext with our shell scope:

ShellDescriptor currentDescriptor;
using (var standaloneEnvironment = shellScope.CreateWorkContextScope()) {
    var shellDescriptorManager = standaloneEnvironment.Resolve<IShellDescriptorManager>();
    currentDescriptor = shellDescriptorManager.GetShellDescriptor();
}

if (currentDescriptor != null && knownDescriptor.SerialNumber != currentDescriptor.SerialNumber) {
    Logger.Information("Newer descriptor obtained. Rebuilding shell container.");

    _shellDescriptorCache.Store(settings.Name, currentDescriptor);
    blueprint = _compositionStrategy.Compose(settings, currentDescriptor);
    shellScope = _shellContainerFactory.CreateContainer(settings, blueprint);
}

At this point we check if there’s actually a more up to date shell descriptor already in the environment. If there is, we recompose our blueprint and construct a new shell scope to use rather than the one we created with our cached shell descriptor (as well as sticking the descriptor back in the cache so it’s there for next time).

From then on, we’re back to just returning our newly created shell context, with a shell resolved from the new shell scope.

DefaultOrchardHost

Finally (this has been a rather long article) we can take ourselves back to our DefaultOrchardHost, and see that the only really important thing that happens now is our call to ActivateShell. That looks like this:

private void ActivateShell(ShellContext context) {
    context.Shell.Activate();
    _runningShellTable.Add(context.Settings);
}

We can see that we’re actually calling Activate on our instance of IOrchardShell, before registering that shell in our table of running shells.

While we could start to dive in to what activating a shell means, that’s best served with a separate article — this one is more than long enough. So let’s wrap that up there. We’ve seen how shells and shell contexts get created based on the site/tenant settings in our App_Data/Sites directory, and we’ve seen how the settings there go towards making up an IoC scope for the shell and context.

We’ve also seen how the dependencies we create in our own custom modules get registered with the underlying shell and scope, so we know what we can do by default with Orchard for dependency specification.

Next up we’ll look at activating the shell, so check back to the main introductory post and the list of articles to see when that gets posted (or subscribe to the Atom feed if that’s you’re thing).

Orchard Startup

2011-08-30T00:00:00-07:00

This is part 1 of a series on Orchard Internals. Other posts will be linked from the introduction as they are published.

Overview

Orchard does a lot when it starts up. Although it’s an ASP.NET MVC 3 web application at heart, it replaces/augments/ignores various things as it needs to. This article will follow through the application startup process and see what gets run at this stage, right up until Orchard is ready to serve the first actual request.

The Web Application

Everything starts off in the web application itself. If you’ve got the source code handy (and these articles will make much more sense if you have), this is the Orchard.Web project. Looking in here we see… not a lot. This is because Orchard only really uses this as a boot up point for the application proper. There’s no content in here or traditional models, controllers and views — only the code needed to call out to Orchard and get things running.

If we look in the global.asax.cs file of the Orchard.Web project, this is where we’ll find our Orchard code. We don’t have some of the code which would normally be present in a default ASP.NET MVC 3 web app — there’s no registration of Areas or Filters in here as Orchard deals with these itself. It doesn’t map any Routes either, only ignoring the Route for resource.axd, as Orchard deals with Routes too.

The first place to look is in the application start method, which looks like this:

protected void Application_Start() {
    RegisterRoutes(RouteTable.Routes);
    _starter = new Starter<IOrchardHost>(HostInitialization, HostBeginRequest, HostEndRequest);
    _starter.OnApplicationStart(this);
}

The call to RegisterRoutes is normal, but then we’re straight in to Orchard code. We create a new Starter<IOrchardHost> and assign it to _starter, which is a static member of the application so it’s always available.

This gets passed a few arguments on construction, each of which is a method to call at different application stages — on start, beginning a request, and ending a request. The one which really matters to us here is the method which is going to get called on application start — and which is actually invoked as part of calling OnApplicationStart on our instance of Starter<IOrchardHost>.

Orchard.WarmupStarter

We’ve seen that we’re creating a new Starter<IOrchardHost> here, so let’s have a look at that. This class can be found in the Orchard.WarmupStarter project, which is the only Orchard project which is explicitly referenced in the web application - it’s referenced in the web.config file. This is because Orchard.WarmupStarter also provides an HttpModule (which is a bit out of scope in this article, but will likely be mentioned elsewhere at some point).

Starter<T> (Starter.cs) is where we want to look. We’ve seen that we’re passing it three methods which it can call (with suitable signatures) and when we construct it it simply stores those as member variables. When we then call OnApplicationStart it calls LaunchStartupThread, passing the HttpApplication instance that we’ve just given it. LaunchStartupThread looks like this:

public void LaunchStartupThread(HttpApplication application) {
    // Make sure incoming requests are queued
    WarmupHttpModule.SignalWarmupStart();

    ThreadPool.QueueUserWorkItem(
        state => {
            try {
                var result = _initialization(application);
                _initializationResult = result;
            }
            catch (Exception e) {
                lock (_synLock) {
                _error = e;
                _previousError = null;
            }
        }
        finally {
            // Execute pending requests as the initialization is over
            WarmupHttpModule.SignalWarmupDone();
        }
    });
}

Most of this is just concerned with making sure that this is run asynchronously (and working with the previously mentioned module) and that any errors which result are caught and recorded/dealt with properly, but the key part is that we’re initializing _initializationResult to the result of the method we passed in on construction. This is our generic type, which we’ve seen is of type IOrchardHost.

This is important - this is the host that’s going to be the root of our Orchard application — anything that happens in Orchard is going to happen as a result of calls in to this root object and the objects it will create and maintain. It’s stored in the Starter<T> which in turn is a static member of our web application, so the lifetime for this root object is the same as the application itself.

So — what’s the root object? We need to pop back to our global.asax.cs and see what the method which constructs our root object gives us.

OrchardStarter

The method that gets called to create our host object is HostInitialization in global.asax.cs. That looks like this:

private static IOrchardHost HostInitialization(HttpApplication application) {
    var host = OrchardStarter.CreateHost(MvcSingletons);

    host.Initialize();

    // initialize shells to speed up the first dynamic query
    host.BeginRequest();
    host.EndRequest();

    return host;
}

We’re getting our IOrchardHost instance by calling OrchardStarter.CreateHost. This is where the meat of our object instantiation is going to happen. It’s also the first place that we see another key element of Orchard, the use of IoC.

Let’s look at OrchardStarter and see what it’s doing. It’s in the Orchard.Framework project in Environment/OrchardStarter.cs. We start off by calling CreateHost, passing in an Action which takes a ContainerBuilder. This is an Autofac concept, but essentially it’s the class used to register dependencies when we build an IoC container. At the moment it’s being passed a method MvcSingletons in our global.asax.cs which registers the Routes, Binders and View Engines as they are currently set up for the application, making them available to the IoC container.

CreateHost looks like this:

public static IOrchardHost CreateHost(Action<ContainerBuilder> registrations) {
    var container = CreateHostContainer(registrations);
    return container.Resolve<IOrchardHost>();
}

It gets an IoC container by calling CreateHostContainer and then asks that container for an instance of IOrchardHost. CreateHostContainer (which I won’t give source for here, but it’s a very useful place to look if you’re wondering what implentation of an interface is used by default) registers all of the default dependencies that Orchard needs to run — all of the dependencies needed to create an IOrchardHost. So we can see that IoC is key to Orchard — there’s no manual creation of object graphs here, just IoC being used to satisfy all of the dependencies at runtime.

This is also a really useful place to look if you’re wondering about the lifecycle of any of the components of Orchard. It’s likely that they’re registered here, with the lifecycle being managed by the IoC container (Autofac is very good in this regard).

DefaultOrchardHost

At this point, if all has gone well, we have an instance of IOrchardHost. Looking at CreateHostContainer we can see that this will actually be an instance of DefaultOrchardHost — that’s the type which has been registered for this interface. Now we can go back to our web application in global.asax.cs and wrap up the tour of the startup process by looking what happens to our host.

private static IOrchardHost HostInitialization(HttpApplication application) {
    var host = OrchardStarter.CreateHost(MvcSingletons);

    host.Initialize();

    // initialize shells to speed up the first dynamic query
    host.BeginRequest();
    host.EndRequest();

    return host;
}

Looking again at our host initialization code, we can see that we call Initialize on our host. That’s pretty much it — the other calls on our host here are just there for performance reasons and aren’t really relevant to our startup process.

Wrapping Up

So we’ve been through the startup procedure and seen how Orchard creates the runtime environment. We haven’t looked at the actual host much yet — we’ll look at that in the next article in this series, but we have seen how a host is constructed so we can probably have a guess that by now our host has all of the dependencies it needs and is ready to start handling Orchard requests.

We’ve also seen where to find the default registrations and lifecycles for the core Orchard components and how those are made available to the host.

We’re now ready to start taking a deep dive in to the Orchard Host.

Orchard Internals

2011-08-26T00:00:00-07:00

Lately I’ve been doing quite a bit of work with the Orchard CMS. It’s a powerful system and although it’s quite new, becoming a 1.0 at the beginning of this year, there’s a lot of code to understand if you want to start extending it and working with it in significant ways as a developer.

While the documentation is pretty good, I find that it helps me to really understand the internals of a system I’m using, especially when — like Orchard — it does quite a lot based on convention and “magic”. So I’ll be writing a series here which is a crawl around some of the Orchard internals examining how it works and which bits do what. It helps me to understand the system better, and hopefully it’ll have some value for other developers that want to better understand Orchard and push the limits of what can be done with it.

I should note now that I’m not on the Orchard team — I didn’t write any of this code, so if I misunderstand it, apologies in advance. I’ll happily make corrections where errors or inclarity are pointed out.

Posts will be listed below as they’re added…

The Orchard Startup Process
The Orchard Host
Orchard Shell Activation
Request Lifecycle in Orchard
Orchard Extensions Mechanics
next…

Note that if something says it’s “in progress”, that pretty much means I’m writing it in public and I haven’t finished yet. Sometimes it takes me a few days to write things, other times I rattle through in an hour, but I quite like just getting something up even if it’s not finished. If something stops weirdly half way through, come back and check whether I’m writing as you’re reading — I’ll finish off soon, just bear with me…

If you’ve got any suggestions for areas you’d like me to cover, corrections, thoughts, etc. just drop me an email (see the Contact page) or say hello on Twitter, etc.

Hello!

2011-08-25T00:00:00-07:00

There’s not a lot to say in first posts on blogs, and I certainly can’t think of anything. All I really want to indicate is that I’ll be blogging on mainly software development and tech related things. A lot of them will probably be .NET because that’s work related, but I’m sure I’ll be writing about some of the other things I enjoy fiddling with as well (Ruby, Erlang, Io, Haskell, compilers, distributed things, you name it).

Anyway, enough waffle — time to start writing real content.