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"
]