Release notes - Kentico 12

Kentico 12.0 Service Pack (released June 26, 2019)

New features

MVC

• New alternative URLs feature for pages on MVC sites. Allows content editors and marketers to make individual pages available under any number of secondary URLs, without requiring changes in the application's routing code. See Enabling alternative URLs for pages and Adding alternative URLs for pages.
• New A/B testing feature for pages on MVC sites, which can be used to optimize content added via the page builder. See A/B testing pages.
• New page templates feature that can be used with pages on MVC sites. Page templates are prepared by the site's developers. Each template defines a specific page layout, which provides a starting point for content editors when creating or modifying pages. Existing pages based on templates can also be saved as new templates, including their page builder content. See Using page templates in MVC and Developing page templates in MVC.
• Added output filtering functionality that automatically resolves all virtual relative URLs on the side of the MVC live site (based on the environment where the site is actually running). This filter prevents content editors from creating invalid links in cases where the code of your MVC application does not explicitly handle resolving of URLs in page content. This functionality was added as part of the previously released hotfix 12.0.26.
• New API that enables intuitive configuration of output caching for pages containing personalized content (using the .NET VaryByCustom output caching feature). See Caching the output of personalized content.
• Boilerplate code added to the MVC project created when installing new MVC sites via the Kentico Installer. The additions consist of placeholder files and code for enabling the page builder and other Kentico features. Moreover, they ensure that first requests made to the MVC site immediately after the installation do not result in an error.

MVC – Page builder

• New API that allows simplified development of page builder components – Widgets, Sections and Page templates. The new development approach removes the need to manually implement a controller and view model for each component.
• New system form components that help create selector properties for page builder components: Media file selector, Page selector, and Path selector. Apart from the added selector form components, developers can also utilize JavaScript APIs to build the selectors within inline editors or custom form components. See Page and media selectors for page builder components.
• Added functionality and API for building modal dialogs, which helps developers implement advanced editors for the properties of page and form builder components. See Developing modal dialogs for builder component properties.
• New feature for page builder sections that allows developers to define section properties. Once the section properties are defined, content editors can adjust the appearance or behavior of the sections through section configuration dialogs.
• New base class for page builder section controllers. Provides a GetPage method that allows developers to access the page containing the currently processed section.
• The system now executes scripts added directly into the view code of page builder sections.

MVC – Form builder

• New File uploader form component that enables users to attach files as part of the submitted form. See Reference - System form components.
• Added the possibility to hide selected form components from the form builder's user interface. See Filtering form components.
• New Component is enabled validation rule for form fields using a component with the bool data type. Validates whether the field is selected or enabled (returns true).
• The system now executes scripts added directly into the view code of form builder sections.

Platform

• Data protection – The Data protection application now allows viewing of all visitors who have given consent agreements for individual consents.
• Macros – New Availability property in the macro rule editing dialog that indicates the intended execution environment of macro rules. Allows developers to hide macro rules for conditions where they would not work correctly (for example when evaluated by MVC live site applications).
• Email queue – When administrators view emails in the queue, the system now displays both the HTML and plain text versions of the message body (if both are specified for the given email).
• UniGrid – Developers can now define button actions within the configuration of UniGrid controls.
• Azure Search – New Fields property added to the event arguments of the CreatingDocument and AddingDocumentValue customization events. The property allows access to the collection of individual Microsoft.Azure.Search.Models.Field objects, enabling developers to modify field values of the corresponding document based on the field's configuration (such as the IsFacetable, IsFilterable flags).

Content management

• Preview – Added option in the Pages application for opening the Preview mode of pages in a new browser tab.

E-commerce

• API – New EcommerceEvents.ProductAddedToShoppingCart global event which can be handled in custom code. Triggers when a customer adds a product to their shopping cart.

On-line marketing

• Marketing automation – Added parameter to the Newsletter subscription marketing automation action, which allows automation steps to be configured to reflect the double opt-in settings of the related newsletter when subscribing. The update changes the parameter definition of the Newsletter subscription action step, which overrides any custom modifications of the step's parameters (for example adding a new field to the definition). If you have locally made such modifications, we recommend creating a separate custom action step (according to the Best practices for customization).

Updates and changes

• A/B testing – The format of the JSON data stored in the CMSAB<test name> cookie was updated due to the introduction of A/B testing for pages on MVC sites. The name of the VariantName data field was changed to VariantIdentifier (the field's value remains the same for tests on Portal Engine sites – the code name of the test variant assigned to the visitor).
• Activities – Updated approach for adding scripts that log page-related activities on MVC sites. Use the new Html.Kentico().ActivityLoggingScript extension method instead of directly loading and rendering scripts via the KenticoLogActivityScript route. The original approach remains functional, but the new extension method is recommended. See Logging activities on MVC sites.
• Azure Search – The Microsoft.Azure.Search⁠ (opens in a new tab) NuGet package provided in Kentico projects was updated to version 5.0.3 (both in the Kentico web project and as a dependency of the Kentico.Libraries NuGet package). All existing search implementations should remain functional – the Azure Search SDK does not contain significant breaking changes for this version update. For detailed information, see Upgrading to the Azure Search .NET SDK version 5⁠ (opens in a new tab).
• Countries – The display name of the default Macedonia country was updated to North Macedonia. The code name and country codes remain unchanged.
• Form builder – Removed the option to set the Required flag for form fields using the Checkbox system form component in the form builder properties panel. Use the new Component is enabled validation rule to check whether Checkbox fields are selected.
• LinkedIn authentication – The LinkedIn authentication feature available for Portal Engine websites was updated to use version 2.0 of the LinkedIn API. The original implementation using version 1.0 of the API is no longer supported by LinkedIn (see the Developer Program Updates⁠ (opens in a new tab) announcement for details).
  • Note: If you are a LinkedIn Partner and use the r_fullprofile permission for your application, you need to manually set the new Requested permissions (scope) setting in Kentico to match the name of the permission: r_fullprofile. See Creating your LinkedIn application.
• Media libraries – All newly created media libraries have their library-level permissions set to Nobody by default (for improved security). Set the permissions according to your site's requirements if you wish to allow users to work with the media library without the administrator privilege level or permissions for the entire Media libraries module.
• Page database structure – The Service Pack adds the DocumentPageTemplateConfiguration and DocumentABTestConfiguration columns to the CMS_Document database table and the related View_CMS_Tree_Joined view. Any custom views, queries or other database objects that rely on the structure of these columns need to be updated.
• Workflow – Most locations in the editing interface of the Pages application no longer offer the option to disable sending of notification emails when moving pages between workflow steps. If required, pages can be moved between workflow steps without notification emails by switching to the Properties -> Workflow tab and clearing the Send notification emails check box.

Fixed issues

• Banner management – Deleting a banner category did not create export delete tasks for the contained banner objects (even when logging of delete tasks for export purposes was enabled).
• Contact management – Editing form data on the Recorded data tab in the Forms application could in rare scenarios cause an unintended update and merging of the on-line marketing contact who submitted the given form record.
• Continuous integration – An error occurred when restoring continuous integration data if the repository contained a binding record representing a personal category assigned to a page (cms.documentcategory).
• Custom tables – When running in a web farm environment, web farm synchronization tasks related to certain custom table operations failed (creating or deleting a custom table, deleting a custom table data item).
• Customization – Under certain circumstances, custom implementations of system services registered using the RegisterImplementation attribute were overridden by their default system implementations.
• Groups – The Group selector on the Media libraries tab of the media and link selection dialogs did not evaluate group read permissions correctly on instances containing multiple sites (each with its own groups).
• E-commerce – If a product was added to a customer's shopping cart automatically as a result of a Buy X Get Y discount, the system incorrectly logged web analytics conversions specified via the Add to shopping cart conversion name e-commerce setting. Such conversions are no longer logged for automatically added products after applying the Service Pack.
• Form builder (MVC) – If the Maximum length validation rule was assigned to a form field with a lower value than the used form component's database column size constraint, the validation error messages for users incorrectly displayed the higher database constraint limit (instead of the actual limit specified by the validation rule).
• Form builder (MVC) – Form validation error messages were displayed incorrectly when the validation failed for multiple rules assigned to a single field.
• Form engine – Form field data macros entered within the field editor were not resolved correctly and errors occurred in special cases when the form used a custom layout of the ASCX type.
• Forms – The option to set a custom submit button image was not available for forms on MVC sites (the Submit button image setting was not displayed when editing forms on the General tab in the Forms application).
• Import toolkit – The Import Toolkit utility incorrectly caused logging of staging and web farm synchronization tasks when running a simulated import of data (if staging and/or web farms were enabled on the target instance).
• Installation – An error occurred during the installation if the Register to IIS option was enabled, and the selected IIS Website did not contain at least one Site Binding of the 'http' type (for example when the only binding was of the 'https' type).
• Installation – After installing an MVC site into an existing instance, the system did not ensure that web farm functionality was enabled and started correctly. This could lead to issues in the administration interface, for example not being able to switch to the new site in the main site selector until the application was restarted.
• Installation – If an installation using the MVC development model was configured to install a site into an existing project of the web site type, and the target location was then changed to install a new independent MVC project, the installer incorrectly created a Kentico administration project of the web site type (instead of the web application type which should always be used for MVC installations).
• Installation – If an installation process that was in progress got cancelled by a user and then restarted, the subsequent installation failed unless the entire Installer application was relaunched.
• Installation – Installing a new MVC site with a hyphen ('-') character in the site name created an MVC project with invalid code that could not be compiled.
• Marketing automation – An error occurred when a marketing automation process ran the Newsletter subscription step with the Unsubscribe from newsletter action selected.
• Object versioning – Clicking the Reset button of the object filter in the Recycle bin application did not correctly refresh the list of deleted objects.
• On-line marketing – Logging of web analytics and contact activities did not work when a page was displayed after a visitor authenticated through a LinkedIn account using the LinkedIn logon web part.
• Page types – After cloning a page type with child query objects, the cloned queries had invalid names that could not be re-saved.
• Performance – Redundant database queries were called during application start when loading the system's data classes (object types, page types, etc.). The process was optimized to reduce the volume of loaded data.
• Personas – An error occurred when cloning persona rules that were calculated at least once for the given persona.
• Web farms – When running in a web farm environment, images uploaded to a form through a field using the Upload file form control with automatic resizing configured were synchronized to other web farm servers in their original size, before the resizing was performed.

Kentico 12.0 (released November 27, 2018)

System requirement changes

• The minimum required version of Microsoft .NET Framework is now 4.6.1.
• Removed support for Visual Studio 2015 development environments.
• Kentico 12 requires version 2.0.1 or newer of the Microsoft.CodeDom.Providers.DotNetCompilerPlatform⁠ (opens in a new tab) NuGet package (.NET Compiler Platform ('Roslyn')⁠ (opens in a new tab) compiler). When upgrading from older versions, the package is updated automatically.

New features

Platform

• Installation – The Installer now allows creation of MVC sites, including both the MVC site project and the connected Kentico administration project. New MVC projects can be connected to existing administration instances.
• Installation – The Quick installation now installs the MVC implementation of the Dancing Goat sample site.
• Kentico Installation Manager – The utility now displays a warning if the hotfix version of an instance is different than the Kentico.Libraries code package version used by connected MVC projects (only applies to projects located within the main installation folder of the given instance).
• Continuous integration – The location of the continuous integration file repository can now be configured using the CMSCIRepositoryPath web.config key. New MVC projects created by the installer use this configuration by default to have a shared repository with the related Kentico administration project.
• Web farm – When using Automatic web farm mode, the system now adds an _AutoExternalWeb suffix to the generated server names for external web applications running the Kentico API (typically MVC live site applications). The suffix ensures unique server names when hosting the synchronized applications on the same machine without using virtual directories (e.g. on different domains).
• The system now uses reCAPTCHA V2 (the original reCAPTCHA API version is no longer functional). Users can now prove they are not a robot simply by clicking a checkbox. See Spam protection (CAPTCHA). This functionality was also added for the previous version in hotfix 11.0.10.
• Modules – New option to set a visibility condition for the help topics of module UI elements.

Content management

• MVC – New page builder feature that allows content editors and other non-technical users to create content using widgets on MVC sites directly from the Pages application. Developers need to create a suitable set of widgets for the site.

• MVC – New form builder feature for composing forms on MVC (content-only) websites.

  • Allows the creation of forms containing "smart fields", which are only displayed on repeated views of a form, as a replacement for other fields that were already filled in by a given visitor. See Using smart fields in forms.
  • Developers can extend the available form options by creating custom form components, validation rules, visibility conditions, etc. See Form builder development.

• Forms – The On-line form web part and widget has a new property that determines whether the HTML output of the resulting form consists of a table or <div> elements. The property only applies to forms that use the automatically generated layout (forms with a custom layout are not affected).

On-line marketing

• MVC – Page builder widgets allow users to create multiple personalization variants, which are then displayed to a different audience based on predefined conditions. Developers need to define the condition types used for the personalization.
• Contact management – The geolocation feature for contacts was updated to work with MaxMind's GeoIP2 Databases.

E-commerce

• API – New business API that makes it easier for developers to write custom code for managing shopping cart content and the overall checkout process. See the API examples for more information.
• Coupon codes – Transformations for displaying coupon codes added to the customer's shopping cart now provide an IsApplied data property, which can be used to evaluate whether codes are still valid. This functionality was also added for the previous version in hotfix 11.0.29.

Social & Community

• Facebook integration – Added support for app secret proof parameters when communicating with integrated Facebook apps. See Connecting Kentico to social media and Facebook authentication. This functionality was also added for the previous version in hotfix 11.0.8.

Fixed issues

Breaking changes (functionality, data structure, API)

NuGet packages for MVC development

• The NuGet integration packages used for the development of MVC sites were reorganized. Most of the packages will not be released for Kentico 12, and their content is either combined into the new Kentico.AspNet.Mvc package, or replaced by API provided as part of the Kentico.Libraries package.
  • Kentico.Activities – l ogging of activities in MVC projects is now performed via the API provided by the Kentico.Libraries NuGet package. The Internal search activity type is no longer logged automatically. To log such activities, you need to manually call the API of a logging service in your site's code. See Enabling activity tracking on MVC sites and Logging activities on MVC sites.
  • Kentico.ContactManagement – tracking of contacts in MVC projects is now performed via the CMS.ContactManagement API provided by the Kentico.Libraries NuGet package . See Tracking contacts on MVC sites.
  • Kentico.Ecommerce – to work with product data and perform other e-commerce actions, use the CMS.Ecommerce API provided by the Kentico.Libraries NuGet package. See the Developing on-line stores chapter.
  • Kentico.MediaLibrary – to generate media file URLs in MVC projects, use the GetDirectUrl or GetPermanentUrl methods of the MediaLibraryHelper class (from the CMS.MediaLibrary namespace). Note that the GetPermanentUrl method now generates URLs with extensions based on the site's URLs and SEO -> Files friendly URL extension setting. See Displaying content from media libraries.
  • Kentico.Newsletters – to manage email feed subscriptions in MVC projects, use the CMS.Newsletters API provided by the Kentico.Libraries NuGet package. See Handling newsletter subscriptions on MVC sites.
  • Kentico.Search – to search through locally stored indexes in MVC projects, call the SearchHelper.Search method available in the CMS.Search namespace (provided as part of the Kentico.Libraries NuGet package) . See Building a search interface for local indexes in MVC.
• Installation of the new Kentico.AspNet.Mvc package does NOT automatically perform certain actions, which were done by the original Kentico.Web.Mvc package. Most importantly:
  • Enabling of individual Kentico MVC integration features (within an automatically added ApplicationConfig.cs file). All such features need to be enabled manually on application start using the methods of the ApplicationBuilder instance. An empty ApplicationConfig.cs file is included within new MVC projects created via the installer.
  • Setting the runAllManagedModulesForAllRequests="true" attribute for the <modules> element in the <system.webServer> section of the MVC project's main web.config file. Instead, individual handlers are added for specific paths that require custom extensions (getattachment, getmedia, etc.). If you require the runAllManagedModulesForAllRequests attribute, you need to enable it manually.

Platform

• The installer no longer provides the option to create Kentico projects targeting .NET Framework 4.7. Installed projects now always target the minimum supported .NET Framework version (4.6.1). If you wish to target a higher version, you can set it manually for your project in Visual Studio.

• The structure of the XML files used to store configuration for the command line installation was changed. Certain element attributes were removed and some new attributes were added. See Command line installation - XML configuration for details.

• The version of the Newtonsoft.Json⁠ (opens in a new tab) NuGet package used by the Kentico web project was updated to 11.0.2. If you use this package in any custom projects within the Kentico solution, you need to consolidate the package versions after performing the upgrade.

• The Kentico.Libraries.Tests NuGet package (CMS.Tests library) no longer supports the Microsoft unit test framework. When writing automated tests for code using the Kentico API, you need to either use the NUnit⁠ (opens in a new tab) testing framework or create tests without leveraging the CMS.Tests library.

• The default name of the SQL server instance used by isolated integration tests was changed to (localdb)\MSSQLLocalDB. Testing projects that have a custom database instance name assigned through the CMSTestDatabaseInstanceName app.config key are not affected.

• The Kentico web project no longer contains or uses the CMSDependencies folder. The stored third-party libraries are now integrated via NuGet packages.

• The Use progressive caching setting (in the System -> Performance category of the Settings application) was removed. The progressive caching feature remains in the system and is always enabled (optimizes access to data for concurrent threads).

• The following values were removed from the SystemContext object in macro expressions:

  • CurrentTrustLevel
  • IISWebSiteName
  • IsFullTrustLevel

• The following changes were made to Kentico assemblies (DLLs). Any references from custom projects to the old assemblies need to be updated. The merges do not change the related API and namespaces.

  • CMS.Localization.dll merged into CMS.Globalization.dll
  • CMS.CKEditor.Web.UI.dll merged into CMS.Base.Web.UI.dll
  • CMS.ModuleLicenses.dll merged into CMS.Modules.dll
  • CMS.ModuleLicenses.Web.UI.dll renamed to CMS.Modules.Web.UI.dll

Content management

• The NotFoundHandler feature for handling of 404 errors on MVC sites was removed. We recommend handling 404 errors via IIS.
• Obsolete MVC functionality related to the CMSApp_MVC project was completely removed from the system. This includes page templates of the MVC type, as well as MVC URL paths of pages and their aliases.
• The demo code files for responsive images were removed from the App_Code (or Old_App_Code) folder of the Kentico web project. Instead, the same code samples are available under the CodeSamples folder in the Kentico program files directory, and integrated into the default web project as part of the removable CMS.DancingGoat.Samples.dll assembly.

REST service

• When retrieving page data using the REST service, the CombineWithDefaultCulture parameter is now always set to false when called together with the AllCultures culture constant. Requests with the AllCultures constant will retrieve page versions in all available cultures regardless of the CombineWithDefaultCulture parameter being set or not.

On-line marketing

• The geolocation feature was updated to work with Maxmind's GeoIP2 Databases. If you use geolocation, you need to add the newer GeoLite2 or GeoIP2 database files into your web project. See Using geolocation for contacts.
• The system no longer logs activities of the User login type for sites using integrated Windows Authentication (where "authentication" occurs on each request).

Social & Community

• The Friends and Messaging features were removed from the system, along with all related components (web parts, widgets, email templates, form controls). See the Upgrade instructions for detailed information about the removed web parts.
• The Facebook integration functionality was updated according to changes and new security requirements in the Facebook API. See Connecting Kentico to social media and Facebook authentication. This updated functionality was also added for the previous version in hotfix 11.0.42.
• Integration with the goo.gl URL shortener for social media posts was removed from the system. The Google URL Shortener service is discontinued⁠ (opens in a new tab) and its API will stop working after March 30, 2019. Before upgrading existing instances to Kentico 12, you need to remove all usage of the goo.gl shortener (see Upgrading to Kentico 12 for details).
• The GetBoardMessagesCount transformation method was removed (both the ASCX transformation method and the macro method for Text / XML transformations). If you need to display the number of messages posted on a board, implement a custom transformation method or macro method and call the BoardMessageInfoProvider.GetMessagesCount method within its code (located in the CMS.MessageBoards namespace).

Database

General

• The following columns were removed from the CMS_PageTemplate database table due to removing of the obsolete MVC functionality:
  • PageTemplateDefaultController
  • PageTemplateDefaultAction

E-commerce

• Columns that reference order addresses (OrderBillingAddressID, OrderCompanyAddressID, OrderShippingAddressID) were removed from the COM_Order database table. Instead, each order address record in the COM_OrderAddress table now references the related order via the AddressOrderID and AddressType columns.

Social & Community

• The following database tables and columns were removed along with the Friends and Messaging features:
  • Community_Friend table
  • Messaging_ContactList table
  • Messaging_IgnoreList table
  • Messaging_Message table
  • UserMessagingNotificationEmail column from the CMS_UserSettings table
• The FacebookAccountPageUrl column was removed from the SM_FacebookAccount database table.

API

MVC – Platform

• The approach used to register Kentico services into dependency injection containers on MVC sites was changed. Instead of registering service types from assemblies with the Kentico. prefix, you need to implement on-the-fly registration for all services from the Kentico API (integrated via the Kentico.Libraries NuGet package). Additionally, the Kentico.Core NuGet package will not be released for Kentico 12 – if you wish to use interfaces for custom service or repository classes, create your own equivalents of the original IService and IRepository interfaces. See Initializing Kentico services with dependency injection.
• Extension methods for registering specific routes used by Kentico features on MVC sites are now obsolete (such as MapActivitiesRoutes, MapOpenedEmailHandlerRoute and MapEmailLinkHandlerRoute). Instead, the Kentico().MapRoutes() extension method now automatically maps all required routes based on the set of features enabled via the ApplicationBuilder instance. As a result, enabling of Kentico MVC features must always be done before routes are registered into the application's RouteTable.
• The initialization of the Kentico API was moved to an earlier phase (Application_Start) for MVC applications that use the Kentico.AspNet.Mvc integration package. As a result, it is no longer possible to assign handlers to the ApplicationEvents.Initialized event within the Application_Start method of the HttpApplication class in Global.asax. If you used this approach, instead assign the event handlers within the OnInit method of a custom module class.

MVC – On-line marketing

• The Kentico().MapActivitiesRoutes() extension method, which maps page activity logging routes on MVC sites, is now obsolete. Instead, call the UseActivityTracking method of the ApplicationBuilder instance to enable the activity tracking feature, and the general Kentico().MapRoutes() method then automatically registers the required routes. See Logging activities on MVC sites.
• The Kentico().MapOpenedEmailHandlerRoute() and Kentico().MapEmailLinkHandlerRoute() extension methods, which map marketing email tracking routes on MVC sites, are now obsolete. Instead, call the UseEmailTracking method of the ApplicationBuilder instance to enable the email tracking feature, and the general Kentico().MapRoutes() method then automatically registers the required routes. See Tracking marketing emails on MVC sites.

Platform

• The way web farm synchronization tasks are registered and created within the system has changed. In Kentico 12, web farm tasks are represented by strongly typed classes that inherit from the WebFarmTaskBase base class. The classes encapsulate both the task's synchronization data and its execution logic. See Creating custom web farm synchronization tasks for more information and an example.

Content management

• The Attachment class is now obsolete and should be replaced with the DocumentAttachment class in any custom code. For all page types containing File or Attachment fields, Info and InfoProvider classes should be re-generated. Alternatively, you can replace occurrences of the Attachment class in the code of these page types manually.

E-commerce

• The ProductPrices and ProductCatalogPrices classes representing calculated prices no longer provide setters for their properties. If you need to update an existing object of this type, create a new instance of the given class with the required values set in the constructor.
• The IAddress interface unifying the AddressInfo and OrderAddressInfo classes was removed. Use the AddressInfo class to work with customer addresses and the OrderAddressInfo class to work with order addresses.