Mats Halfvares, the Content Studio Development team

Since Content Studio version 5 is based on the .NET Framework platform there is a huge step from the old version 4.x platform, which was based on the old COM technology.

One of the most obvious differences is that the old programming language VB-script was an untype script based programming language whose syntax has undergone substancial changes compared to its successor VB.NET which is a full blown programming language. For this reason, and other as well, there are no possibilities to directly upgrade a Web site running on Content Studio 4.x to the Content Studio 5.x platform.

For this reason, the strategy is not upgrade but to migrate. The process consists of the following steps:

• Analyze and generated a report of the site database by using the Migration tool.
• Install a copy of the database to an new SQL Server instance or the same instance as the current site.
• Migrate and upgrade the database copy by using the Migration tool.
• Install Content Studio and install a new Web site using the migrated database as a source.
• By using the analyze report, make the changes needed to get the new Web site working. This part of the process can require a substancial amount of work for large Web sites depending on the following factors.
  • The amount of outdated AS-components in use - most of which can be replaced with newer that performs the same things.
  • The amount of VB script code that exists in scriptable AS components such as Insert script
  • The amount if inline server side script block found (<% ... %>) blocks and the complexitiy of these code blocks.
  • The amount of server side code blocks (<script runat="server" >) and the amount and complexity of the code found.
  • The amount of custom AS components in use. These components will probably need to be re-written.
  • If there are COM objects in use on server side and a corresponding .NET class exists that does the same work, it is probably a good idea to use the .NET object instead. For example, the MSXML.DomDocument is easily replaced by the System.Xml.XmlDocument or the System.Xml.XmlReader object. This might greatly help performance of the Web site, especially if the object is used often.
• When the Web site is working and tested, the new, version 5, site can be made public.

Changing the code to VB.NET

For more information on converting to VB.NET, se the following articles from Microsoft:

• Converting ASP to ASP.NET
• Migrating to ASP.NET: Key Considerations

AS components in version 5

Deprecated AS components

Some old AS components are still included in the product, even though there are better alternatives available. It is not recommended to use these old AS components. Instead, use the alternative AS components. There is no guarantee the old AS components will be a part of the product in future versions.

Outdate AS components

When developing version 5 of Content Studio, some components was permanently removed compared to version 4. The reason is that they are replaced by other components that perform roughly the same but in a far better and more optimized way.

Removed AS components

This class of components represents are removed from Content Studio version 5 and there are no replacements for them. The reason for this either that they uses an old technique that no longer is supported in the product (ex. the Content Studio Personalization Server) or or that they cannot meet the requirements of a modern development platform.

Upcoming AS components

Some of the functionality that is available in Content Studio version 4 are not yet available i version 5. The corresponding AS components are hence not available at the moment.

Preparing your Web site for migration

In order to faciliate the migration you should prepare your Web site as much as possible prior to the actual migration process.

Replace outdated components

The migration tool will provide you with a list of all outdated AS components and suggest their replacements. You should examine those document and, if possible, replace those older components with their successors. When replacing the components you typically place the new component on the page and transform the settings from the old component into the new one. You can now test the page and when it behaves as expected you can remove the old component and approve the document.

Analyze your custom components

In the report there will be (if you choosed to scan for custom components) a summary section where you can see how often custom AS-components have been used on the Web site. It is now wise to analyze these components to see how they can be rewritten to support Content Studio 5. Often custom components are built with one of the standard components as a source and just extends them in some way. In Content Studio 5 the source code of the standard components no longer is a part of the actual component but the SDK contains the source code of all these components. You can use this code base to rewrite your component and this library also guides you through the new completly rewritten CS API. What you find in the standard components in Content Studio 5 is normally just the call to the compiled form of the component but this code too is valuable when you rewrite your own components. You can freely use the source code in the SDK to build your own components but Teknikhuset has no responsibility for any problem these components can cause.
Custom components that are built from own code only but accesses the Content Studio API must be rebuilt using the new API. A major part of the work will to translate the old API calls into the new ones. The developer is encouraged to use the new high level objects in CS Server that radically faciliates works with documents, EPT documents and Xml index filtering.
If your component uses the MSXML2.DomDocument COM object or other COM objects you should use the .NET class that performs the same task, if available. The MSXML2.DomDocument is easily replaced with the System.Xml.XmlDocument object or even better, the System.Xml.XmlReader class.
When the analyze have been done and you have access to a Content Studio 5 development Web site you can rewrite your custom component on that site. Develop a class library with your own namespace as the back-end of your component and upload that code library/file to the App_Code folder in Content Studio 5. Your component will then be able to use your "code behind" exactly as the standard component does. Use the same programming model as the built in components, i.e. expose all the component settings as public properties and provide an Infoke method that does the actual Html rendering. Also, you can inherit from one of the AS component base classes which will provide useful base functionality to your component.

Analyze your custom code blocks

The migration tool will find every document where there is an inline code block. An inline code block is executed on the server side an is contained within <% %> tags. In the old ASP it was possible to write procedures and functions within these blocks but in ASP.NET this is no longer possible. All such procedures must be moved into the Code Behind file or moved to server side script blocks ( <script runat="server">  </script>)
Alsoe, there are some important differences between the old VB Script language and the new VB.NET programming language in .NET and all these differences must be corrected before the document will compile in Content Studio 5.

For example, the following code snippet in Content Studio 4

<span><%
Function IsEmptyData(data) 
  If data = "" Then
    IsEmptyData = True
  Else
    IsEmptyData = False
  End If
End Function
Result = IsEmptyData(EPT_GetFieldName("MyField"))
Response.Write "The field MyField is empty is a " & Result & " statement"
%></span>
 

can be rewritten to something like this in CS 5

<script runat="server">
  Function IsEmptyData(data As String) As Boolean
    If String.IsNullOrEmpty(data) Then
      Return True
    Else
      Return False
    End If
  End Function
</script>
<span><%
Dim Result As Boolean = IsEmptyData(CS_DataFields("MyField"))
Response.Write (String.Format("The field MyField is empty is a {0} statement", Result))
%></span>
 

In both examples the following code will be written out on the Web page

<span>The field MyField is empty is a True statement</span> 

What you can see from these two examples is how the VB Script code can be rewritten in order to work in ASP.NET.

Procedures cannot exist in inline code blocks in VB.NET

The IsEmptyData was moved out to a new server side script block.

Visual Basic .NET is a typed language and variables should be declared

All variables are declared with a datatype and the function was given a return value.

All procedure calls must have paranthesis around their arguments

The Response.Write call was surrounded by paranthesis.

The IsEmptyData = True has been replaced with a Return statement

This is the new way of returning a value from a function, however the old syntax still works.

Handling COM objects

If you are using COM objects on your site Visual Basic.NET can use them via the CreateObject function or the CreateObject method on the ASP.NET intrisic Server object. Often used COM objects are the ADO objects such as the Connection, Recordset and Command objects for reading data and the MSXML DomDocument object for consuming Xml based data. All these objects is used in Content Studio 4.x in documents that call into the CS 4.x API. Although you can use these objects in CS 5, they come with some caveats and should be replaced with their managed successors ADO.NET objects or objects in the System.Xml namespace.

• performance can be substantially worse
• can consume more resources on the server
• are untyped and late bound
• The Set keyword is no longer supported

When estimating the amount of work needed you should take replacement of these objects into consideration. Also if any of the ADO objects exists as a result of calls into the CS 4 API you will know that the successors of these API calls will have to be rewritten since they all returns Xml in CS 5.

Converting CS 4 API calls to CS 5 API

As mentioned before the entire CS API has been rewritten and now have a completly different structure even though the return value for those calls that returned Xml has been preserved in most cases. This means that most of your work that handles the returned Xml can be reused. This is true even if you use the System.Xml.XmlDocument instead of the old COM based counterpart. However the actual calls must be rewritten and while at it, you really should have a look on some of the high level API calls that radically makes life easier for the Content Studio developer.

Converting Web API calls

The Content Studio Web API is used mainly from client side java script code that needs to have access to the Content Studio API. This makes it possible to use the AJAX technology when developing your Web sites.

In CS 4 these Web API consists of a number of .ASP files located in the administrative Web site. These .ASP files accepts and returns Xml that can be consumed by JavaScript code in the Web Browser. The CS 5 counterpart is mainly the same but have been placed in the WebAPI subdirectory and have new names that follows the namespaces and class names in the CS 5 API. They are now implemented as Web handlers (.ASHX files) that gives better performance compared to both .ASPX files and regular Web Services as well. When you call the Web API you will send the query string action that is the name of the method in the API to call and the parameter data can be sent with one of the following methods:

1 The parameters as query strings using the method GET

FILE.ashx?action=METHODNAME&param1=VALUE&param2=VALUE

2 The parameters as an Xml document using the method POST

You will send a query string with the action argument

FILE.ashx?action=METHODNAME

and POST an Xml document with the parameters and their values

<root>
 <parameters>
  <parameter name="param1">VALUE</parameter>
  <parameter name="param2">VALUE</parameter>
 </parameters>
</root>                        

What method to use is depending on the implementation but as a rule you use the first method when there is only a small number of arguments that contain little data. To be able to determine exactly you can check the code in the .ASHX file on your Content Studio 5 Web site.

Naming of the .ASHX files

As mentioned above the WebAPI files are placed in the WebAPI sub directory of the administrative Web site and named after the namespace and class it represents. The different elements are separated with an underscore (_) so the file that represents the ContentStudio.Security.AccessControl class is named ContentStudio_Security_AccessControl.ashx.

Compatibility issues with CS 4.x

Besides from the obvious naming changes and the structural changes of the CS API most of the calls have parameters that are compatible with the new platform and the same goes for the return values. However there are a small number of changes that needs to be dealt with. In some calls, like the call to make Xml index filtering, one of more paramters have new names and in a few other calls the returned Xml is slightly different from the Xml returned by the CS 4.x predecessor.

The following code snippet shows how you can use the built in Content Studio java script functions getAdminURL, that returns the Url of the administrative web site and getXMLDOM that returns an DomDocument using a Url as input, to check the BROWSE permission on a document with a specific id. Both these methods work both in Internet Explorer and Mozilla Firefox and possibly in other Web browsers as well.

<script type="text/javascript">
function canBrowse(docId){
var url = getAdminURL() + 
          "WebApi/ContentStudio_Security_AccessControl.ashx?Action=ObjectAccessCheck" +
          "&ObjectType=D" +
          "&ObjectID=" + docId +
          "&AccessMask=1";
var dom = getXMLDOM(url, "GET"); 
if(dom)
{
   alert(dom.xml);
   var elem = dom.selectSingleNode("root/access");
   if(elem.text == "grant")
      return true;
   else
      return false;
} 
return false;
}
</script>

Return value from the Web api on success:

<root>
  <access>grant</access>
</root>
    

You can test the code with the following Html code that checks whether you can browse the document with id=1 and alerts the result.

<button type="button" 
onclick="if(canBrowse(1))
           alert('Access granted')
         else 
           alert('Access denied');">
Check a document
</button>
    

Migration strategies

• Parallell migration
  • Make a copy of the CS 4 site database and migrate it
  • Install the database on a new or existing installation of Content Studio 5. This can be the same server or a new server.
  • Make the changes necessary to make the migrated site work.
  • Verify the new CS 5 site
  • Make the new site public instead of the old CS 4 site

    Good

    Easy and fast

    Appropriate for small Web sites that can be considered read-only during the migration process

    Bad

    Changes made to the old site will not be reflected in the new Web site

    Not suited for sites that needs to be updated regulary

• Advanced parallell migration
  • Make a copy of the CS 4 site database and migrate it
  • Install the database on a new or existing installation of Content Studio 5. This can be the same server or a new server. This will be the temporary site.
  • Make the changes necessary to make the migrated site work.
  • During the migration keep accurat records of all document that need to be changed.
  • Verify the temporary CS 5 site
  • Make a new copy of the the CS 4 site database and migrate it.
  • Install the database on a new or existing installation of Content Studio 5. This can be the same server or a new server. This will be the new site.
  • Transfer the changes made to the temporary site to the new permanent site. This can easily made by using the built in advanced copying features in Content Studio.
  • Verify the permanent CS 5 site
  • Make the new site public instead of the old CS 4 site and remove the temporary site

    Good

    Makes the time where "lost changes" can occur shorter than the former method.

    Can give higher quality since the migration work can be done during a longer time span and with more carfully testing

    Appropriate for Web sites where changes needs to be done during most of the the migration process.

    Bad

    Requires more work

    There still is a chance that there will be changes that not will be reflected in the new Web site.

    Not suited for sites that needs to be constantly updated.

• Parallell migration with content syncronization
  • Make a copy of the CS 4 site database and migrate it
  • Install the database on a new or existing installation of Content Studio 5. This can be the same server or a new server.
  • Carefully document all the EPT categories where changes on the old Web site will be made during the migration
  • Make the changes necessary to make the migrated site work.
  • Verify the new CS 5 site
  • Copy all EPT categories where changes can be made from the old
  • Make the new site public instead of the old CS 4 site

  • Good

    Easy and fast

    Appropriate for small Web sites that can be considered read-only during the migration process

    Bad

    Changes made to the old site will not be reflected in the new Web site

    Not suited for sites that needs to be updated regulary