Preparing to Migrate to MCMS 2002 and ASP.NET
Published, February 2002
Updated, September 2002
Microsoft Content Management Server 2002
Summary: Discover the benefits of migrating to Microsoft® Content Management Server (MCMS), and learn how to prepare for your migration.
A Microsoft® Content Management Server (MCMS) Web site is composed of ASP pages based on MCMS templates and placeholders. Any decision to migrate site content involves choosing a migration path best suited to the needs of your organization. Depending on the design of your site and the time and resources available in your organization, you might choose to:
- Install MCMS 2002, migrate your MCMS 2001 database to an MCMS 2002 database using the Database Configuration Application (DCA), resolve any issues logged in the migration report, and verify that your MCMS 2002 ASP-based site is functioning correctly. For information about the tasks performed by the DCA during the upgrade process from MCMS 2001 to MCMS 2002, see the "Improved Migration Support" section in this paper.
- Convert your templates, in full or in part, from ASP to ASP.NET to take advantage of the integration with Microsoft® Visual Studio® .NET. For an explanation of the simple, straightforward coding changes you need to make to update your MCMS 2002 ASP-based site to ASP.NET-based functionality, see the "Migrating to an ASP.NET-Based Site" section in this paper.
- Adopt a more gradual, staged approach to migration with a mixed ASP-based and ASP.NET-based site. For more information about the issues with mixed sites, see the "Migrating to a Mixed Site" section in this paper.
While the choice of migration path is yours, to take full advantage of ASP.NET features and benefits—including standards-based interoperability, cross-platform connectivity, modular and reusable code, and high-performance, secure, managed code—you have to upgrade to MCMS 2002 and convert your templates to ASP.NET. As ASP.NET represents a fundamental technology change from Active Server Pages (ASP), migrating your site will involve rewriting some code. However, the following sections provide more information about how the migration process works and show that the procedure for converting your ASP-based templates to ASP.NET is relatively simple and straightforward which keeps your development work minimal.
Readers of this paper should have a working knowledge of the following:
- Programming differences between ASP and ASP.NET including the benefits of managed code
- Scripting against the MCMS 2001 Publishing API
- MCMS 2001 concepts such as templates, placeholders, connected pages, and template switching
- MCMS security issues including the existing rights and user authentication models. For an overview of the ASP.NET security and authentication model, see the Microsoft MSDN Web site located at: http://www.msdn.microsoft.com/library. Search using the keywords "ASP.NET security."
- For information about ASP.NET programming concepts and event handling, see the Microsoft MSDN Web site located at http://www.msdn.microsoft.com/library/ Search using the keywords "event handling and ASP.NET."
- For information about the concepts in MCMS, see the MCMS online documentation.
MCMS 2002 is designed to support both the .NET Framework and traditional COM technology. You can continue to do development work in ASP or opt for ASP.NET. The choice is yours. To help you understand how the move to ASP.NET affects MCMS sites and offer prescriptive guidance to better prepare you for migration to MCMS 2002, the following three features are addressed in this paper specifically in terms of their impact on your migration work:
- Improved template development experience
- Improved flexibility with the MCMS Publishing API
- Improved migration support
Improved Template Development Experience
MCMS 2002 represents significant changes in template architecture to allow for improved integration with other Web development tools such as Microsoft Visual Studio® .NET and to improve the development process. This section describes two notable architectural changes:
- Changes to MCMS template architecture
- Changes to placeholders
Changes to MCMS Template Architecture
In MCMS 2001, templates could not be directly edited by developers. When a developer created or edited a template, MCMS created a temporary HTML file on the developer’s hard drive. When the developer completed work and saved the file, MCMS uploaded the file. The server then parsed the file to discover its relevant metadata (name, number of multipurpose placeholders, and so on). It also injected the ASP code necessary to render pages based on the template. The template metadata and the template file were then stored in the database. When a page based on a particular template was requested, MCMS 2001 retrieved the template from the database and sent it to a directory on the file system. All templates were placed in the same directory.
In MCMS 2002, template code is now stored as files on the file system (as opposed to inside the database) to facilitate editing and integration with Visual Studio .NET and with source control mechanisms such as Microsoft Visual SourceSafe®. Templates are now .asp or .aspx pages. Templates reference a template file and store information regarding placeholder definitions and custom properties. These terms are defined in table 1 below:
|Template (object)||A template object defines a similar overall appearance for a set of pages in an MCMS Web site. Some areas of a template are pre-defined for all pages based on the template, while areas of the template, known as placeholders, are reserved for custom content in each page based on the template. When a page is viewed in authoring mode (in the Web Author), placeholders defined in the template are rendered as controls that allow custom content to be created or modified. When a page is viewed in presentation mode, the custom content associated with each placeholder in the template is rendered as an integrated part of the page. Templates are implemented as a combination of information in the Content Repository, known as the template, and an ASPX template file in the file system. The template contains a property that identifies its corresponding template file.|
|Template file||An ASPX file (sometimes an ASP or ASCX file) that contains the executable code associated with a template in MCMS. Template files generally contain a placeholder control for each placeholder definition in the corresponding template. When a template file is run in response to a page based on the corresponding template being requested, the placeholder controls in the template file are run, as is any other code in the template file. Depending on the mode, authoring or presentation, the placeholder controls will render themselves differently. In authoring mode, they allow authorized users to create or modify their content and write that content back to the Content Repository. In presentation mode, they retrieve their content from the Content Repository and render it as part of the page.|
|Placeholder (object)||A placeholder object is an area in a template that is reserved to contain unique content for each page based on that template. Placeholders are implemented using placeholder controls in template files and placeholder definitions in templates, and the actual content (accessed programmatically through Placeholder objects) defined to fill those placeholders on a page by page basis using the Web Author or the Authoring Connector. There are different placeholders for different types of content, such as HTML, images, attachments, and XML. New placeholders can be created by MCMS developers.|
|Placeholder definition||A placeholder definition defines characteristics, such as constraints on the content, for a placeholder. Placeholder definitions are associated with a template and govern the placeholders to which they are bound on all pages based on that template. Connected templates share placeholder definitions.|
|Placeholder control||A placeholder control is an ASP.NET-based server control that provides the user interface for a placeholder in both the authoring and presentation modes of the Web Author. In authoring mode, a placeholder control must provide a way for the corresponding content to be created and modified. In presentation mode, a placeholder control must present the content as appropriate. There are different types of placeholder controls for different types of content, such as HTML, images, attachments, and XML. New placeholder controls can be created by MCMS developers.|
The content of your page depends on the template metadata, such as placeholder definitions, and not on the template file itself. The template file only contains information about how to display the page. The placeholder information is the same regardless of whether the file has an .asp or .aspx file extension. Figure 1 shows the relationship between these separate components when an ASPX page is run.
Figure 1 Page Elements
Changes to Placeholders
Placeholders now contain three separate components: a placeholder definition, a placeholder object, and a placeholder control. Converting ASP-based templates to ASP.NET-based template files is now possible because placeholder definitions can be bound to ASP.NET placeholder controls. After conversion, each multipurpose placeholder in a template becomes either an HTML, attachment, or image placeholder definition, depending on its associated properties. The following table describes other available Microsoft Content Management Server (MCMS) 2002 placeholder definition types.
|Placeholder definition type||Description|
|XML Placeholder||A placeholder that supports XML.|
|Office Attachment Placeholder||An attachment placeholder used with the MCMS Authoring Connector.|
|Office HTML Placeholder||An HTML placeholder used with the MCMS Authoring Connector.|
The following MCMS 2001 placeholder properties are no longer supported:
- Video only
- HTML placeholders that do not support text
- Non-editable placeholders
After migration, video-only placeholders map to a new single attachment placeholder. Refer to the migration report to identify which template has a video-only placeholder. Edit the page so that it uses the new single attachment placeholder.
Improved Flexibility with the Publishing API
To ensure compatibility with the .NET Framework and provide developers with improved flexibility to design Web sites, developers will be able to develop Web applications in managed code with MCMS 2002. The MCMS 2002 Publishing API is wrapped in a managed code layer so that the API can be invoked on a Web page or in a stand-alone application. For backwards compatibility, unmanaged components are still available and accessible from COM objects.
Changes to Autosession for Managed Code
In MCMS 2002, the CmsHttpContext object is functionally equivalent to the Autosession object from MCMS 2001. However, MCMS 2002 also contains a new object called CmsApplicationContext that is similar to the Autosession object, but is meant to be accessed or "consumed" outside the context of ASP and ASP.NET. The benefit is that you can access the API from any application, including a compiled application. ASP-based sites will still use the Autosession object.
For changes to the Autosession object that are specific to mixed sites, see the "Changes to Authentication" section in this paper.
Improved Migration Support
MCMS 2002 is designed to help protect your investment in traditional ASP and COM technologies. If you have already built a site using Microsoft Content Management Server (MCMS) 2001, and are upgrading to MCMS 2002, rest assured that your content is safe. While no migration is seamless and migrating MCMS 2001 ASP-based applications to MCMS 2002 ASP.NET-based will undoubtedly require some scripting changes, the initial migration process from MCMS 2001 to MCMS 2002 is highly automated, facilitating a smooth transition to a MCMS 2002 ASP-based site.
During the upgrade of the 2001 database, the Database Configuration Application (DCA) automatically performs the following tasks during the upgrade process:
- Creates a directory under IIS_NR called Templates that mirrors the MCMS 2001 template gallery hierarchy.
- Creates a template file for each template, and deletes historical revisions of templates.
- Converts each of the placeholders to use the correct placeholder definition. This ensures compatibility with managed placeholder objects in ASP.NET.
- Moves resources that are embedded in templates to the file system.
- Converts every Microsoft Content Management Server (MCMS) 2001 navigation template to a channel rendering script. In MCMS 2002, a channel rendering script is run for a channel when it is selected, or when one of the postings for the channel is used to render the channel. Channel managers can select the method of channel rendering by setting channel properties in the Site Manager. For more information, see "Channel Rendering Scripts" in MCMS 2002 Help.
- Logs each change that was made during migration to a migration report. The report is located at <system drive>:\Program Files\Microsoft Content Management Server\Server\IIS_NR\LogFiles\MigrationReport.txt.
- Searches for all items currently stored in Deleted Items and removes all location information from the object name. All characters, up to and including the very last slash character ("/") are removed, leaving only the original object name in place.
It is important to note that post-migration only the following character set is valid when naming any MCMS object: alphanumeric characters, hyphens, underscores, brackets, and spaces. This MCMS naming convention is based on the legal characters that are allowed by Internet Information Services (IIS) 6.0 and URLScan. Any existing MCMS object with an illegal name will have to be edited for compliance to this standard whenever changes are made to the content or name property of that object.
If you have built your Web site using MCMS 2001 and want to upgrade to MCMS 2002 and convert your site to ASP.NET, the planning considerations and best practices listed below are intended as prescriptive guidance to help you:
- Prepare for a smooth transition to an MCMS 2002 ASP.NET-based site
- Save time and effort, keeping your migration work to a minimum
- Concentrate on more important issues such as managing your Web content
This section outlines some considerations to keep in mind when planning your migration strategy:
- Changes to the development platform
- Changes to the authoring environment
- Changes to the rights model
- Changes to Authentication
Changes to the Development Platform
Because MCMS 2002 is integrated with Microsoft Visual Studio .NET, the template development environment and the procedure for creating templates has changed between MCMS 2001 and MCMS 2002.
In MCMS 2001, template designers and navigation programmers designed templates using an HTML code editor and the Design Palette in MCMS Site Builder. The HTML was displayed in an HTML editor with the placeholders represented as image tags. However, what was being edited was a representation of the code that resided in the template in the database.
In MCMS 2002, ASP-based templates are still supported but the model for creating them has changed. Now ASP-based templates, as well as placeholder definitions, are created in Microsoft Visual Studio .NET. Note, however, that only placeholders of type HTML, image, or attachment can be used because the ASP emitter class will always create the placeholder object from MCMS 2001.
In MCMS 2002, Site Builder has been renamed to Site Manager, and much of its developer functionality has been replaced by the integration with Visual Studio .NET. Developers work within Visual Studio .NET to create and modify templates, placeholder definitions, custom property definitions, template files, and placeholder controls.
Changes to the Authoring Environment
The authoring environment has changed for MCMS 2002. If your content providers formerly used Site Manager as their authoring environment, they must now author using the Web Author. The Web Author provides an improved in-context authoring experience, greater extensibility, and ease of access to the MCMS Publishing API. Authoring using Site Manager is no longer supported. For more information about the Web Author see "Creating Content with the Web Author" in MCMS 2002 Help.
With MCMS 2002 users can now take advantage of MCMS Authoring Connector for Microsoft Word. For more information about working with Authoring Connector, see "Creating Content with Authoring Connector" in MCMS 2002 Help.
Changes to the Rights Model
In Microsoft Content Management Server (MCMS) 2002, the rights model has been modified in the following ways:
- Extends the rights model to allow for the new role of channel manager.
- Changes the rights granted to the template designer role to accommodate a revised template development process.
- Modifies the container viewing rights allowed for the subscriber role to accommodate recent security changes that place stronger access control lists (ACLs) on resources and template galleries.
- Modifies how guest access is handled.
The implications of these rights changes specifically for migration are as follows:
- Directory access
- Web Author access
- Templates and template switching
- Template designer access
About directory access
Migration does not grant write rights to the directories where template files, channel rendering scripts, and application resources are created. If template developers need to create or modify files in these directories, appropriate permissions must be explicitly granted to the following directories:
- Created a template directory or template file under <drive>:\Program Files\Microsoft Content Management Server\Server\IIS_NR \exeres\Templates.
- Created a rendering directory or file under <drive>:\Program Files\Microsoft Content Management Server\Server\IIS_NR\exeres \Channel_Rendering_Scripts.
- Created a resource directory or file under <drive>:\Program Files\Microsoft Content Management Server\Server\IIS_NR \rdonyres\MigratedResources.
About Web Author access
Subscribers need explicit access rights granted to templates and resource items so that resources can be viewed in the Web Author.
Template designers need explicit access rights granted to channels so that they can access the Web Author.
Moderators need explicit access rights granted to templates and resource items so that they can be viewed and used in the Web Author.
About templates and template switching issues
In MCMS 2001, having access to the channel containing a page allowed any user with subscriber or better rights (author, editor, moderator) to view the page using the primary template or an alternate template if template switching was used. In MCMS 2002, in addition to having rights to the channel, a user must also have a minimum of subscriber rights to the template gallery where the primary template is stored and the template gallery where an alternate template is stored.
About template designer access
In MCMS 2001, template designers needed to be included in specific authoring rights groups to be able to create test pages with their templates. In MCMS 2002, template designers can be assigned directly to a channel or a resource gallery
Changes to Authentication
While Microsoft Content Management Server (MCMS) Site Stager is still supported for ASP-based sites, it is not supported for ASP.NET-based sites. This means that administrators cannot assign Site Server users to MCMS rights groups. They must move to Active Directory® directory service-based users. For authentication issues with mixed sites, see the "Migrating to a Mixed Site" section in this paper.
Best Practices for Migration to ASP.NET
When you migrate your Microsoft Content Management Server (MCMS) Web site (all or part of it) to ASP.NET, use the following best practices:
- Use Microsoft Visual Studio® .NET as your development environment.
- Identify those parts of your site that are well defined pieces of code that can be easily encapsulated into .NET-based user controls or server controls and then re-used throughout the site. For example, template headers and footers can be easily expressed as ASP.NET user controls. Similarly, navigation code can be easily encapsulated as a server control.
- Determine if you can use new features to replace old methods. For example, you may be able to replace fragment caching with output caching. The advantage of output caching is that it enables you to store the results that a dynamic page generates. On subsequent requests, the cached output is used to satisfy the request rather than dynamically executing the page code. Output caching is also referred to as page caching.
- Ensure that sites using both ASP and ASP-based templates share compatible application scope or global variables. The authentication models must be compatible for a user to navigate seamlessly between portions of a mixed site. For more information about the potential impact of mixed ASP and ASP.NET-based sites, see "Migrating to a Mixed Site."
- Use source control for your templates.
Summary of Anticipated Code Changes
The core focus of MCMS 2002 involves heavy integration with ASP.NET. Since ASP uses Microsoft Visual Basic® Scripting Edition (VBScript) and ASP.NET uses object-oriented programming languages such as Microsoft Visual C#™ and Visual Basic .NET, some ASP code will need to be rewritten. For managed code written for MCMS 2001, you can anticipate that five to ten percent of the code will need to be changed for MCMS 2002. For segregated code written in ASP, the percentage is lower. Coding changes you should be aware of are summarized below.
Changes to Autosession
As a result of the changes to the Autosession object to ensure compatibility with ASP.NET, all parameters and arguments that expect or return the Autosession object will need to be rewritten to adhere to the guidelines for the CmsHttpContext object.
For changes to the Autosession object specific to mixed sites, see the "Changes to Authentication" section in this paper.
Changes to Cache Management
In MCMS 2001, each template that uses output caching usually requires the template developer to write explicit logic that governs the details of how that cache is managed. MCMS 2002 will use ASP.NET for output caching. This means that you do not need to use the strategy of building a string as the only output of the class library as with MCMS 2001. The reason the class library should only output a string for MCMS 2001 is that developers have to fragment cache manually. For MCMS 2002, the class library does not require this approach because caching is handled automatically by ASP.NET.
For the majority of templates (that do not have interactive or transactional code) you should use the "outputcache" ASP.NET page directive. Otherwise, you can use the ASP.NET Cache dictionary object.
Changes in Template Programming
When migrating to .aspx templates, classes in existing complied class libraries must be copied and pasted to code-behind C# (.cs) files. Typically, MCMS 2002 templates (.aspx files) use a code-behind approach for functionality specific to a single template. If the functionality is used on more than one template, it should stay as a class library to share the functionality between templates.
ASP Emitter Class Versus ASP.NET Binding
The multi-step process through which the various elements used to build a Microsoft Content Management Server (MCMS) Web page are bound together is referred to as binding in ASP.NET. The ASP emitter class corresponds roughly to the placeholder controls in ASP.NET templates.
The ASP emitter class is used to emit the contents of a placeholder. Specifying the name of the ASP placeholder performs the binding. One of the steps in migrating your MCMS 2002 ASP-based site to an ASP.NET-based site involves converting emit calls to placeholder controls using the PlaceholderToBind property in ASP.NET. However, the ASP emitter class has been retained for backward compatibility.
Migrating a Microsoft Content Management Server (MCMS) 2002 ASP-based site to ASP.NET requires that you convert each template to ASP.NET manually. Although there is no way to automatically convert an ASP page to an ASP.NET page, the procedure for migrating your site manually is quite straightforward. This section summarizes the steps involved in migrating your ASP-based site to an ASP.NET-based site using Microsoft Visual Studio .NET. For more information, refer to the additional resources provided.
Step 1: Enabling an MCMS Project in Visual Studio .NET
As a result of the Microsoft Content Management Server (MCMS) 2002 integration with Microsoft Visual Studio .NET, MCMS Web applications and services are managed as Visual Studio .NET projects and solutions. The first step in migrating an ASP template to ASP.NET is to enable it as an MCMS project in the Visual Studio .NET development environment. For more information about working with Visual Studio .NET projects and solutions, see Visual Studio .NET Help.
Step 2: Creating Template Files
After you create the template gallery, you can create your template files. For each template that you are migrating, you must to create a corresponding template file. This template file will contain the HTML layout for the resulting Web page, and its code-behind page will contain the scripting code required to support dynamic content on the Web page. For more information, see Visual Studio .NET Help or "Creating Template Files" in MCMS 2002 Help.
Step 3: Converting Placeholders to Placeholder Controls
Now that you have created the template file, you can convert placeholders to placeholder controls. Converting placeholders to placeholder controls involves replacing the ASP emit calls with ASP.NET functionality. To do this using the Visual Studio .NET development environment, you have to:
- Add MCMS 2002 placeholder controls to an .aspx page by dragging and dropping them from the Content Management Server tab of the Toolbox window. For more information, see "Adding Placeholder controls to Template Files" in MCMS 2002 Help.
- Set properties for the placeholder control in the Visual Studio. NET Properties window.
- Associate the placeholder control with its definition. In MCMS 2002, placeholder controls in a template file become bound to a placeholder definition in the associated template when their PlaceholderToBind property is set. For more information, see "Setting Template and Template Gallery Properties" in MCMS 2002 Help.
Step 4: Adding Server and User Controls
After you have associated the placeholder controls with their definitions, you need to identify those parts of your site that contain well defined pieces of code that can be easily encapsulated into .NET-based user controls or server controls and then re-used throughout the site. For example, navigation code can be easily encapsulated as a server control. Template headers and footers can be easily encapsulated as user controls to facilitate code reuse.
Depending on the design of your site and the needs of your organization, you might need to take a staged approach to migration that involves a mixed site. A mixed site approach to migration may be beneficial if you have a complex site with a large amount of ASP-based code that cannot be converted all at once due to resource constraints. ASP-based and ASP.NET-based applications can run side-by-side on a server. It is possible to have one part of an application running ASP and another part of the same application running ASP.NET.
When you upgrade to MCMS 2002, you may choose to have a portion of your site as it was with MCMS 2001, and build a portion of it in ASP.NET. The proportions you choose will depend on factors such as:
- How much time you have to rewrite a percentage of your code.
- How complex the code is and how much work would be involved to rewrite it in ASP.NET. If your code is complex you should write it once in ASP.NET and use COM interoperability.
- Where you can leverage ASP.NET functionality to start with.
- Which .NET applications that you have already written and can integrate with.
However, using ASP.NET throughout your site is highly recommended. A mixed ASP and ASP.NET solution will increase the complexity of your site and potentially impact coding time, management costs, and overall site usability. This section highlights the following issues with mixed sites:
- Different Web Author user experiences
- Different event models
- Changes to authentication
Different Web Author User Experiences
While ASP-based templates use an ASP-based console, ASP.NET-based templates use an ASP.NET-based console. The functionality may be quite different in each case. In general, it is strongly recommended that you limit the customization opportunities for mixed sites to keep the functionality as uniform as possible.
Different Event Models
ASP-based hooks are replaced by MCMS Publishing API events in MCMS 2002. So, for example, if you create an ASP-based e-mail notification mechanism, it will not be available until you convert it to the corresponding event in the ASP.NET event model.
Changes to Authentication
If you have both ASP and ASP.NET templates in use on your site, then your authentication model may be more complex. This topic describes three authentication-related issues that may arise in mixed sites:
- Global settings
- Cookie settings
Global settings or scope variables, such as custom authentication, authorization settings, and session state handlers, are defined in the global.asa file for ASP-based applications, and in the global.asax file for ASP.NET-based applications. Similarly, the Web.config file applies to ASP.NET-based applications, but not to ASP-based applications.
If a business user chooses a template in a different Web application (ASP or ASP.NET), the Web site may reference a different application context. If any component on a page depends on these global settings, it may stop functioning. Security settings may also change, depending on which page’s security settings are being applied.
Use an ASP.NET logon page to retrieve your authentication cookie. Both ASP and ASP.NET templates use the same cookies. Your ASP.NET browser must support cookies. You cannot run ASP.NET sites in a cookieless mode. The ASP.NET feature <sessionState cookieless=”true”> is not supported by MCMS 2002.
If you are using a forms-based logon page and have both ASP and ASP.NET templates, you should configure authenticate.inc to use an ASP.NET logon form.
To change which page displays as the manual logon page, you must modify the new
MANUALLOGINURL variable to point to the correct manual logon page. You need to make the
MANUALLOGINURL variable match the URL that is specified in the <
forms ... loginUrl="xxxxxxxx" .../> tag in the Web.config file for the Web application(s). The
MANUALLOGINURL variable is located in <InstallDirectory>:\Server\IIS_NR\System\Access\ManualLogin.inc. and IIS_NR_RO_ASP\System\Access\ManualLogin.inc.
For more information see the MCMS Web site at http://www.microsoft.com/cmserver.