Documentation Center

API changes for future improvements

For SDL Digital Experience Accelerator 1.1, changes to the API were made with future improvements and features in mind. As much as possible, backward compatibility was maintained, but implementers who used the extension points to build custom extensions may need to rewrite or recompile their code.

One of the themes of this release was making DXA's architecture and public APIs future-proof. This resulted in the deprecation of the old APIs, minimizing the number of code changes needed to get existing implementations up and running. SDL recommends heeding deprecation warnings reported by your compiler, however, in order to make your implementation fully compliant with this release.

In addition to the API that we expect the Web application (that is, View code) to use, and on which backwards compatibility focused, DXA's extension points for Service Provides (such as Content Providers, Resolvers and Renderers) have also changed significantly for this release. This is because we expect neither the Web application nor custom Modules to make extensive use of these extension points.

Concretely, implementers can expect the following compatibility issues:
Include Pages are now modeled as Regions

If your View code uses Model.Includes, it will now result in deprecation warnings. If your View code iterates over Regions, it will pick up Regions for the Include Pages as well. As a minimal workaround for this, add the Include Page Regions (for example your header page) to the list of Regions to exclude.

Changes due to support for multiple logical sites in one physical Web application

Because of multisite support, a number of properties and methods of the SiteConfiguration class have moved into the Localization class, which you can access through a call to WebRequestContext.Localization. The SiteConfiguration has also changed its configuration directory, which you now access by Publication ID rather than by path.

Also, the following classes have been updated to have the ability to store their settings per Publication (using a Publication ID as key):
  • SemanticMapping
  • ResourceProvider
  • TridionConfig
New type RichText
This new type is an alternative for the string type for model properties that represent rich text. The following Core Entity Model properties use this new type:
  • Teaser.Text
  • Paragraph.Content

As a result, View code that expects these properties to be of type string will fail to compile. For string manipulation on the property value (as is done in Teaser-ImageOverlay.cshtml), use the ToString method to convert it to a string. To render the property value to HTML (supporting embedded Entites), we recommend using the Html.DxaRichText method.

Unresolvable property names now throw an exception

A View in SDL Tridion Reference Implementation 1.0 used syntax such as @Markup.Property(element, "Link.LinkText"), which failed to resolve because Link.LinkText is not a valid property name. Now, the same error would result in an exception.