Upgrading from v5.0.41 to v5.2.30

Who should apply these changes?

If you created your project from a StartSharp / Serene 5.2.30+ template you don't need to apply changes in this document.

If the project was created from 5.0.41 or an earlier version, then please first apply migrations earlier migrations listed on left.

StartSharp customers should use stargen to automate most of the changes listed here. Stargen also works on Serene template for this update.

If you are not sure which version of a template your project was created from, you may check your sergen.json file. Since version 5.0.19, StartSharp/Serene projects contain information about the initial version of the template under UpgradeInfo section:

"UpgradeInfo": {
    "InitialType": "Premium",
    "InitialVersion": "5.0.40.0"
}

If InitialVersion is not shown there, it means your initial template version is less than 5.0.19.

Serenity Package Versions

You should first update your Serenity package versions to 5.2.2 minimum.

Your package versions should look like this at minimum:

<PackageReference Include="Serenity.Assets" Version="5.2.2" />
<PackageReference Include="Serenity.Scripts" Version="5.2.3" />
<PackageReference Include="Serenity.Net.Web" Version="5.2.3" />

Don't forget to update pro packages to 5.2.3 as well.

Adding New Packages

You should install new Serenity.Pro.Theme and Serenity.Pro.UI packages to your project.

Serenity.Pro.Extensions package is also required for this update, install the package if it's not used in the project also, check the version.

With newly added and updated packages there should be a section that looks like this:

<PackageReference Include="Serenity.Pro.Theme" Version="5.2.3" />
<PackageReference Include="Serenity.Pro.UI" Version="5.2.3" />
<PackageReference Include="Serenity.Pro.Extensions" Version="5.2.3" />

If it's your first time installing Serenity.Pro.Extensions package, add Serenity.setupUIOverrides() to last line inside brackets or before the line with window.onerror in ScriptInitialization.ts file in Modules\Common folder.

Removing ThemeSamples Package

We do not use AdminLTE anymore, you should remove Serenity.Demo.ThemeSamples package from your project if you have it.

You can easily do it by removing the package reference from your project. Remove this lines from YourProject.csproj:

<!--<if:ThemeSamples>-->
<PackageReference Include="Serenity.Demo.ThemeSamples" Version="5.0.49.1" />
<!--</if:ThemeSamples>-->

You should also remove the package's controller assembly from ITypeSource. Remove this lines from ConfigureServices method of Initalization\Startup.cs:

//<if:ThemeSamples>
typeof(Serenity.Demo.ThemeSamples.AdminLTEController).Assembly,
//</if:ThemeSamples>

Removing AdminLTE

Do following replaces to empty string in *.cs files (with regex):

^[\t ]*if\s*\(UseAdminLTELoginBox\)[\s\S]*?{*?[\s\S]*?else\s*?{?\r*\n*(\t|    )
^\s*public\sstatic\sbool\sUseAdminLTELoginBox\s*({\s*get;\s*set;\s*}|=\s*.*?)\s*$

Alternatively you can remove if conditions that use UseAdminLTELoginBox and leave the else block, and remove UseAdminLTELoginBox property from files:

  • Modules\Membership\Account\AccountPage.cs
  • Modules\Membership\Account\ForgotPassword\AccountPage.ForgotPassword.cs
  • Modules\Membership\Account\ResetPassword\AccountPage.ResetPassword.cs
  • Modules\Membership\Account\SignUp\AccountPage.SignUp.cs
  • wwwroot\Content\adminlte\*
  • wwwroot\Scripts\adminlte\*

Removing AdminLTE from MVC.cs

Remove following lines from Imports\MVC\MVC.cs:

public const string AccountLogin_AdminLTE = "~/Modules/Membership/Account/AccountLogin.AdminLTE.cshtml";
public const string AccountForgotPassword_AdminLTE = "~/Modules/Membership/Account/ForgotPassword/AccountForgotPassword.AdminLTE.cshtml";
public const string AccountResetPassword_AdminLTE = "~/Modules/Membership/Account/ResetPassword/AccountResetPassword.AdminLTE.cshtml";
public const string AccountSignUp_AdminLTE = "~/Modules/Membership/Account/SignUp/AccountSignUp.AdminLTE.cshtml";

You can delete these files if you deleted AdminLTE code:

  • Modules\Membership\Account\AccountLogin.AdminLTE.cshtml
  • Modules\Membership\Account\ForgotPassword\AccountForgotPassword.AdminLTE.cshtml
  • Modules\Membership\Account\ResetPassword\AccountResetPassword.AdminLTE.cshtml
  • Modules\Membership\Account\SignUp\AccountSignUp.AdminLTE.cshtml

Removing Pace

Pace was our choice of automatic page load progress bar, but ultimately we ended up using NProgress.

To remove Pace, remove this line from Views\Shared\_LayoutHead.cshtml:

<script type="text/javascript">window.paceOptions = { startOnPageLoad: false, ajax: { trackMethods: ['GET', 'POST'], trackWebSockets: false, ignoreURLs: [] } };</script>

Adding RTL Bundle Support

Add following lines after the last @inject in Views\Shared\_LayoutHead.cshtml:

@{
    var rtl = System.Globalization.CultureInfo.CurrentUICulture.TextInfo.IsRightToLeft ? ".rtl" : "";
}

Remove following lines:

@if (System.Globalization.CultureInfo.CurrentUICulture.TextInfo.IsRightToLeft)
{
    @Html.Stylesheet("~/Content/site/site.rtl.css")
}

Find the line with @Html.StyleBundle("Base") and replace it with @Html.StyleBundle("Base" + rtl)

Editing _LayoutNoNavigation.cshtml

Add following lines before the rtl variable declaration line in Views\Shared\_LayoutNoNavigation.cshtml:

var themeCookie = Context.Request.Cookies["ProThemeSelection"];
var theme = themeCookie != null && !themeCookie.IsEmptyOrNull() ? themeCookie : "azure-light";

Replace following line:

<html lang="@System.Globalization.CultureInfo.CurrentUICulture.Name"@Html.Raw(rtl ? " dir=\"rtl\"" : "")>

with

<html lang="@System.Globalization.CultureInfo.CurrentUICulture.Name" class="pro theme-@(theme) no-navigation@(Html.Raw(rtl ? " dir=\"rtl\"" : ""))">

Editing NavigationModel.cs

Replace NavigationModel.cs in Modules\Common\Navigation folder with this file.

If you made any modifications to this file, please take a backup as it will be gone.

Creating NavigationModelFactory.cs

Create a file named NavigationModelFactory.cs in Modules\Common\Navigation folder and paste this file.

Replace StartSharp.Navigation namespace to YourProject.Navigation.

If your rows still have .Entities in their namespace, change Administration.UserPermissionRow on line 67 to Administration.Entities.UserPermissionRow.

In Startup.cs add Serenity.Navigation to usings, then find the line:

services.AddSingleton<IPermissionService, ...

Add following line after that line you just found:

services.AddSingleton<INavigationModelFactory, Common.NavigationModelFactory>();

Removing Antiforgery and Clean Parameters

Remove using Microsoft.AspNetCore.Antiforgery; from Startup.cs. Remove ILoggerFactory loggerFactory, IAntiforgery antiforgery parameters from Configure method.

Creating _Sidebar.cshtml

Create a file named _Sidebar.cshtml in Views\Shared folder and paste this file.

Remove following lines on Shared class from Imports\MVC\MVC.cs:

public const string _LayoutSlim = "~/Views/Shared/_LayoutSlim.cshtml";
public const string _LayoutSlimHead = "~/Views/Shared/_LayoutSlimHead.cshtml";
public const string LeftNavigation = "~/Views/Shared/LeftNavigation.cshtml";

Put the following line under variable declaration of _LayoutNoNavigation or at the bottom of the Shared class:

public const string _Sidebar = "~/Views/Shared/_Sidebar.cshtml";

You can delete these files:

  • Views\Shared\_LayoutSlim.cshtml
  • Views\Shared\_LayoutSlimHead.cshtml
  • Views\Shared\LeftNavigation.cshtml

Replace _Layout.cshtml

Replace Views\Shared\_Layout.cshtml with this file.

If you made any modifications to this file, please take a backup as it will be gone.

Replace DashboardIndex.cshtml

Replace Modules\Common\Dashboard\DashboardIndex.cshtml with this file.

Fix @model StartSharp.Common.DashboardPageModel namespace to @model YourProject.Common.DashboardPageModel.

If you made any modifications to this file, please take a backup as it will be gone.

You can edit line 15 to change the title.

Installing Libman CLI and Add Client Libraries

Open a command prompt in your project directory and type the following:

dotnet tool install Microsoft.Web.LibraryManager.Cli

Install Chart.js

dotnet libman install Chart.js@3.7.0 --provider cdnjs --destination wwwroot\lib\chartjs --files chart.min.js --files chart.js

Install datatables.net

dotnet libman install datatables.net@1.11.3 --provider unpkg --destination wwwroot\lib\datatables --files js/jquery.dataTables.min.js --files js/jquery.dataTables.js

Install datatables.net-bs5

dotnet libman install datatables.net-bs5@1.11.3 --provider unpkg --destination wwwroot\lib\datatables --files css/dataTables.bootstrap5.css --files css/dataTables.bootstrap5.min.css --files images/favicon.ico --files images/sort_asc.png --files images/sort_asc_disabled.png --files images/sort_both.png --files images/sort_desc.png --files images/sort_desc_disabled.png --files js/dataTables.bootstrap5.js --files js/dataTables.bootstrap5.min.js

Modifying tsconfig.json

Remove following lines if you have them from include array of tsconfig.json:

"./wwwroot/Scripts/serenity/Serenity.Pro.UI.d.ts",
"./wwwroot/Scripts/serenity/Serenity.Pro.App.d.ts",
"./wwwroot/Scripts/serenity/Serenity.Pro.EmailClient.d.ts"

Updating dotnet sergen tool

If you haven't already, update dotnet sergen tool to the latest.

Open a command prompt in your project directory and type the following:

dotnet tool update sergen

Changing DotnetSergenExe Usage

This should be only necessary if you are using Serenity as a submodule (with sources) or, you may skip this step.

Find this lines in YourProject.csproj:

<DotNetSergenExe>$(SerenitySrc)Serenity.Net.CodeGenerator\bin\sergen.exe</DotNetSergenExe>
<!-- Do not delete this line between them -->
<DotNetSergen Condition="Exists('$(DotNetSergenExe)')">$(DotNetSergenExe)</DotNetSergen>

Remove them and put the following lines under DotNetSergen tag:

<DotNetSergenDir>$(SerenitySrc)Serenity.Net.CodeGenerator\bin"</DotNetSergenDir>
<DotNetSergen Condition="Exists('$(DotNetSergenDir)sergen')">$(DotNetSergenDir)sergen</DotNetSergen>
<DotNetSergen Condition="Exists('$(DotNetSergenDir)sergen.exe')">$(DotNetSergenDir)sergen.exe</DotNetSergen>

Removing LESS Generation

Remove following lines from site.less on wwwroot\Content\Site folder:

@import "site.theme.less";
@import "site.premium.less";

Open a command prompt in your project directory and type the following:

npm install

Then run:

node .\node_modules\less\bin\lessc wwwroot\Content\Site\site.less wwwroot\Content\Site\site.css

Remove following elements on your YourProject.csproj:

<CreateItem Include="wwwroot\Content\site\**\*.less">
      <Output TaskParameter="Include" ItemName="CompileSiteLessInputs" />
</CreateItem>
<Target Name="CompileSiteLess" AfterTargets="AfterBuild" Inputs="@(CompileSiteLessInputs)" Outputs="wwwroot\Content\site\site.css">
    <Message Text="Compiling site.less..." Importance="high"></Message>
    <Exec Command="node_modules/.bin/lessc ./wwwroot/Content/site/site.less ./wwwroot/Content/site/site.css" ContinueOnError="true" />
</Target>

Modifying packages.json

Open a command prompt in your project directory and type following:

npm uninstall less datatables.net datatables.net-bs @types/toastr

Then run:

npm install @types/toastr@2.1.33 -D

Modifying appsettings.bundles.json

Replace the following line in appsettings.bundles.json:

If you never modified appsettings.bundles.json you can replace the whole file with this file.

CssBundling.Bundles.Base

Remove following lines from CssBundling.Bundles.Base array.

"~/Serenity.Assets/Content/font-open-sans.css",
"~/Serenity.Assets/Content/font-awesome.css",
"~/Serenity.Assets/Content/bootstrap.css",
"~/Serenity.Assets/Content/css/select2.css",
"~/Serenity.Assets/Content/pace.css",
// Do not remove toastr.css
"~/Serenity.Assets/Content/slick.grid.css",
"~/Content/serenity/serenity.css",
"~/Scripts/vegas/vegas.css",
"~/Serenity.Extensions/index.css"

Add following lines to the top of the CssBundling.Bundles.Base array.

"~/Serenity.Assets/fonts/poppins/poppins.css",
"~/Serenity.Assets/fonts/open-sans/open-sans.css",
"~/Serenity.Assets/bootstrap/css/bootstrap{.rtl}.css"

Add following lines to the bottom of the CssBundling.Bundles.Base array.

"~/Serenity.Assets/line-awesome/css/line-awesome-fa.css",
"~/Serenity.Assets/nprogress/nprogress.css",
"~/Serenity.Extensions/index.css",
"~/Serenity.Pro.Extensions/pro-extensions{.rtl}.css",
"~/Serenity.Pro.Theme/pro-theme{.rtl}.css"

CssBundling.Bundles.Pages/Dashboard

Remove following lines from CssBundling.Bundles.Pages/Dashboard array.

"~/Content/iCheck/flat/blue.css",
"~/Scripts/morris/morris.css",
// Do not remove values in between
"~/Scripts/bootstrap-wysihtml5/bootstrap3-wysihtml5.min.css"

Add the following line to the bottom of the CssBundling.Bundles.Pages/Dashboard array.

"~/Serenity.Pro.Theme/pages/dashboard.css"

ScriptBundling.Bundles.Base

Replace the following lines from ScriptBundling.Bundles.Base array.

Replace ~/Serenity.Assets/Scripts/pace.js with ~/Serenity.Assets/nprogress/nprogress.js.

Replace ~/Serenity.Assets/Scripts/bootstrap.js with ~/Serenity.Assets/bootstrap/js/bootstrap.bundle.js.

Replace ~/Scripts/vegas/vegas.js with ~/Serenity.Assets/preact/preact.umd.js.

Add the following line before ~/Serenity.Pro.UI/index.js value on the ScriptBundling.Bundles.Base array.

"~/Serenity.Pro.Theme/pro-theme.js",

ScriptBundling.Bundles.Site

Remove following lines from ScriptBundling.Bundles.Site array.

"~/Serenity.Assets/Scripts/jquery.slimscroll.js",
// Do not remove values in between
"~/Scripts/adminlte/app2.js",

Also, remove "~/Scripts/adminlte/app.js" if it exists.

ScriptBundling.Bundles.Pages/Dashboard

Remove following lines from ScriptBundling.Bundles.Pages/Dashboard array.

"~/Scripts/raphael/raphael-min.js",
"~/Scripts/morris/morris.min.js",
// Do not remove values in between
"~/Scripts/datepicker/bootstrap-datepicker.js",
"~/Scripts/bootstrap-wysihtml5/bootstrap3-wysihtml5.all.min.js",
"~/Scripts/adminlte/pages/dashboard.js",
"~/Scripts/adminlte/demo.js"

Add the following line to the top of the ScriptBundling.Bundles.Pages/Dashboard array.

"~/lib/chartjs/chart.js",

Add the following line to the bottom of the ScriptBundling.Bundles.Pages/Dashboard array.

"~/Scripts/datepicker/bootstrap-datepicker.js"

Updating Texts

Replace following lines in Modules\Texts.cs:

Replace FormTitle under nested class of Forms, Membership, Login to:

public static LocalText LoginToYourAccount = "Login to your account";

Change the value of SignUpButton to Don't have account yet? Sign up..

Change the value of FormTitle under the nested class of Forms, Membership, Signup to Create a new account.

Replacing AccountLogin.cshtml

Replace Modules\Membership\Account\AccountLogin.cshtml with this file.

Replace StartSharp.Membership namespace with YourProject.Membership.

If you made any modifications to this file, please take a backup as it will be gone.

Replacing LoginPanel.ts

Replace Modules\Membership\Account\LoginPanel.ts with this file.

Replace StartSharp.Membership namespace with YourProject.Membership.

If you made any modifications to this file, please take a backup as it will be gone.

Replacing AccountChangePassword.cshtml

Replace Modules\Membership\Account\ChangePassword\AccountChangePassword.cshtml with this file.

Replace StartSharp.Membership namespace with YourProject.Membership.

If you made any modifications to this file, please take a backup as it will be gone.

Editing ChangePasswordPanel.ts

Add following lines at the bottom of the ChangePasswordPanel class on the Modules\Membership\Account\ChangePassword\ChangePasswordPanel.ts file:

        getTemplate() {
            return `<div class="s-Panel">
    <h3 class="page-title mb-4 text-center">${Q.text("Forms.Membership.ChangePassword.FormTitle")}</h3>
    <form id="~_Form" action="">
        <div id="~_PropertyGrid"></div>
        <div class="px-field mt-4">
            <button id="~_SubmitButton" type="submit" class="btn btn-primary w-100">
                ${Q.text("Forms.Membership.ChangePassword.SubmitButton")}
            </button>
        </div>
    </form>
</div>`;
        }

Replacing AccountForgotPassword.cshtml

Replace Modules\Membership\Account\ForgotPassword\ForgotPassword.cshtml with this file.

Replace StartSharp.Membership namespace with YourProject.Membership.

If you made any modifications to this file, please take a backup as it will be gone.

Updating Navigation

Remove the following line from Modules\Common\Navigation\NavigationItems.cs:

using Administration = SereneTheme.Administration.Pages;

Add following lines after usings:

[assembly: NavigationGroup("YourProject", "fa-home", Default = true)]

If you use demo modules on your project add the following line with your demo modules instead of "Northwind", "Basic Samples":

[assembly: NavigationSection("YourProject/Demo Modules",
    Include = new[] { "Northwind", "Basic Samples" })]

If you use pro modules on your project add the following line with your pro modules instead of "Meeting", "Work Log":

[assembly: NavigationSection("YourProject/Pro Features",
    Include = new[] { "Meeting", "Work Log" })]

Add the following line:

[assembly: NavigationGroup(9000, "Administration", icon: "fa-tools")]

[assembly: NavigationSection("Administration/General", Default = true)]

[assembly: NavigationSection("Administration/Localization", ItemClass = "s-nav-section",
    Include = new[] { "Administration/Languages", "Administration/Translations" })]

[assembly: NavigationSection("Administration/Security", ItemClass = "s-nav-section",
    Include = new[] { "Administration/Roles", "Administration/User Management" })]

Removing Unused Files

If the project is working, you can delete *.less files under wwwroot/Content/Site folder (Do not delete site.css).

Remove these files from your project:

  • wwwroot\Content\bootstrap-less\*
  • wwwroot\Content\bootstrap-rtl.css
  • wwwroot\Content\jquery-ui.multidatespicker.css
  • wwwroot\Content\site\site.rtl.css
  • wwwroot\Content\site\slides\*
  • wwwroot\Content\serenity\*
  • wwwroot\Content\skins\*
  • wwwroot\Scripts\bootstrap-wysihtml5\*
  • wwwroot\Scripts\chartjs\*
  • wwwroot\Scripts\datatables\*
  • wwwroot\Scripts\morris\*
  • wwwroot\Scripts\raphael\*
  • wwwroot\Scripts\vegas\*

You can remove everything except from \wwwroot\Content\site\images:

  • serenity-logo-40.png
  • serenity-logo-g-40.png
  • serenity-logo-w-128.png
  • serenity-logo-w-40.png

Warning: Take a backup as everything will be gone.

Updating sergen.json

Add the following line on the Restore.Exclude array of sergen.json:

"/wwwroot/Content/serenity/*"

If you don't have an array named AppliedUpgrades, create it under UpgradeInfo property and add UP_20211229_1251_Serenity_v5_2_30 to it, it should look like:

"AppliedUpgrades": [
    "UP_20211229_1251_Serenity_v5_2_30"
]