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:
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.
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.
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.
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.
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<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
VB.NET<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
Html<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.
To | Class to use | Remarks |
---|---|---|
Read document information |
|
Loads most of the properties for any document with or without content data. |
Read document information with only BROWSE permissions |
|
Use on an anonymous web site to obtain document information |
Update or create any document except for uploaded files |
|
Handles the check in / check out process automatically |
Read EPT document data |
|
Use the CSDocumentInformation class to load the document into the EPTXmlTextParser. |
Create and update EPT document data |
|
|
Filter EPT document data |
|
Can return Xml as before or a |
Check permissions |
|
|
Read MLC information |
|
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
-
FILE.ashx?action=METHODNAME¶m1=VALUE¶m2=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.
JavaScript<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:
Xml<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.
Html<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