Migrating Sitefinity 3 to 4 Deep Dive: API Changes

Migrating Sitefinity 3 to 4 Deep Dive: API Changes

December 13, 2011 0 Comments

The content you're reading is getting on in years
This post is on the older side and its content may be out of date.
Be sure to visit our blogs homepage for our latest news, updates and information.

The Sitefinity 4 Migration Module takes care of migrating pages and content items from Sitefinity 3. However, if you've done any custom development, such as custom user controls and modules that use the Sitefinity 3 API, you may find these controls need to be updated.

Namespaces and DLLs

In Sitefinity 3, most of the components were spread out amongst several DLL files, each with their own separate namespace. Sitefinity 4 reduced many of these to a single Telerik.Sitefinity.dll file so that all CMS classes share that common namespace.

This new API helps organize the Sitefinity namespaces. In Sitefinity 3, each module had a top-level namespace, such as Telerik.Blogs and Telerik.News. Sitefinity 4 places all of these modules under a new Telerik.Sitefinity.Modules namespace. Any additional required components of a module, such as Data Models, Configuration, and Widgets exist underneath their respective namespace.


Another advantage to this approach is a simplified upgrade path, reducing the number of libraries that need to be updated. If you are developing custom components, you only need the main Telerik.Sitefinity namespace to access most of the major components of Sitefinity.

Documentation and Examples

Instead of trying to create a definitive list of API changes, this post will instead highlight the major areas of documentation that developers coming from Sitefinity 3 will find useful.


Pages are organized as just another Sitefinity module, with their own Content Manager and API. If your custom controls and modules are accessing pages programmatically, you'll definitely want to look at the Sitefinity 4 Pages Documentation. Examples for the topics below are available using both the native content manager and the new Fluent API.

Content Modules

Content items such as News, Blog Posts, Events, etc. can be retrieved and manipulated using either their associated Content Manager or the new Fluent API. The Sitefinity 4 Modules Documentation includes examples of both methods for each native module.

Custom Modules

The simplest way to extend Sitefinity 4 is by creating a User-Control-based module. This means that all of the logic and user-interface components are contained in User Controls (.ascx files) that you place directly on a page. There are two options for this type of module:

  • Page Based Modules - created using the Backend Page Editor, dragging and dropping the controls onto the page manually
  • Intra-Site Modules - Installable and distributable modules that programmatically register pages and add controls on installation

You can also Sitefinity by making your own Content-based module, tying deeply into things like taxonomy, lifecycle, workflow, and permissions. This is a more advanced topic, and is available in the blog post series Creating Content-Based Modules.

However, the 4.4 release of Sitefinity will include a new Module Builder, that allows you to create new Content types (including all native Sitefinity features such as workflow, taxonomy, etc.) on the fly right inside of Sitefinity. More details will be available in Q1 after the release.

Sitefinity Controls (Widgets)

Widgets in Sitefinity 4 are still based on standard ASP.NET controls (.ascx files). However, there have been some changes to creating user-friendly control designers. For a detailed look at the process of creating several different types of Sitefinity 4 widgets, from simple to advanced, take a look at the following topics:

Other Changes

Here I hope to briefly list some common changes that have been frequently asked about by customers. This is by no means an exhaustive list, but I will update it based on feedback via our Sitefinity Discussion Forums. If you are having trouble locating something from Sitefinity 3, please feel free to submit a post so that I can update this section.

Navigation (SiteMenu)

While in Sitefinity 3, the main SiteMenu was a standard user control (ascx file), the navigation control in Sitefinity 4 is now a compiled web control. So if you wish to add the Sitefinity menu to a custom user control, you need to register it first, as shown here.

<%@ Register Assembly="Telerik.Sitefinity" Namespace="Telerik.Sitefinity.Web.UI.NavigationControls" TagPrefix="sf" %>
<sf:SiteMenu ID="SiteMenu1" runat="server" />

Breadcrumb Navigation

Although the breadcrumb control is planned to be included in the Sitefinity 4.4 release, you can recreate it now by following this blog post Working Breadcrumb Widget With Source.

Alternatively, you can add the standard ASP.NET breadcrumb control, as described by Ivan's first reply to this thread: Breadcrumbs in SF4.


The Progress Team

View all posts from The Progress Team on the Progress blog. Connect with us about all things application development and deployment, data integration and digital business.

Comments are disabled in preview mode.
Latest Stories in
Your Inbox
More From Progress
The New Mobile Development Landscape
Download Whitepaper
IDC Spotlight Sitefinity Thumbnail
Choosing the Right Digital Experience Platform to Improve Business Outcomes
Download Whitepaper
The Fastest Way to Build Mobile Apps With Cloud Data
Watch Webinar