ASPX versus Portal Engine development in Kentico CMS


We are often asked about the two development models we offer in our solution, specifically which model the customers should use for their development, which one is better and what are the differences. This post should help you when you are not familiar with these differences to decide which one would you like to use for your development.

Short version

If you don't know the development models, or if you are not that experienced developer, and if you want your web site to be developed quickly, choose the Portal Engine. If you don't like design modes and visual programming, but like writing your code by yourselves, choose ASPX model (ASPX page templates).

If that is not enough information for you at this point or you are not yet decided, read further.

Long version

Once upon a time ... actually in the times of Kentico CMS version 1.x and Web 1.0 there was only the ASPX page templates model. It required the Visual Studio and lots of coding experience, but it could produce nice templated pages. Later, in version 2.0, the new development model was introduced in Kentico CMS, providing the portal UI experience where you could develop your web site from your web browser, without any special needs for the VS. This model evolved in what you now know as the Portal engine with all its features. Where you can develop same nice page templates much easier.

There are some basics that are same for both models. As you probably know, each page can be assigned with the page template. Page template is basically the definition of how the page looks like, and when it is displayed in the context of specific page, it feeds the content into its controls and display the content as the live page. When somebody requests the page URL (e.g. /Home.aspx), the path is internally rewritten to the physical page which can handle the rendering, and the aliaspath parameter analyzed from the URL is added to the URL by the rewriting engine, like this: <template url>?aliaspath=/Home. The page gets the path from query and sets up all the controls which are based on it. With ASPX, the template URL is specific physical page implemented by you, in the location you choose. With Portal engine, the template URL is always /CMSPages/PortalTemplate.aspx, which is the page that can load the structure of the page template dynamically from the database and hierarchically combine the levels of templates, so there is no need for any implementation of physical pages.

ASPX model

The ASPX page template (as the physical file) must be completely implemented by you, so you define all the controls and dynamic content programatically. Here is the example of the CorporateSite News page template code:

<%@ Page Language="C#" MasterPageFile="Root.master" AutoEventWireup="true" CodeFile="News.aspx.cs" Inherits="CMSTemplates_CorporateSiteASPX_News" ValidateRequest="false" %>
<%@ Register Src="~/CMSWebParts/navigation/cmsbreadcrumbs.ascx" TagName="breadcrumbs" TagPrefix="uc1" %>
<%@ Register Src="~/CMSWebParts/Viewers/cmsrepeater.ascx" TagName="repeater" TagPrefix="uc1" %>
<asp:Content ID="cntMain" ContentPlaceHolderID="plcMain" Runat="Server">
  <!-- Container -->
  <div class="newsSummary">
    <cms:WebPartContainer ID="wpcBreadCrumbs" runat="server" ContainerName="Box.Gray">
      <uc1:breadcrumbs runat="server" ID="BreadCrumbs" ShowForDocumentTypes="CMS.News" /> 
      <cms:CMSEditableRegion runat="server" ID="HeaderText" RegionTitle="Header text" RegionType="TextBox" /> 
    <asp:Panel ID="pnlNews" runat="Server" >
      <cms:CMSEditableRegion runat="server" ID="ContentText" RegionType="HtmlEditor" /> 
    <uc1:repeater runat="server" ID="NewsRepeater" ClassNames="CMS.News" OrderBy="NewsReleaseDate DESC" TransformationName="CMS.News.NewsWithSummary" SelectedItemTransformationName="CMS.News.NewsDetail" PagingMode="querystring" PagerPosition="bottom" ResultsPosition="top" ShowNewButton="True" NewButtonText="Add news&lt;br /&gt;" ShowEditDeleteButtons="True" /> 
    <div style="padding:10px 0">
      <asp:HyperLink ID="lnkRss" runat="server">
        <asp:Image ID="imgRss" runat="server" BorderWidth="0" /> 

With the code behind:

using System;
using System.Web;

using CMS.CMSHelper;
using CMS.UIControls;
using CMS.GlobalHelper;

public partial class CMSTemplates_CorporateSiteASPX_News : TemplatePage
  protected void Page_Load(object sender, EventArgs e)
    if (CMSContext.CurrentDocument != null && CMSContext.CurrentDocument.NodeClassName.ToLower() != "")
      wpcBreadCrumbs.Visible = false;
      pnlNews.Style.Add("margin-bottom", "20px");
    this.lnkRss.NavigateUrl = this.ResolveUrl("~/CMSPages/NewsRss.aspx");
 &&;&&; this.imgRss.ImageUrl = this.ResolveUrl(UrlHelper.ImagesDirectory + &quo&;/rss.gif&quo&;);
&&;&&;&&; this.imgRss.AlternateText = &quo&;Rss&quo&;;
&&; }

And the master page will look like this:

<%@ Master Language="C#" AutoEventWireup="true" CodeFile="Blank.master.cs" Inherits="BlankASPX_BlankMaster" %>
<html xmlns="">
<head runat="server" enableviewstate="false">
    <title runat="server">My site</title>
    <asp:literal runat="server" id="ltlTags" enableviewstate="false" />
<body class="<%=BodyClass%>" <%=BodyParameters%>>
    <form id="form1" runat="server">
        <asp:ScriptManager ID="manScript" runat="server" />
        <cms:CMSPageManager ID="CMSPageManager1" runat="server" />
        <p>Any master page content you can think of ...<p>
        <asp:ContentPlaceHolder ID="plcMain" runat="server">

With code behind:

using System;
using System.Web;

using CMS.CMSHelper;
using CMS.UIControls;

public partial class BlankASPX_BlankMaster : TemplateMasterPage
    protected override void CreateChildControls()

        this.PageManager = this.CMSPageManager1;

    protected override void OnPreRender(EventArgs e)

        this.ltlTags.Text = this.HeaderTags;

You can see you have to specify the master page manually, and create the master page by yourselves, see more code in our sample web templates, in the web site installation folder /CMSTemplates.

Basically, the ASPX page template is just standard ASPX page using our displaying controls on it. The only thing you need to ensure is that it inherits specific class from the CMS.UIControls namespace, which is TemplatePage for .aspx pages and TemplateMasterPage for master pages. That gives the page the main, basic functionality. For the master page (or the page without master page), you need to assign the title tags and some other parts of the page (DocType, BodyClass, etc.) with specific properties from CMSContext.

That's pretty much all you do, just develop almost standard ASPX pages, so you need to be the ASPX developer to create or alter the page templates. As I told you, that was the only way how you could do this with version 1.x and you would need to write all that code by yourselves. As you will see now, you do not need so much knowledge when developing with Portal engine.

Portal engine (recommended)

Portal engine is basically the design-mode UI which allows you to define your page from the admin interface. You only need to know the HTML and basics of ASPX and you can do the same as in the ASPX development mode, and even better. The portal engine development looks like this: You open the admin interface (the CMSDesk), browse to the document and click on the Design tab which is present for all the pages which use the Portal engine page template. On the design tab, you can see the visual representation of the Web parts (controls representation in the portal mode), with the preview of their content and a small handle (the blue box with name of the web part and buttons) which you can use to drag and drop them from one zone to another. The Web part zone (the orange box) is a special control that you place to the layout and you can put the web parts in it and manage them. The green box is called the PagePlaceholder and its function is very similar to the ContentPlaceholder control, it basically creates a window to the next level of the page where the next template will be inserted.

The good thing about portal engine is that you can use this placeholders to very simply create any number of visual inheritance levels you want, just by adding the PagePlaceholder web part on the template and define the template for the child document. In the ASPX mode, you would need to create several levels of master pages and write a lot of code in them.

The only code you actually need to write is the layout of the page with web part zones. Layout is the ASPX code so you can put the controls in it, but you can also just put HTML code in there to just define the HTML layout. Then you put web part zones using code like this <cc1:CMSWebPartZone ID="zoneTop" runat="server" /> (it is a standard ASPX control) and from this point on, you don't need to write any more code, you can just work with the web parts objects without programming.

So the layout will look like this:

<!-- Container -->
<div class="newsSummary">
  <cc1:CMSWebPartZone ID="zoneLeft" runat="server" />

And you just put the web parts in it using the UI:

You can simply set the web part properties by clicking the properties button, encapsulate them with containers using their properties and get much more from them (like using Update panel for the web part just by checking the box "Use update panel"). You would have to write all this in the code.

The actual web parts are located in the /CMSWebParts directory of your web site so you can change their code, create your own or just change the layout using the web part properties dialog. That would be another post on what all you can do with them, so I think that's enough for now.

How to combine portal engine with ASPX page templates

Actually, it is possible to use both approaches on your web site. You can use the Portal engine on some sections and you can use the ASPX page templates on other sections. The only limitation is that you cannot combine the approaches, which means that you cannot combine ASPX master pages (or pages) with visual inheritance of Portal engine or the other way. If the page uses one mode, it cannot use the other mode at the same time, or combination of modes.

There is one exception for each mode:
ASPX model: Since the web parts are just standard ASCX controls, just inherited from our special class CMSAbstractWebPart, it can be used on any page so you can use the web part controls in the ASPX mode, just without the nice features that are in the common properties of web parts and available only in Portal engine (like the UpdatePanel one, etc.).

Portal engine: You can write any ASPX code to the layout of the page template so you can combine Web part zones with standard ASPX code.

There is a topic in our documentation which describes the recommended way how to share controls (or master page) between ASPX and Portal mode. Basically, you encapsulate the controls in the user control which you can use on the ASPX page and load with special web part in Portal engine. You can find it here.


I am pretty sure that you would ask about how the performance looks like when you compare both approaches. Good news is that the performance of Portal engine and ASPX pages varies only by few percent. Bad news is that I cannot tell you which one is faster because it varies based on what the page contains, some page can be faster in Portal mode, some in ASPX mode. In general, there is no actual difference between them from the performance point of view. That means that you shouldn't decide which one you will use based on this.


ASPX mode
  • You develop from Visual studio or Visual Web Developer
  • You have complete control over your web page code, but you have to write all the code by yourselves
  • You can use the same controls as in Portal engine, because the web parts are reusable
  • You cannot use the web part zones in the ASPX page template and get the portal engine functionality
Portal mode
  • You develop from your web browser, not from Visual studio, with the possibility to check-out the code to the disk and edit it from Visual studio if you need it
  • You don't need to have such detailed knowledge of ASPX
  • You have complete control over the visual inheritance
  • You can put any ASPX code to the layout of the page so you can combine ASPX and portal engine approach
  • You can use the out-of-the box extended functionality of the web parts (like UpdatePanel, etc.)
  • You can use macros directly in the web parts properties (I will write a deep-dive post on macros soon)
  • You can simply customize the layout of the web parts
  • The possibilities of the web parts will extend in future while ASPX model stays pretty much the same
How to decide

You should decide based on which type of development you like more. For me, it is always the Portal mode, because you can implement from your browser, you can set the properties using the selectors and moreover, lots of features are available only through the properties, without the need to write the additional code. And from the CTO's point of view, I must say that there isn't much ve can improve in ASPX mode, since you are the one who is writing the code, but we can introduce much more new features in the Portal engine mode, just by defining and implementing new properties handled by the abstract web part class.

Still, it is up to you to decide ... so good luck with that ;-)
Share this article on   LinkedIn

Martin Hejtmanek

Hi, I am the CTO of Kentico and I will be constantly providing you the information about current development process and other interesting technical things you might want to know about Kentico.


Martin Hejtmanek commented on

Hi nvpat,

All portal pages run through ~/CMSPages/PortalTemplate.aspx, so you should probably be able to modify it to provide more form elements or put things outside of the form. I din't try it, so let me know the results if you try it. I think it should be possible.

nvpat commented on

Hi all.

I've discovered at least one thing which can be done with ASPX templates which cannot be done with the portal engine:

Putting more than one <form> element on a page:

In an ASPX template, you can put one or more additional HTML <form> elements (without the runat="server" attribute) outside of the ASPX form. In the portal engine, *everything* is inside the ASPX form, so additional <form>s are impossible.

I have found, in some cases, additional <form>s to be indispensible for getting around the major drawbacks of the ASPX postback model.

Martin Hejtmanek commented on

Hi Gaurav,

If you are experienced, I do not really see any main reason to use ASPX for something that you couldn't do in Portal. If you are begginner, ASPX may give you more control over the overall page markup (you may have everything written from scratch) but for a cost of lesser flexibility in the future. Myself, I am always choosing and recommending Portal engine.

Gaurav commented on

Will you please explain the one main reason for why to use ASPX templates instead of Portal Engine?

Please give an example where ASPX Template is the only solution instead of Portal Engine

Martin Hejtmanek commented on

Hi Neil,

Yes, you definitely can. As you can see, the web part zones in the layout are just regular controls, because the layout code is just another user control used as a template (very similar to transformations, just without the databinding), so you may write just any ASPX code to it. I recommend to divide your current layout to two areas:

1) Separable standalone components - Best way how to handle them is to create custom web parts out of them.

2) The rest, which is the layout of the page - Put this other code to the layout.

neil-fourmangos commented on

Quick question re: "You can put any ASPX code to the layout of the page so you can combine ASPX and portal engine approach"

We built out a site using the aspx page. I'd like to convert it to portal. Something tells me this is "easier" to do than starting from scratch yes?


Martin Hejtmanek commented on

Hi Neil, there are two ways how to export the web part:

1) Directly from the Web part management interface, using the action "Export selected". In such case, your web part gets with its codebehind file and the directory <webpartname>_files in the webpart directory. In such case, no additional files are exported

2) Using the Export objects action from the site list in Site manager, where you can choose whether the global files should be exported, in such cases, certain directories are exported as well, you can find the list here:

That way, you can place your additional App_Code classes to the export package. I Suggest you try different locations and different export types to see what gets included into your package.

Neil commented on

We're just starting using Kentico and as a developer I've been tasked with writing several custom web parts, my question is where do I place class files if I wish to export the web part so they're easy to load onto new installations?

Elijah commented on

I JUST had this conversation with a prospective client yesterday. Thanks for publishing a nice article that I can refer to in the future when explaining this to new clients.

My thoughts for the client were this: I've been using the portal engine for all my projects, large and small, and I haven't found ANYTHING it can't do. If there's some custom code or anything you need to do that isn't part of the built-in capability, you just write a web part and register it with Kentico. In fact, this model forces you to use better programming practice. It encourages modular development and reusable code.

Long live the Portal Engine!