Skip to content

Orchard Core 2.1.0

Release date: 11/21/2024

This release includes critical bug fixes that enhance stability and performance, along with new features to improve functionality.

Change Log

Behavioral Changes

JsonOptions Configuration

A key change in version 2.0 is the shift from Newtonsoft.Json to System.Text.Json. Previously, we configured the default JsonOptions to match the settings used for document serialization. In this release, however, we’ve reverted that approach, and the JsonOptions are no longer configured by default. This change provides greater flexibility, allowing you to customize JSON serialization as needed.

If your Minimal API returns YesSql documents, entities (implementations of IEntity) or content (implementations of IContent), such as ContentItem, User, Query, or Notification, you may need to use DocumentJsonSerializerOptions for proper serialization. For example, when using Minimal API, instead of returning the result with TypedResults.Ok(entity), you should use Results.Json(entity, options.Value.SerializerOptions), resolving IOptions<DocumentJsonSerializerOptions> from the IoC container.

For scenarios using ApiController to return YesSql documents or entities, we’ve introduced new output formatters, DocumentSystemTextJsonOutputFormatter and ContentSystemTextJsonOutputFormatter, to automatically handle document serialization to JSON correctly.

These changes are non-breaking and you shouldn't need to change working 2.0.x code.

Users Feature

External Authentication Logic Has Been Separated From the Users Feature

We've introduced a new feature called External Authentication. This feature has been separated from the existing Users feature to improve dependency management and to provide an option to disable external authentication by default. As a result, the User Registration feature no longer needs to be enabled unless you specifically want to allow site registration.

This feature is only available on-demand and cannot be manually enabled or disabled. It is automatically enabled when a feature requiring external authentication is activated.

Warning

If you're using a custom Login.cshtml view or Login template, make sure to update the external login form action. The ExternalLogin action has been moved from the Account controller to the ExternalAuthentications controller as of this update. While old routes will continue to work, they'll be removed in a future release.

We included a fast-forward migration to enable this feature automatically if previously needed. No action is needed from site administrators.

The following settings have been relocated to new classes as part of this update:

  • The properties UseScriptToSyncRoles and SyncRolesScript have been moved from LoginSettings to the new ExternalLoginSettings class.
  • The property UseExternalProviderIfOnlyOneDefined has also been moved from LoginSettings to ExternalLoginSettings.

In addition, several properties have been moved from RegistrationSettings to a new ExternalRegistrationSettings class:

  • NoPasswordForExternalUsers is now ExternalRegistrationSettings.NoPassword.
  • NoUsernameForExternalUsers is now ExternalRegistrationSettings.NoUsername.
  • NoEmailForExternalUsers is now ExternalRegistrationSettings.NoEmail.
  • UseScriptToGenerateUsername is now ExternalRegistrationSettings.UseScriptToGenerateUsername.
  • GenerateUsernameScript is now ExternalRegistrationSettings.GenerateUsernameScript.

Moreover, a new property, DisableNewRegistrations, has been added to ExternalRegistrationSettings, allowing you to prevent new external users from registering on the site. This property will be set by default if you are currently using the NoRegistration value for the obsolete UsersCanRegister property.

Also, note the following updates in ExternalLoginSettings:

  • UseScriptToSyncRoles has been renamed to ExternalLoginSettings.UseScriptToSyncProperties.
  • SyncRolesScript has been renamed to ExternalLoginSettings.SyncPropertiesScript.

Warning

When updating recipes to configure LoginSettings or RegistrationSettings, ensure that the settings reflect the new class structure.

Users With Permission Can Disable Two-Factor Authentication

Users granted the new DisableTwoFactorAuthenticationForUsers permission can now disable two-factor authentication for other users directly from the Users Admin UI.

User Registration Feature

User Registration Feature No Longer Required for External Authentication

The User Registration feature is no longer required if you only want to enable external authentication.

The following properties of RegistrationSettings are now deprecated and will be removed in the next major release:

  • UsersCanRegister
  • NoPasswordForExternalUsers
  • NoUsernameForExternalUsers
  • NoEmailForExternalUsers
  • UseScriptToGenerateUsername
  • GenerateUsernameScript

Previously, the UsersCanRegister property controlled which types of registration were allowed. With this update, this property is obsolete and will be removed in a future release. To enable site registration now, simply activate the User Registration feature.

Roles Feature

Roles Assignment Permissions Consolidated

In the Roles feature, there were previously AssignRoles and AssignRole_{RoleName} permissions, alongside the Users feature's AssignRoleToUsers and AssignRoleToUsers_{RoleName} permissions. As these permissions were redundant and the AssignRoles permissions were never actually authorized against, AssignRoles and AssignRole_{RoleName} have been removed in favor of the latter.

Warning

Please review all your recipes and replace occurrences of AssignRoles with AssignRoleToUsers, and AssignRole_{RoleName} with AssignRoleToUsers_{RoleName}.

Site Owner Permission Deprecated, Administrator Role Retained as a System Role

The SiteOwner permission has been deprecated and is scheduled for removal in future releases. To streamline performance, the Administrator role has been retained as a system role, much like the Authenticated and Anonymous roles. This update enhances efficiency by assigning permissions at the role level, eliminating reliance on a single super-permission. Users previously granted the SiteOwner permission will automatically receive the Administrator role through a fast-track migration process.

Additionally, the Manage Recipes permission has been introduced, replacing the deprecated SiteOwner permission for the Recipes feature.

Customizing the Administrator Role Name

If you wish to globally change the default role name of Administrator, this can be easily configured using any settings provider. For instance, to rename it to Admin in appsettings.json, add the following configuration:

"OrchardCore_Roles": {
  "AdminRoleName": "Admin"
}
New System Admin Role Creation

If the Administrator role did not previously include the SiteOwner permission, a new system admin role will be generated. This role may be named SiteAdmin or SiteAdmin{N}, where {N} ensures uniqueness. Users previously assigned the SiteOwner permission will automatically be assigned this new role.

Important Change in Admin Permission Handling

The Administrator role no longer registers permission-based claims by default during login. This means that directly checking for specific claims in Liquid, such as:

{% assign isAuthorized = User | has_claim: "Permission", "AccessAdminPanel" %}

will return false for administrators, even though they still have full access. Non-admin users, however, may return true if they have the claim.

For backward compatibility, the current behavior still allows this code to return true for administrators, but this will change in a future major release. To avoid potential issues, it’s recommended to use the has_permission filter for permission checks going forward:

{% assign isAuthorized = User | has_permission: "AccessAdminPanel" %}

New Methods Added to IRoleService

Two new methods have been introduced to the IRoleService interface: ValueTask<bool> IsAdminRoleAsync(string role) and ValueTask<bool> IsSystemRoleAsync(string role). To prevent breaking changes in the current release, these methods have been provided with default implementations.

However, if you have a custom implementation of this interface, it is crucial to implement these new methods. In the next major release, the default implementations will be removed, and failing to implement them will result in a breaking change.

Recipes Feature

New 'Manage Recipes' Permission Added

Previously, only users with the SiteOwner permission could run recipes. Now, a new ManageRecipes permission allows you to grant recipe management capabilities to any role, providing greater flexibility in permission assignment.

Themes Feature

Users with 'Apply Theme' Permission Can List Themes

Previously, only users with the SiteOwner permission could list themes. Now, users with the existing ApplyTheme permission can also list and apply themes, enhancing theme management capabilities.

Azure Communication Services Email Feature

Azure Communication Services Email Feature Name Update

The feature formerly known as Azure Email Provider has been renamed to Azure Communication Services Email to clarify that it uses ACS, and to use the same naming pattern as the ACS SMS feature (see above).

Additionally, the configuration provider key for the default provider has changed from OrchardCore_Email_Azure to OrchardCore_Email_AzureCommunicationServices. While the old key (OrchardCore_Email_Azure) will continue to bind for backward compatibility, it is scheduled for removal in the next major release. To ensure future compatibility, it is highly recommended to update your configuration to use the new key.

Autoroute Feature

Content Item Shape Alternates Based on Alias and Slug (Content and Widget shapes)

Content item shapes (Content and Widget local zones) can be overridden by their alias if AliasPart is attached or by their slug if AutoroutePart is attached. For examples, refer to the docs.

Recipes Feature

New NamedRecipeStepHandler Base Class

The NamedRecipeStepHandler class has been introduced to streamline the implementation of IRecipeStepHandler. This base class simplifies the creation of custom recipe steps by handling common step-name check, allowing developers to focus on implementing their specific step logic.

Deployment Feature

Deployment Source Optimization

A new abstract class, DeploymentSourceBase<TStep>, has been introduced to streamline and simplify deployment source implementations. Instead of directly implementing the IDeploymentSource interface, it is now recommended to inherit from DeploymentSourceBase<TStep>. This change reduces complexity and improves the maintainability of deployment sources.

Content Types

New Event Handlers

We've introduced the IContentDefinitionHandler interface, which allows you to intercept and modify content definitions as they are being built, prior to being cached. This provides finer control over the creation of content types, enabling customization at various stages of the content definition process.

The following events are available for handling different aspects of content definition:

  • ContentTypeBuilding(ContentTypeBuildingContext context): Triggered during the creation of a content type.
  • ContentPartBuilding(ContentPartBuildingContext context): Triggered during the creation of content part definitions.
  • ContentTypePartBuilding(ContentTypePartBuildingContext context): Triggered while constructing a content type part.
  • ContentPartFieldBuilding(ContentPartFieldBuildingContext context): Triggered when building fields within a content part.

These event handlers grant you the flexibility to adjust definitions at each step, providing greater customization capabilities.

System Defined Types, Parts and Fields

The new events mentioned above enable scenarios where you can inject content parts into content definitions programmatically. These parts are designated as system-type, meaning they cannot be removed or modified by users through the UI or recipes. For an example of how to inject a system-type part into a content definition, refer to the DashboardPartContentTypeDefinitionHandler class. This ensures that specific content parts are always present in the content definition, maintaining a consistent structure across the application.

Admin Dashboard

Creating Admin Widgets No Longer Requires DashboardPart

Thanks to the newly introduced System-Type capability, it is no longer necessary to attach DashboardPart to an admin dashboard. To create a new admin dashboard content type, simply assign the DashboardWidget stereotype to the content type. This streamlined process reduces complexity while ensuring that admin widgets are properly categorized without additional manual configuration.

Note

The DashboardPart will no longer be available as an attachable part by default.

Elasticsearch

Add Custom Token-Filters Support

You can now define custom token filters in your Elasticsearch configuration. To add new custom token filters, update your Elasticsearch settings accordingly.

For instance, to create a token filter named english_stop, you can include the following configuration in your appsettings.json file:

"OrchardCore_Elasticsearch": {
  "TokenFilters": {
    "english_stop": {
      "type": "stop",
      "stopwords": "_english_"
    }
  },
  "Analyzers": {
    "my_new_analyzer": {
      "type": "custom",
      "tokenizer": "standard",
      "filter": [
        "english_stop"
      ]
    }
  }
}

In this example, the english_stop token filter removes English stop words, and the my_new_analyzer uses the standard tokenizer along with the english_stop filter to process text.

Added Features

Azure Communication Services SMS Feature

A new feature was added to allow you to send SMS messages using Azure Communication Services (ACS). Simply enable it then navigate to the admin dashboard > Configurations >> Settings >> SMS to configure the provider. For more information you can refer to the docs.

Background Service Options

The PollingTime and MinimumIdleTime properties have been added to BackgroundServiceOptions, so now we have the ability to configure them from appsettings.json or other configuration providers.

External Authentication Feature

The new External Authentication feature contains common functionality used by multiple external (i.e. non-local) authentication providers (like Microsoft or Google login). See above for details.

URL Rewriting

The URL Rewriting module enables you to configure URL rewrites and redirects for incoming HTTP requests, significantly enhancing your site's SEO and user experience. This allows you to control how URLs are handled and presented to users and search engines. For more info visit this document

Miscellaneous

New Extension Methods

A new extension method, AddDisplayDriver<TModel, TDriver>, has been introduced to streamline the registration of generic display drivers. Now, instead of the verbose syntax services.AddScoped<IDisplayDriver<Navbar>, VisitSiteNavbarDisplayDriver>() for registering a driver like VisitSiteNavbarDisplayDriver, you can simply use the more concise services.AddDisplayDriver<Navbar, VisitSiteNavbarDisplayDriver>(). This enhancement reduces boilerplate code and improves readability when adding display drivers.