To improve the performance of categories in EPiServer CMS, the Category API was updated to use the read-only instance pattern commonly used in other areas of the API. This means that requested categories are returned as read-only instances by default, and modification can be done only after a writable clone has been requested. As a part of the change, a new CategoryRepository class is introduced to improve the testability of the API. This repository replaces the now-obsolete methods directly on the Category class, such as GetRoot() and Save.
Example of modifying a Category:
var categoryRepository = ServiceLocator.Current.GetInstance<CategoryRepository>(); var myCategory = categoryRepository.Get("MyCategory"); // Returns a read-only instance myCategory = myCategory.CreateWritableClone(); myCategory.Description = "My category is really nice"; categoryRepository.Save(myCategory);
Another smaller change is that the parent Category instance is no longer modified beyond the current when adding or deleting a category. This means you must reload the parent category to get an updated version with/without the added/deleted category. For example:
var parent = categoryRepository.Get("Parent"); var childCategory = new Category(parent, "Child"); categoryRepository.Save(childCategory); // parent.Categories will not contain a "Child" category here. parent = categoryRepository.Get("ParentCategory"); // parent.Categories will now contain the "Child" category
The Save method now respects changes to the Parent property. So, it's possible to move a category from one parent to another without having to recreate it. This also means that content items associated with the moved category maintain their association after the move.
To make the category tree easier to use, we changed the CategoryCollection class to no longer inherit from CollectionBase. Now, it implements IList<Category> instead of just IList.
While we tried to keep the API as backward-compatible as possible, some behavioral changes were introduced with version 8. The following changes made to the API are considered breaking:
Note that many parts of the old API have been marked obsolete. These items have compile-time information describing the change and where to find the equivalent method in the updated API.
Last updated: Oct 20, 2016