For the first section of the Architecture Series I'm going to concentrate on the Starter Site. I'll be covering the Control Library in a later series of posts.
The main code of the site lives in the App_Code directory. For those new to ASP.NET 2.0, the contents of this directory are compiled together into an assembly that is used by the entire site. All common classes should live inside of App_Code.
Inside App_Code lies two important classes and they hold the foundation to the Starter Site. The first, SiteModule, is invisible in the day-to-day code, but it sets the stage. The second, SiteContext, is explicitly used nearly everwhere.
The first class to look at is CommerceSite.SiteModule in the file App_Code\SiteModule.cs. This module is the entry point of the Starter Site application. Note that we could have just as easily used global.asax to house this code, however we chose a Module format so that we could derive from CommerceModule allowing us to enforce a dependency on Commerce Server (line 38).
SiteModule plugs into three places in the request life-cycle in order to do some important work:
The ApplyUserPreferences method (line 84) does the actual work of setting preferences. Currently the only two preferences set are currency and language. They are both set from a recognized user's profile however if the user is anonymous or does not have a preferred language an attempt is made to choose a language from the user's browser preferences (several user agents support setting a list of preferred languages to use when interacting with the site). The supported languages are determined by the web config and should be an intersection of the languages supported by the site (resource files) and the catalog. Out of the box the list is set to the languages supported by the catalog even though the Starter Site itself is not localized into any language other than English. If you want to set the user's preferences based on a cookie this is the place to do it.
The SiteContext class (App_Code\SiteContext.cs) is the launching point for many of the operations on the Starter Site. It is used similarly to HttpContext and CommerceContext. SiteContext is a request singleton, meaning that only one instance exists per request and they are not shared between requests. A new SiteContext is created at the beginning of the request (see above) and it is discarded at the end of the request.
InitializeSiteContext (line 105) creates a new SiteContext and adds it to the HttpContext Items dictionary. This dictionary exists only for the life of the HttpContext object, which is also a request singleton. This method is called by SiteModule.OnBeginRequest.
Two static properties used most often are Current and Configuration. Configuration returns the SiteConfiguration object which holds the parsed contents of web.config. All properties are strongly-typed and the config section is parsed using the ASP.NET 2.0 configuration classes. The Current property holds the instance of SiteContext for the current request; this is how you access the SiteContext instance and you will see it used throughout the site.
I won't go through all of the members (you can consult the Starter Site developer documentation for that) but I will cover some of the more important ones.
The members of ISiteContext are a special bunch. Because the control library is intended to be site-agnostic we needed a way to get site-specific functionality, things like product URLs, browse page, and order status display names, into the control libraries. The members are:
And that's SiteContext and SiteModule -- two rather simple classes that every page uses.