API changes in Sitefinity CMS 5.1

This article contains all changes in backward compatibility in the Sitefinity CMS 5.1 release. The introduced changes are the following:

• Several modules were decoupled into separate assemblies.
• Properties of several modules were replaced with extension methods.
• Changes in the Ecommerce module

Read the whole article for detailed information about each of the changes.

In Sitefinity CMS 5.1, some of the modules were decoupled, i.e. moved from Telerik.Sitefinity.dll to a separate assembly. News, Blogs, Lists and Events are moved to Telerik.Sitefinity.ContentModules.dll and Ecommerce is moved to Teletik.Sitefinity.Ecommerce.dll. All types are the same and the upgrades to the database and configuration are done automatically.

If you use custom controls or projects, that are using the API of the decoupled modules, you have to recompile them after applying the following changes:

• Add a reference to the Telerik.Sitefinity.ContentModules.dll and/or Teletik.Sitefinity.Ecommerce.dll.
• If you are using the Fluent API for News, Lists, Events or Blogs, add a Telerik.Sitefinity using, because the fluent methods for those modules are moved as extensions in the new assembly.

For example, this code won’t be working anymore, if there is no Telerik.Sitefinity using clause:

 You must add a Telerik.Sitefinity CMS using:

In case of using the fluent API in .ascx/.aspx files, the Telerik.Sitefinity namespace must be imported:

The Sitefinity CMS team have done code optimizations in order to decrease the consumed memory and in the same time to increase the overall performance of the product. This lead to the introducing of several breaking changes in the Sitefinity CMS API. In general several properties (in-memory collections) of given classes were replaced with extension methods that return the same data via IQueryable collections. The main advantage of using the IQueryable collections when working with remote data source, is that you could perform an Out-of-Process data manipulation (filtering, paging, etc.), i.e. without the need of loading large sets of data into the memory.

Here is a list of the removed properties:

1. The Pages property of the PagesTemplate class.
   In case you want to get all pages based on given template, you must use the newly introduced Pages extension method of the PageTemplate class. For more information, see For developers: Query pages.
   
   Here is a code example:
   
   
   public static IQueryable<PageData> GetPagesByTemplate(Guid templateId)

   {

       PageManager pageManager = PageManager.GetManager();

    

       PageTemplate template = pageManager.GetTemplate(templateId);

    

       return template.Pages().Where(p => p.Status == ContentLifecycleStatus.Live);

   }
2. The Images property of the Album class.
   

   In case you want to get all images in given album, you must use the newly introduced Images extension method of the Album class. For more information, see For developers: Query images.

   Here is a code example:
   
   
   public static IQueryable<Image> GetImagesByAlbum(Guid albumId)

   {

       LibrariesManager librariesManager = LibrariesManager.GetManager();

    

       Album album = librariesManager.GetAlbum(albumId);

    

       return album.Images().Where(i => i.Status == ContentLifecycleStatus.Live);

   }
3. The Videos property of the VideoLibrary class.
   In case you want to get all videos in given video library, you must use the newly introduced Videos extension method of the VideoLibrary class. For more information, see For developers: Query videos.
   
   Here is a code example:
   
   
   public static IQueryable<Video> GetVideosByVideoLibraryNativeAPI(Guid videoLibraryId)

   {

       LibrariesManager librariesManager = LibrariesManager.GetManager();

    

       VideoLibrary videoLibrary = librariesManager.GetVideoLibrary(videoLibraryId);

    

       return videoLibrary.Videos().Where(v => v.Status == ContentLifecycleStatus.Live);

   }
4. The Documents property of the DocumentLibrary class.
   

   In case you want to get all documents in given document library, you must use the newly introduced Documents extension method of the DocumentLibrary class. For more information, see For developers: Query documents.
   
   Here is a code example:

   public static IQueryable<Document> GetDocumentsByDocumentLibraryNativeAPI(Guid documentLibraryId)

   {

       LibrariesManager librariesManager = LibrariesManager.GetManager();

    

       DocumentLibrary documentLibrary = librariesManager.GetDocumentLibrary(documentLibraryId);

    

       return documentLibrary.Documents().Where(d => d.Status == ContentLifecycleStatus.Live);

   }

The following changes and additions have been introduced in the Ecommerce module:

1. A dependency between Customer class and CustomerProfile class was removed and replaced by the CustomerAddress class. During the upgrade process the customer profile information for each customer is copied to the CustomerAddress table. In the old code (before the CustomerAddress model was created), the CustomerProfile stored only the most recent values of the customer’s billing and shipping addresses.
2. CustomerMoney and CustomerStatistic classes have been created to keep track of Customer related statistics, e.g. how much money has been spent by the customer, the last order number and date, etc. If using a custom checkout, you have to use the CustomerStatisticUpdater class to update the statistics of a customer. This class updates both the customer statistics and the customer money.
3. During the upgrade process the customer first name, last name, and email are set equal to their corresponding values in the user profile for the customer. More specifically, the CustomerFirstName property of the Customer instance is set equal to the FirstName property of the UserProfile instance, the CustomerLastName property of the Customer instance is set equal to the LastName property of the UserProfile instance, and the CustomerEmail property of the Customer instance is set equal to the Email property of the UserProfile instance.