Content management and repository breaking changes

This article covers content management breaking changes in CMS 13, including content repository, content areas, XhtmlString, content versioning, validation, and save actions.

EPiServer.IContentRepository

• A new Copy method was added. Change any previous Copy implementations to the new method.
• An additional method Publish was added.
• An additional method ConvertLanguageBranch was added.
• The entries in the Data dictionary for a thrown ValidationException are now an IList<ValidationError> when a property has multiple errors. Previously it was a single error.
• The MoveToWastebasket method now takes an AccessLevel parameter. The deletedBy parameter was removed in favor of reading the current user from IPrincipalAccessor similar to other methods on this interface.

EPiServer.IContentRepositoryExtension

Class was obsoleted because all its methods are now on the IContentRepository interface.

EPiServer.Core.ContentProvider

• The deletedBy parameter on MoveToWastebasket was removed. The provider should read the current user from IPrincipalAccessor similar to other methods.
• Property WastebasketReference now returns a ContentReference instead of a PageReference.
• Protected method CreateContentResolveResult(ContentCoreData contentData) changed to CreateContentResolveResult(ContentNode contentData). Custom providers overriding this method must update the parameter type from ContentCoreData to ContentNode.

EPiServer.Core.ContentReference

• Properties StartPage, RootPage, and WasteBasket changed from PageReference to ContentReference.
• The setter of the StartPage property was obsoleted.

PageReference obsolescence

PageReference is obsolete throughout CMS 13. Replace all usages with ContentReference. The following types have had PageReference parameters or return types replaced with ContentReference:

• EPiServer.Core.ConvertedPageEventArgs – Property PageLink
• EPiServer.Core.IPageCriteriaQueryService – Parameters
• EPiServer.PropertyCriteriaCollection – Parameters
• EPiServer.Core.PageDataCollection – Parameters
• EPiServer.Core.PageTypeConverter – Parameters
• EPiServer.Core.PageData – Properties ContentLink, ParentLink, and ArchiveLink now return ContentReference instead of PageReference.
• EPiServer.Personalization.VisitorGroups.Criteria.ViewedPagesModel – Return value for GetViewedPageLink
• EPiServer.Personalization.VisitorGroups.CriterionEventArgsExtensions – Return value for GetPageLink

ContentArea changes

• EPiServer.Core.ContentArea – Class no longer inherits XhtmlString. All properties and methods related to string manipulation are obsoleted (ToHtmlString, ToInternalString, etc.).

  • Property FilteredItems was obsoleted. Use Items to get all items. Or use HTML Helpers or Tag Helpers to render content areas. Alternatively, use IEnumerable<IContentAreaItemsRenderingFilter> to read all filters and apply to a list for rendering.
  • Property Tag was obsoleted since it is no longer being used.

• EPiServer.Core.ContentAreaItem – Constructor no longer accepts ContentFragment. Empty instances of this class are no longer saved. At least one property must be assigned for the instance to be considered non-empty. RenderSettings changed to IDictionary<string, string>, and the setter was replaced with an initializer.

• EPiServer.SpecializedProperties.PropertyContentArea – No longer inherits PropertyLongString and no longer supports raw strings.

• EPiServer.SpecializedProperties.PropertyContentAreaItem – No longer inherits PropertyLongString and no longer supports raw strings.

• EPiServer.Core.IContentAreaLoader – Method Get was removed in favor of LoadContent. A new overloaded LoadContent method with a ContextMode parameter was added.

• EPiServer.Core.ContentAreaItemExtensions – Extension method GetContent on EPiServer.Core.ContentAreaItem was removed in favor of LoadContent.

XhtmlString changes

• EPiServer.Core.XhtmlString – Method ToHtmlString(IPrincipal principal) was obsoleted with compilation error. Use HTML Helpers or Tag Helpers to render, or use IEnumerable<IStringFragmentRenderingFilter> to filter fragments for rendering. Method ToHtmlString() now always filters away content fragments and personalized fragments.

• EPiServer.Core.Html.StringParsing.StringFragmentCollection – Methods GetFilteredFragments() and GetFilteredFragments(IPrincipal principal) were obsoleted with compilation error. Use IEnumerable<IStringFragmentRenderingFilter> to filter fragments for rendering instead.

• EPiServer.Core.Html.StringParsing.ContentFragment – Constant IsInlineBlockAttributeName is no longer used; use InlineBlockTypeIdAttributeName to determine if the item is an inline block. Interface IRenderSettings is no longer implemented. Class no longer implements ISecurable interface. Now implements IPersonalizedGroup instead of IContentGroup. Constructor parameters IPublishedStateAssessor and IContentAccessEvaluator were removed.

• EPiServer.Core.Html.StringParsing.PersonalizedContentFragment – No longer implements ISecurable, IContentGroup, and IPersonalizedRoles. Now implements IPersonalizedGroup. Constructor parameter type changed from ISecuredFragmentMarkupGenerator to IPersonalizedFragmentMarkupGenerator.

• EPiServer.Core.Html.StringParsing.IContentGroup – Interface removed. Use IPersonalizedGroup instead.

• EPiServer.Core.Html.StringParsing.ISecuredFragmentMarkupGenerator – Interface removed. Use IPersonalizedFragmentMarkupGenerator instead. Property RoleSecurityDescriptor replaced with RoleIdentities of type IEnumerable<string>.

• EPiServer.Core.Html.StringParsing.ISecuredFragmentMarkupGeneratorFactory – Interface removed. Use IPersonalizedFragmentMarkupGeneratorFactory instead.

• EPiServer.Core.Html.StringParsing.VisitorGroupMarkupGenerator – Now implements IPersonalizedFragmentMarkupGenerator instead of ISecuredFragmentMarkupGenerator. Property RoleSecurityDescriptor replaced with RoleIdentities. Constructor overloads accepting IRoleSecurityDescriptor removed. Constructor parameter IVisitorGroupRoleRepository removed.

• EPiServer.Core.Html.TextIndexer – Removed because it is no longer used.

ScriptParser changes

• EPiServer.Core.Html.StringParsing.ScriptParserOptions –
  • Default value for property LoadingMode changed to ScriptParserMode.Remove, meaning illegal URIs, HTML elements, and HTML attributes are removed during content loading.
  • Default value for property SavingMode changed to ScriptParserMode.ThrowException, meaning saving content with illegal URIs, HTML elements, or HTML attributes causes an InvalidPropertyValueException.
  • New settings MediaUploadMode and MediaExtensionsToParse specify which extensions for media files should be parsed during upload, and which action should be taken for illegal elements/attributes. Default values are that extensions .svg, .svgz, .html, and .htm are parsed and that an exception is thrown for illegal attributes/elements.
  • The AttributeNames property was removed. Use ElementAttributes, which allows you to define attributes for elements. By default, ElementAttributes covers attributes that start with on* for elements.

Property changes

PropertyString and PropertyLongString

• EPiServer.Core.PropertyString – Property String changed accessibility to public. Property PublicString was removed.

• EPiServer.Core.PropertyLongString – Property LongString changed accessibility to public. Property PublicLongString was removed. Property PageLink was removed in favor of Parent.OwnerLink.

PropertyUrl and related types

• EPiServer.SpecializedProperties.PropertyUrl – Property LinkEditorType was removed. Property String was replaced with LongString property. Base class changed from PropertyString to PropertyLongString to support longer URLs.

• EPiServer.SpecializedProperties.PropertyDocumentUrl – Property LinkEditorType was removed.

• EPiServer.SpecializedProperties.PropertyImageUrl – Property LinkEditorType was removed.

PropertyBlock and PropertyXhtmlString

• EPiServer.SpecializedProperties.PropertyBlock<T> – No longer implements IPersonalizedRoles interface. Method GetRoles() was removed. Property ItemTypeReference changed type from BlockTypeReference to ContentTypeReference.

• EPiServer.SpecializedProperties.PropertyXhtmlString – No longer implements IPersonalizedRoles interface. Method GetRoles() was removed. Constructor accepting (string value, IPrincipalAccessor principalAccessor) was removed.

• EPiServer.SpecializedProperties.IPropertyBlock – Property BlockPropertyDefinitionTypeID was replaced with BlockPropertyDefinitionID. Property ItemTypeReference changed type from BlockTypeReference to ContentTypeReference.

LinkItem

• EPiServer.SpecializedProperties.LinkItem – Overrides object.Equals and object.GetHashCode. Property Attributes changed type from Dictionary<string, string> to IDictionary<string, string>. The Attributes dictionary is no longer case-sensitive. Type implements IReadOnly.

Other property changes

• EPiServer.Core.PropertyData – The Locate property is obsolete and is no longer available for retrieving services. The Clear method is no longer virtual. To override clear behavior, override method ClearImplementation instead.

• EPiServer.Core.PropertyDataCollection – Property LanguageBranch is obsolete and is no longer assigned.

• EPiServer.Core.PropertyCriteriaCollection – Type no longer inherits System.Collections.CollectionBase, but instead implements IList<PropertyCriteria>.

• EPiServer.Core.RawContent – Public fields were changed to public properties.

• EPiServer.Core.RawNameAndXml – Public fields were changed to public properties.

• EPiServer.Core.RawProperty – Property PageDefinitionID was removed in favor of PropertyDefinitionID. Public fields were changed to public properties. Property BlockTypeReference changed type from BlockTypeReference to ContentTypeReference.

• EPiServer.Core.RequiredPropertyValueException – No longer used. System.ComponentModel.DataAnnotations.ValidationException is thrown instead if a required property is missing.

• EPiServer.Web.PropertyControls.MultipleOptionsListSettings – Moved to EPiServer.SpecializedProperties.PropertySettings namespace in the EPiServer assembly.

Content versioning

• EPiServer.Core.IContentVersionRepository – A new event CommonDraftAssigned was added. A new overloaded Delete method with an AccessLevel parameter was added. New overloaded LoadCommonDraft and LoadPublished methods with a variationKey parameter were added.

• EPiServer.Core.IContentVersionRepository.List – No longer automatically counts and assigns the out parameter totalCount. To get totalCount counted, you must explicitly assign EPiServer.Core.VersionFilter.IncludeTotalCount to true. If IncludeTotalCount is not assigned, totalCount is assigned the value -1.

• EPiServer.Core.IContentVersionRepositoryEx – Obsoleted. Method ListObsolete moved to IContentVersionRepository.

• EPiServer.Core.IVersionable – A new property Variation was added to support variations of content versions.

• EPiServer.Core.IContentCacheKeyCreator – A new method CreateGuidCacheKey was added to support GUID-based cache keys.

• EPiServer.Core.IStatusTransitionEvaluator – A new overloaded method was added that takes an optional parameter of existing ContentVersion.

• EPiServer.Core.StatusTransition – This struct is now readonly.

Validation system overhaul

New validation skip options

• EPiServer.DataAccess.SaveAction – Three new validation skip flags were added:

  • SkipReferenceValidation – Skips reference validation during save.
  • SkipApprovalValidation – Skips approval validation during save (requires Administer rights).
  • SkipDataValidation – Skips data validation during save.
  • SkipValidation – Composite flag combining all three skip options.
  • The Patch action now uses ForceCurrentVersion | SkipValidation to update content without any validation.

• EPiServer.DataAccess.SaveAction – Value None was removed in favor of Default. Value DelayedPublish was removed in favor of Schedule.

Content save validation

• EPiServer.Validation.IContentSaveValidate<TContent> – A new interface property SkipOption of type ContentValidationSkipOption was added. Existing implementations must implement this property. Use ContentValidatorBase<TContent> which provides default implementations.

• EPiServer.Validation.ContentValidationSkipOption – New enum defining which parts of content validation can be skipped: None, Data, Approval, References.

• EPiServer.Validation.IContentValidationService – New service interface providing content-specific validation with support for granular skip options.

• EPiServer.Validation.ContentSaveValidationContext – A new constructor argument with the content being validated was added.

• EPiServer.Framework.Validation.IContextValidationService – A new overload of Validate was added that accepts a predicate parameter to filter which validators should be called.

Behavioral changes

• Validators implementing IValidate<T> (without IContentSaveValidateOptions) are now treated as supporting SkipDataValidation for backward compatibility, meaning they are skipped when SaveAction.SkipDataValidation is used.
• References for content (from ContentReference, ContentArea, Url properties) are now validated for existence during save. Use SaveAction.SkipReferenceValidation to suppress this validation.
• CMS 13 enforces validation attributes (RequiredForPublish, MinElements) on block creation from ContentArea, not just during publish. This may cause silent failures for custom validation attributes.

Content language and language settings

• EPiServer.Core.LanguageLoaderOption – Property EvaluatePublishDates changed default value to true. This change makes content routing and content loading consistent.

• EPiServer.Core.LanguageSelectionSource – Value Master was removed because it is no longer used.

• EPiServer.Core.LanguageSelector – The constructor LanguageSelector(string languageBranch, IContentLanguageSettingsHandler languageSettingsHandler) was removed in favor of LanguageSelector(string languageBranch).

• EPiServer.Core.ContentLanguageSettingsHandler – The static ContentLanguageSettingsHandler is obsolete. Retrieve the IContentLanguageSettingsHandler instance from the service container.

• EPiServer.IContentEvents – Two new events were added, ConvertingContentLanguage and ConvertedContentLanguage.

• EPiServer.Core.ContentOptions.AllowModifiedMasterLanguageProperties – When saving content in a non-master language, modifications to non-culture specific properties now throw InvalidOperationException unless explicitly allowed through configuration.

Other content changes

• EPiServer.Core.ContentMediaResolver – Method Initialize was removed. The constructor parameter of type IContentTypeBaseResolver was removed.

• EPiServer.Core.EditTab – Values Category, Link, and Scheduling were removed because they are no longer used.

• EPiServer.Core.PageData – Property IsModified is only exposed explicitly through the EPiServer.Core.IModifiedTrackable interface. Property ACL and the constructor accepting ContentAccessControlList were obsoleted. Use IContentAccessEvaluator to check access rights, or GetContentSecurityDescriptor() to get the security descriptor.

• EPiServer.PageEventArgs – Removed as it was no longer in use.

• EPiServer.EPiServerCancelException – Constructor taking a PageEventArgs argument was removed.

• EPiServer.Construction.ConstructorParameterResolver – The static Instance property is obsolete. Retrieve the singleton instance from the service container.

• EPiServer.Construction.IPropertyDefinitionTypeResolver – Method ResolveType has an additional out parameter.

• EPiServer.Core.IBlockPropertyFactory – New overloads for Create accepting integer-based content type identifiers.

• EPiServer.Core.Transfer.IContentCopyHandler – Replaced the existing Copy method with a Copy method that has a CopyContentOptions parameter. The old Copy(ContentReference, ContentReference, AccessLevel, bool) overload was removed.

• EPiServer.Core.Transfer.ITransferPageData – Interface removed. Use ITransferContentData instead.

• EPiServer.Core.Transfer.TransferPageData – Class removed. Use TransferContentData instead.

• EPiServer.Core.RawPage – Class removed. Use RawContent instead for import/export.

• EPiServer.DataAbstraction.MetaDataProperties – Constant PageFolderID was removed. Virtual Path Providers are no longer supported.

• EPiServer.Core.Transfer.IContentTransferContext – Property ContentTypesMap changed from IDictionary<string, Guid> to Dictionary<string, (Guid exportedGuid, Guid importedGuid)>.

• EPiServer.Core.Transfer.IFileTransfer – An additional parameter displayName was added to method TryAddBlob.

• EPiServer.Core.Transfer.TransferImportOptions – Property ContentLanguages was removed in favor of property SelectedLanguage.

• EPiServer.Cms.Shell.Service.Internal.ContentService – The Copy method no longer automatically publishes content.

• EPiServer.Cms.Shell.UI.Rest.Internal.ContentChangeManager – The Copy method no longer automatically publishes content.

Audiences (Visitor Groups)

Audiences (formerly Visitor Groups) are not enabled by default. Enable them by calling .AddVisitorGroupsMvc() and .AddVisitorGroupsUI() to register MVC and UI services. The EPiServer.Cms composition package no longer includes Visitor Groups as a dependency.

• EPiServer.Personalization.VisitorGroups.DojoWidgetAttribute – Removed because Dojo is no longer supported for Audiences UI. Use CriterionPropertyEditor instead.

• EPiServer.Personalization.IPersonalizedRoles – Interface removed. Functionality is now part of IPersonalizedGroup interface.

• EPiServer.Personalization.PageDataPersonalizationExtension – Class and its extension method GetUsedPersonalizedGroupIds removed.

• EPiServer.Security.IRoleSecurityDescriptor – Interface removed. Use IEnumerable<string> for role identities instead.

• EPiServer.Personalization.IPersonalizedContentFactory – Method signatures changed; ISecuredFragmentMarkupGenerator replaced with IPersonalizedFragmentMarkupGenerator.