Breaking changes in CMS 9

To view the complete list of changes, see the release notes feed.

Some changes are binary breaking but do not necessarily require code changes but rather just a recompilation of the project. Breaking changes are changes in method signatures or behavior of methods compared to the documented API in the previous version, which are described in this document.

Who/what is affected:

Sites using log4net for logging may have to re-install the EPiServer.Logging.Log4net package.

Description:

EPiServer.CMS.Core no longer has a dependency on EPiServer.Logging.Log4Net. This breaking change lets you run on the latest version of Log4Net or use another provider. See Logging.

Because of this change, the NuGet package, EPiServer.Logging.Log4Net, may be removed by NuGet when you upgrade to CMS 9. You need to manually ensure that the package is installed by inspecting packages.config. You also may get the following error, which indicates EPiServer.Logging.Log4Net was uninstalled:

System.TypeLoadException: Method 'Log' in type 'Log4NetLogger' from assembly 'EPiServer.Logging.Log4Net, Version=1.0.0.0, Culture=neutral, PublicKeyToken=8fe83dea738b45b7' does not have an implementation.

Install the EPiServer.Logging.Log4Net package to get a supported version (version 1.1 or higher).

Who/what is affected:

Custom logging frameworks implementing the EPiServer.Logging.ILogger interface to provide custom logging functionality.

Description:

An additional parameter representing the logger framework boundary type was added to the Log method of the ILogger interface. This is required by the Log4Net implementation to resolve the logging location when using logging extension methods correctly and can be useful for other logging frameworks for the same reasons. If you have implemented your custom Logger implementation, you can add the new argument to your implementation and ignore the passed value.

Who/what is affected:

Sites using Windows Workflow Foundation for content approval.

Description:

As previously announced, Episerver removed its implementation of WF (Windows Workflow Foundation), where Microsoft now obsoletes WF 3 that Episerver was using and (officially) not supported on Azure.

You must manually delete EPiServer.Implementation.dll, EPiServer.BaseLibrary.dll and EPiServer.WorkflowFoundation.dll from the bin folder because they are blocking the initialization process. NuGet will not automatically remove these.

Episerver is investing in a new projects feature that supports rich collaboration on pages and also blocks, media, and catalog content. Even though the new project feature is still in Beta, the released features are well-tested. The user guide describes the project feature from an end-user perspective up until update 79; newer features are described in the release feed.

Who/what is affected:

Sites using legacy/obsolete API's.

Description:

Removes remains of the VPP system that was made obsolete in CMS 7.5, and mostly incorporates the EPiServer.Web.Hosting namespace in EPiServer.dll, but because this system was very much integrated into all parts of the system, there also are small breaking changes in other classes. For example, Permanent Links had both content and file links. They are now unified to permanent content links.

SearchService and SearchPageController classes in Alloy MVC 7.5 still had code referencing the Unified File System, even though all media was migrated, you can remove this code. To get help with fixing these classes, create a new site from the Visual Studio extension and compare the classes.

Who/what is affected:

Sites using any of the ASP.NET 2.0 Web Services (ASMX).

Description:

Removes Content Channel and the other ASP.NET 2 Web Services that were last shipped in 7.5 and officially obsolete in 8.

Who/what is affected:

Sites using ObjectStore or other undocumented API's.

Description:

Removes assemblies EPiServer.BaseLibrary.dll and EPiServer.Implementation.dll. The changes are source code-compatible (unless you are using an undocumented or obsoleted API). These assemblies were the framework of CMS 5 and contained internal features such as the ObjectStore. There are a few classes still used in there that are being moved to EPiServer.dll.

Who/what is affected:

Sites using the obsolete API.

Description:

A feature that pre-dated blocks. Obsolete in 7.5.

Who/what is affected:

Sites using the obsolete API (PageProviderBase/PageProviderCapabilities).

Description:

The API was made obsolete since EPiServer 7.0 and is now removed. It was replaced by Content Providers.

Also affect sites based on the CMS 7.5 Alloy templates that used the PageProviderCapabilities enum, replace usage with ContentProviderCapabilities.

Who/what is affected:

Sites using dynamic properties.

Description:

As officially announced in 7.5, this feature does not support the new user interface introduced in CMS 7. When you upgrade, this feature is disabled, both in the user interface and any API access to properties. To re-enable dynamic properties, add configuration operationCompatibility="DynamicProperties" on the applicationSettings element.

Who/what is affected:

Sites that have code that creates new instances of DataFactory (new DataFactory()).

Description:

There was a default constructor on DataFactory but you should not create new instances of DataFactory because it bypasses the IoC container. This causes problems with events and caching, but the constructors were left for compatibility with older unit tests. The constructors are now made obsolete; use DataFactory.Instance or IContentRepository instead when working with DataFactory.

Who/what is affected:

If you have code that uses the EPiServer.BaseLibrary.Channels namespace .

Description:

The interfaces IChannel/IItem etc. that were part of EPiServer.BaseLibrary and were only used by XForms are moved into XForms under the EPiServer.XForms.Channels namespace. The API is intact so it should be enough to change namespace and recompile.

Who/what is affected:

If you are relying on the implementation of IPropertyLoadDataHandler in PropertyLongString.

Description:

The delayed value loading support in PropertyLongString was revised and it no longer implements IPropertyLoadDataHandler. The IPropertyLoadDataHandler interface is still supported but deprecated and will be removed in a future release.

A few related quirks in PropertyLongString were addressed, correcting issues with Clear and IsNull not behaving as expected when the value loading was delayed. The ParseToSelf method also was corrected to raise IsNull and IsModified correctly when passed a null string.

If you are using EPiServer.Shell.Web.Hosting.ZipFileVirtualPathProvider.

EPiServer.CMS.UI.Core no longer has a dependency to DotNetZip and EPiServer.Shell.Web.Hosting.ZipFileVirtualPathProvider was removed.

If you were using the EPiServer.Shell.Web.Hosting.ZipFileVirtualPathProvider in your code, you should change it to use EPiServer.Web.Hosting.ZipArchiveVirtualPathProvider or have a look in the Zip Compressed Content section in Developing Add-ons.

The EPiServer.Shell.UI.zip archive was renamed to Shell.zip. The EPiserver.CMS.Shell.UI.zip archive was renamed to CMS.zip.

Who/what is affected:

Anyone using StructureMap or registering items in Episerver's StructureMap Container.

Description:

The StructureMap dependency was updated to the latest major version. The changes in the Episerver Library are minimal, but there are some major changes to the StructureMap API that may affect any usage. See the StructureMap release notes for further details. Episerver Framework 9.0.0 requires the signed version of StructureMap (packages structuremap-signed and structuremap.web-signed). Depending on version of NuGet you installed, the old version of StructureMap (2.6.4.1) may have to be manually uninstalled.

For example, components that are compiled against StructureMap 2 and uses the ASP.NET extensions HttpContextScoped must be re-compiled. The following example exception is seen when the components are not re-compiled against CMS 9:

System.MissingMethodException: Method not found: 'StructureMap.Configuration.DSL.Expressions.CreatePluginFamilyExpression`1<!!0> StructureMap.Configuration.DSL.Registry.For()'.

To support multiple versions of CMS, use the ServiceConfiguration attribute instead of manually calling into StructureMap.

Who/what is affected:

Any code that references the EPiServer.Shell.ShellContext class.

Description:

The EPiServer.Shell.ShellContext class was removed because the last useful property was removed after being made obsolete in previous versions.

Who/what is affected:

Anyone using mirroring.

Description:

Mirroring shipped with CMS 7.5 is no longer compatible with CMS 9. An updated DLL is available in the EPiServer.CMS.Core NuGet package (example packages/EPiServer.CMS.Core.9.0.0/tools/MirroringService/). You need to manually update the DLL in any mirroring installation after upgrading to CMS 9.

Who/what is affected:

Anyone using URL Rewrite providers.

Description:

The episerver/urlRewrite configuration will be removed, if configured. Classes related to URL rewriting are made obsolete and point to the routing extensibility options.

The URL Rewrite provider system was replaced with ASP.NET Routing already in CMS 7 but was officially obsoleted in CMS 8 when classic links were removed and it was no longer possible to render a template with direct links.

Who/what is affected:

Sites configuring custom property controls by using the \<episerver.baseLibrary> section in the web.config file.

Description:

The episerver.baseLibrary section in the web.config file is removed on upgrade. Custom property controls now can be registered only in code by using PropertyControlClassFactory.Instance.RegisterClass.