CmsHttpContext

CmsHttpContext is an object that represents the ASP.NET entry point into PAPI. It is instantiated by CMS on our behalf when we are interacting with a CMS-aware Web application. CMS gets the four pieces of information it needs to create a CmsHttpContext primarily through the QueryString:

• Authenticated user

• Publishing mode

• Channel

• Posting

In a Web application, either the user is authenticated by the application using Integrated Windows security, Forms-based authentication, propriety authentication, IIS anonymous access using the ASP.NET and IUSR_Machinename users, or guest access is enabled and CMS authenticates the user using the guest account. There are variations on each of these security approaches, but in all cases the user is authenticated as a specific user.

NOTE: Unless guest access is enabled, on pages where the user has not yet authenticated (like a typical login form), the CmsHttpContext will return an access denied error.

The URL QueryString usually specifies a specific posting in a specific channel for CMS to retrieve. It will also typically contain the publishing mode for CMS to create the Context in. If a publishing mode is not provided, the mode defaults to Published.

NOTE: In previous versions of CMS, what we refer to as Context was called Autosession. Autosession is still available in CMS when you are using an ASP-based solution. We will be covering the ASP.NET-based solution.

Perhaps a code sample is the best way to explain.

Open VS.NET to any project you can code in, or follow the steps in the Scratchpad sidebar. Although it is not the best programming practice, we will leave references to all elements as the default names the VS.NET IDE gives to them. In essence, we need to create a template file with the following ASP.NET Web Form controls TextBox, Label, ListBox, and Button using their default properties plus the default console, of course. It should look something like Figure 24-2. We will be repeatedly replacing the contents of the Button1_Click function.

Double-clicking the Web Form Button control in the Design palette will create the Button1_Click function in the code-behind of the template file. Replace the entire function with the following code:

 private void Button1_Click(object sender, System.EventArgs e) {   //1. Grab the current CMS context   CmsHttpContext cmsContext = CmsHttpContext.Current;   //2. Populate the label with the Publishing Mode   Label1.Text = cmsContext.Mode.ToString(); } 

At the top of the code window is a list of namespaces in use. If there isn't a line that looks like the following, you will need to add it:

 using Microsoft.ContentManagement.Publishing; 

Choose Build Solution from the VS.NET Build menu (Ctrl-Shift-B) or from the drop-down menu that results from right-clicking the solution name. When the build is done, the text

 Build: 1 succeeded, 0 failed, 0 skipped 

should be displayed at the bottom of the VS.NET Output window. Compile errors, if any, will need to be addressed before you proceed. VS.NET does a pretty good job of providing feedback when things aren't quite right.

Open Internet Explorer and browse to http://localhost/Scratch/Pad. Click the Button, and the label will display Published (Figure 24-3) in place of its default value of Label.

Figure 24-3. Current Context publishing mode

Click the Switch to Edit Site link, and then click the Button again. This time the label displays Unpublished. Cool.

Let's take a closer look at that code. The first executable line looks like this:

 CmsHttpContext cmsContext = CmsHttpContext.Current; 

We are declaring a variable named cmsContext (this can be any name we choose), using CmsHttpContext as the data type and immediately assigning it to the Current property of the existing CmsHttp Context that CMS creates for us using the IIS ISAPI filter when the posting is requested. Notice that there is not a new constructor but a declarative assignment statement instead. Current is declared by the CmsHttpContext class as Static, so it does not require the "new" keyword to instantiate it. Because there is only one CmsHttpContext allowed per HTTP request, the Current property controls access, ensuring that additional instances are not created. The CmsHttpContext class cannot be inherited or created by any other class.

The second executable line looks like this:

 Label1.Text = cmsContext.Mode.ToString(); 

Position your cursor just after the cmsContext variable name and type a period. An Intellisense window (Figure 24-4) should appear.

Figure 24-4. Exploring CmsHttpContext Intellisense

Take a close look at the items in the list. Compare it with Table B-1 in Appendix B. Choose any property (preceded by an icon of a hand pointing to a paper) and type ".ToString();" after it. For instance, if we used the first property in the list, Channel, the resulting assignment statement would look like this:

 Label1.Text = cmsContext.Channel.ToString(); 

Build the solution and then browse to or refresh the posting in Internet Explorer. Click the Button, and the label will display the value of the current channel rendered as a string. Since we didn't choose a specific property (characteristic) of the Channel object, like cmsContext.Channel.DisplayName.ToString(), .NET just shows us what type of object it is. So, Label displays the text

 Microsoft.ContentManagement.Publishing.Channel. 

Spend some time just toying with the different items in the Intellisense list. The worst that you could do is end up with syntax errors. Remember, every change made in the code window will only be reflected in the browser after a successful VS.NET build.

NOTE: The first attempt to browse a recently compiled page will require a just in time (JIT) compilation of the changes so it will consequently take longer than subsequent requests.

But we have a problem we can't use the CmsHttpContext if we need to access CMS with a different set of credentials than were provided by the user, or when we need to use a different mode than the posting is in (although it is possible to redirect the user to another publishing mode, we may not want to), or when we aren't in a posting at all. For situations where the CmsHttpContext isn't available or isn't what we need, we use the CmsApplicationContext.