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:

Changing the code to VB.NET

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

AS components in version 5

AS components in version 5
Component Folder Remarks
AD Object Picker AS_Security  
Add to CS favorites AS_Miscellaneous Included in version 5.1 and later
Add to favorites AS_Miscellaneous Included in version 5.1 and later
Anonymous Writer AS_EPT  
Count children AS_Document  
Date picker AS_Date  
Delete document AS_Document  
Document information AS_Document The document usage field, used in version 4, exists but no longer return valid data
Document level information AS_Document  
Document list AS_Miscellaneous  
Document writer 4.0 AS_EPT  
EA Send mail AS_EPT  
EPT button AS_EPT  
Force login AS_Security  
Group Include or Redirect AS_Security  
Image dialog AS_EPT  
Insert advanced image AS_EPT  
Insert author AS_Document  
Insert back link AS_Document  
Insert children AS_Document  
Insert Comma Separated Documents AS_Document  
Insert date AS_EPT  
Insert document AS_Document  
Insert document by MLC Language AS_MLC  
Insert document from URL AS_Document Included in version 5.1 and later
Insert document tree path AS_Menu  
Insert encrypted email link AS_Security  
Insert field 2.0 AS_EPT  
Insert field with objects AS_EPT  
Insert filtered documents 2.0 AS_EPT  
Insert flash content AS_Miscellaneous  
Insert image link AS_EPT  
Insert link 2.0 AS_EPT  
Insert link by permission AS_Security  
Insert link if write permission AS_Security  
Insert link to other language AS_MLC  
Insert link to self AS_EPT  
Insert links to MLC siblings AS_MLC  
Insert menu 2.0 AS_Menu  
Insert menu 3.0 AS_Menu  
Insert multiple documents AS_Document  
Insert number of children AS_Document  
Insert pagebreak for printing AS_Miscellaneous  
Insert querystring AS_Miscellaneous  
Insert RSS Feed AS_Miscellaneous  
Insert script AS_Miscellaneous  
Insert simple menu AS_Menu  
IP Address access restrictions AS_Security  
Language dropdown AS_MLC  
Last modified AS_Document  
Link dialog AS_EPT  
List Children AS_Document Included in version 5.1 and later
List documents 2.0 AS_Document  
List filtered documents in dropdown advanced 2.0 AS_EPT  
List pageable filtered documents 2.0 AS_EPT  
Load browser cookie AS_Miscellaneous  
Load user info cookies AS_Security  
Mail form AS_Miscellaneous  
Notification list AS_Workflow Included in version 5.1 and later
Open window AS_Document  
Preview draft button AS_Document Included in version 5.1 and later
Randomize documents AS_Document  
Redirect if not authorized AS_Security  
Redirect on host AS_Miscellaneous  
Redirect to other document AS_Document  
Redirect to page AS_Document  
Rotate documents AS_Document  
RSS 2.0 Feeder AS_Miscellaneous  
Script filtered documents AS_EPT  
Seach result for categories AS_Search  
Search form AS_Search  
Secure download AS_Security  
Set credentials for delegate requests AS_Security Included in version 5.1 and later
Set to startpage AS_Miscellaneous  
Show date AS_Date  
Show document hierarchy AS_Document  
Tell a friend AS_Miscellaneous  
Time picker AS_Date  
Tooltip AS_Miscellaneous  
Track changes AS_Miscellaneous Included in version 5.1 and later
Tree info AS_Menu  
Tree menu AS_Menu  
Tree navigator AS_Menu  
Upload file 2.0 AS_EPT  
User dialog AS_Security  
Web Map A-Z 2.0 AS_Menu  
Web tree AS_Menu  
Webitor 2.0 AS_Miscellaneous  
Webitor toolbar AS_Miscellaneous Included in version 5.1 and later  
Webitor templates AS_Miscellaneous Included in version 5.1 and later
WF disable objects AS_Workflow Included in version 5.1 and later
WF perform action AS_Workflow Included in version 5.1 and later
WF set participants AS_Workflow Included in version 5.1 and later
WF status AS_Workflow Included in version 5.1 and later

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.

Deprecated AS components
Component Folder Alternative
Document writer 3.0 AS_EPT/Archive In most cases, it is better to use Document writer 4.0

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.

Outdated AS components
Component Alternative
Document Writer Anonymous Writer
Document Writer 2.0 Anonymous Writer
Forum Writer Anonymous Writer
Insert Document Filtered On Date Insert filtered documents 2.0
Insert EPT date Insert Date
Insert field Insert Field 2.0
Insert field with breaks Insert Field 2.0
Insert Filtered Documents Insert filtered documents 2.0
Insert filtered documents advanced Insert filtered documents 2.0
Insert image Insert advanced image
Insert link Insert link 2.0
Insert link to parent Insert document tree path
Insert menu Insert menu 2.0 or Insert menu 3.0
Insert safe link Insert link by permission
List distinct EPT documents Script filtered documents
List documents List documents 2.0
List Filtered Documents List pageable filtered documents 2.0
List filtered documents advanced List pageable filtered documents 2.0
List filtered documents in dropdown List filtered documents in dropdown advanced 2.0
List filtered documents in dropdown 2.0 List filtered documents in dropdown advanced 2.0
List filtered documents in dropdown advanced List filtered documents in dropdown advanced 2.0
List pageable filtered documents List pageable filtered documents 2.0
Randomize filtered documents List pageable filtered documents 2.0. In CS 5 this component has an option that randomly sorts the result.
Search result Seach result for categories
Show Username Load user info cookies can be used to store the user name. You can display the name from the user name sub cookie.
Upload file Upload file 2.0
Web map A-Z Web Map A-Z 2.0

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.

Removed AS components
Component Remarks
Add To Cart The simple Web shop has been removed in CS 5
AS EPT Form Security  
Change password  
Choose document  
Insert javascript  
Insert XML Tree  
Post Cart The simple Web shop has been removed in CS 5
PS Authenticated Login CS Data Storage has been removed in CS 5
PS BuildQueryCacheForSlot CS Data Storage has been removed in CS 5
PS ConnectToSlot CS Data Storage has been removed in CS 5
PS IfSlotExists CS Data Storage has been removed in CS 5
PS Login CS Data Storage has been removed in CS 5
PS Logout CS Data Storage has been removed in CS 5
PS Logoutbutton CS Data Storage has been removed in CS 5
PS Properties CS Data Storage has been removed in CS 5
PS Redirect if logged in or not CS Data Storage has been removed in CS 5
PS Register CS Data Storage has been removed in CS 5
PS Show Field CS Data Storage has been removed in CS 5
PS SlotID CS Data Storage has been removed in CS 5
PS Subscribe CS Data Storage has been removed in CS 5
PS Subscription properties CS Data Storage has been removed in CS 5
PS System SlotCleanUp CS Data Storage has been removed in CS 5
PS UnSubscribe CS Data Storage has been removed in CS 5
Select multiple documents
Set publish date
Show Cart The simple Web shop has been removed in CS 5

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.

Upcoming AS components
Component Schedule
Create PDF Part of PDF Server, planned for version 5.2
Create PDF of current page Part of PDF Server, planned for version 5.2
Insert link to pdf Part of PDF Server, planned for version 5.2

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

VB Script
Function IsEmptyData(data) 
  If data = "" Then
    IsEmptyData = True
    IsEmptyData = False
  End If
End Function
Result = IsEmptyData(EPT_GetFieldName("MyField"))
Response.Write "The field MyField is empty is a " & Result & " statement"

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
      Return False
    End If
  End Function
Dim Result As Boolean = IsEmptyData(CS_DataFields("MyField"))
Response.Write (String.Format("The field MyField is empty is a {0} statement", Result))

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.

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.

Usage of the high-level CS 5 API
To Class to use Remarks
Read document information ContentStudio.Document.CSDocumentInformation Loads most of the properties for any document with or without content data.
Read document information with only BROWSE permissions ContentStudio.Document.CSApprovedDocumentInformation Use on an anonymous web site to obtain document information
Update or create any document except for uploaded files ContentStudio.Document.CSSyncronizedDocument Handles the check in / check out process automatically
Read EPT document data ContentStudio.Document.EPT.EPTXmlTextParser Use the CSDocumentInformation class to load the document into the EPTXmlTextParser.
Create and update EPT document data ContentStudio.Document.EPT.SyncronizedEPTDocument  
Filter EPT document data ContentStudio.Document.EPT.XmlFilter Can return Xml as before or a XmlFilterReader object that can iterate through found documents.
Check permissions ContentStudio.Security.AccessControl  
Read MLC information  ContentStudio.Document.MLC.MLCInformation Provides a object oriented way to get information about a specific document, sibling documents, master documents and sibling languages. 

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
2 The parameters as an Xml document using the method POST
You will send a query string with the action argument

and POST an Xml document with the parameters and their values
  <parameter name="param1">VALUE</parameter>
  <parameter name="param2">VALUE</parameter>

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 +
var dom = getXMLDOM(url, "GET"); 
   var elem = dom.selectSingleNode("root/access");
   if(elem.text == "grant")
      return true;
      return false;
return false;

Return value from the Web api on success:


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" 
           alert('Access granted')
           alert('Access denied');">
Check a document

Migration strategies