Upgrading from v6.0.0 to v6.1.6
Who should apply these changes?
If you created your project from a StartSharp / Serene 6.1.6+ template you don't need to apply changes in this document.
If the project created earlier from 6.0.0 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 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 the UpgradeInfo section:
"UpgradeInfo": {
"InitialType": "Premium",
"InitialVersion": "6.0.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 6.1.6
minimum.
Your package versions should look like this at the minimum:
<PackageReference Include="Serenity.Assets" Version="6.1.6" />
<PackageReference Include="Serenity.Scripts" Version="6.1.6" />
<PackageReference Include="Serenity.Net.Web" Version="6.1.6" />
<PackageReference Include="Serenity.Extensions" Version="6.1.6" />
Don't forget to update pro packages to 6.1.6
as well.
<PackageReference Include="Serenity.Pro.Extensions" Version="6.1.6.0" />
<PackageReference Include="Serenity.Pro.Theme" Version="6.1.6.0" />
<PackageReference Include="Serenity.Pro.UI" Version="6.1.6.0" />
The demo and pro modules are also updated to 6.1.6
:
<PackageReference Include="Serenity.Pro.DataAuditLog" Version="6.1.6.0" />
<PackageReference Include="Serenity.Pro.DataExplorer" Version="6.1.6.0" />
<PackageReference Include="Serenity.Pro.EmailClient" Version="6.1.6.0" />
<PackageReference Include="Serenity.Pro.EmailQueue" Version="6.1.6.0" />
<PackageReference Include="Serenity.Pro.Organization" Version="6.1.6.0" />
<PackageReference Include="Serenity.Pro.Meeting" Version="6.1.6.0" />
<PackageReference Include="Serenity.Pro.WorkLog" Version="6.1.6.0" />
<PackageReference Include="Serenity.Demo.AdvancedSamples" Version="6.1.6.0" />
<PackageReference Include="Serenity.Demo.Northwind" Version="6.1.6.0" />
<PackageReference Include="Serenity.Demo.BasicSamples" Version="6.1.6.0" />
Important Information for Serene Users
At the time of writing this document, Serene was not yet updated to ES modules as we wanted to test it with a limited user base. So we had to use sample file links from StartSharp repository, which can only be accessed by the premium members.
Serene was updated to ES modules two months later and you may find some of the files at similar locations if you browse Serene repository using this link:
https://github.com/serenity-is/serene/tree/3668a20a2a1c390d975f39e64774c4888357f958
As we directly switched to ES modules in Serene, skipping Namespaces
folder etc. and due to some changes occuring in those two months like making tsbuild an NPM package, some of the files mentioned in this document have no match in Serene repository.
We recommend following this blog post for ES modules switch in place of this document as it has more up-to-date information and better directions for Serene (and also for StartSharp):
https://serenity.is/blog/2022/10/15/switching-to-es-modules
You should still follow this document for changes that are not related to ES modules switch.
Updating CsProj File
Adding TypeScriptNoEmitOnError
If there is no <TypeScriptNoEmitOnError
tag with false
inside in your .csproj
file, add the following inside the first PropertyGroup
element without any condition:
<TypeScriptNoEmitOnError>false</TypeScriptNoEmitOnError>
If there is any TypeScriptNoEmitOnError
with true
inside, remove it.
Removing TypeScriptToolsVersion Tags
If there is any TypeScriptToolsVersion
tag in your .csproj
file, remove it.
Ignoring node_modules on TypeScriptCompile
If there is no TypeScriptCompile
tag with Remove
attribute with the value of node_modules
, add the following inside the first ItemGroup
element without any condition:
<TypeScriptCompile Remove="node_modules\**" />
Adding Content Files
Add the following inside the first ItemGroup
element without any condition:
<Content Update="libman.json;sergen.json;tsconfig.json;tslint.json">
<CopyToPublishDirectory>Never</CopyToPublishDirectory>
<CopyToOutputDirectory>Never</CopyToOutputDirectory>
</Content>
<Content Update="Modules\tsconfig.json">
<CopyToPublishDirectory>Never</CopyToPublishDirectory>
<CopyToOutputDirectory>Never</CopyToOutputDirectory>
<ExcludeFromSingleFile>true</ExcludeFromSingleFile>
</Content>
Updating Target CompileTSC
Add wwwroot\esm\**\*.js
to the Outputs
attribute of the CompileTSC
target. Don't forget to change YourProject
part of the Outputs
to your project name.
- <Target Name="CompileTSC" AfterTargets="AfterBuild" Inputs="@(CompileTSCInputs)" Outputs="wwwroot\Scripts\site\YourProject.Web.js">
+ <Target Name="CompileTSC" AfterTargets="AfterBuild" Inputs="@(CompileTSCInputs)" Outputs="wwwroot\Scripts\site\YourProject.Web.js;wwwroot\esm\**\*.js">
Replace the Exec
element inside the CompileTSC
Target
like the following:
- <Exec Command="node "$(TSJavaScriptFile.Replace('build\\..\tools\', 'tools\'))" -p ./tsconfig.json" ContinueOnError="true" />
+ <Exec Command="node "$(TSJavaScriptFile.Replace('build\\..\tools\', 'tools\'))" -p ./Namespaces/tsconfig.json" ContinueOnError="true" />
+ <Exec Command="node tsbuild" ContinueOnError="true" />
Adding SourceGeneratorTransform Condition to Targets
Add the following attribute inside any Target
element with Name
attribute of TransformServerTypings
, TransformMvcClientTypes
.
After adding this attribute, the Target
element should look like this:
<Target Name="TransformMvcClientTypes" AfterTargets="BeforeBuild">
<Exec Command="dotnet tool restore" ContinueOnError="true" />
<Exec Command="$(DotNetSergen) restore" ContinueOnError="true" />
- <Exec Command="$(DotNetSergen) mvct" ContinueOnError="true" />
+ <Exec Command="$(DotNetSergen) mvct" ContinueOnError="true" Condition="'$(SourceGeneratorTransform)' != 'false'" />
</Target>
- <Target Name="TransformServerTypings" AfterTargets="AfterBuild">
+ <Target Name="TransformServerTypings" AfterTargets="AfterBuild" Condition="'$(SourceGeneratorTransform)' != 'false'">
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
Updating appsettings.bundles.json
If you never modified appsettings.bundles.json
you can replace the whole file with this file. Otherwise apply the changes below.
CssBundling.Bundles.Base
Remove following lines from ScriptBundling.Bundles.Base
array.
"~/Serenity.Assets/Scripts/jquery.blockUI.js",
"~/Serenity.Assets/Scripts/jquery.cookie.js",
"~/Serenity.Assets/Scripts/jquery.json.js",
ScriptBundling.Bundles.Pages/Dashboard
Remove following line from ScriptBundling.Bundles.Pages/Dashboard
array.
"~/Scripts/daterangepicker/moment.min.js",
Add following line to ScriptBundling.Bundles.Pages/Dashboard
array under the "~/Scripts/knob/jquery.knob.js",
line.
"~/lib/moment.js/moment.min.js",
ScriptBundling.Bundles.Site
Remove following line from ScriptBundling.Bundles.Site
array.
"~/Scripts/split.js",
Adding Moment.js to libman
If Libman is not installed run the following command first:
dotnet tool install Microsoft.Web.LibraryManager.Cli
Open a command prompt in your project directory and type the following:
dotnet libman install moment.js@2.29.2 --provider cdnjs --destination wwwroot/lib/moment.js/ --files moment.min.js
Adding End of Line Character to sergen.json
Sergen now supports changing the end of line character of generated files. To enable this feature add the following line to the sergen.json
file after RootNamespace
line. The available options are LF
and CRLF
. We prefer to use LF
instead of CRLF
because it's more compatible with Linux and Mac.
"EndOfLine": "LF",
Creating the Namespaces folder
The Namespaces
folder is a new folder for existing TypeScript files. You need to create this folder manually and move the existing TypeScript files to this folder with same structure of Modules
folder. The new TypeScript files should be created under the Modules
folder. You will convert the existing TypeScript files to modular format after upgrade completed. But until you convert them to modular TypeScript, you can use both of them at the same time. This will allow you to upgrade your TypeScript files to modular structure while it's still can be build and deployed to the production.
After creating the folder move all the TypeScript files under Modules
folder to the Namespaces
folder.
Copying the Root tsconfig.json
Copy the tsconfig.json
file from the root of the startup project to the Namespaces
folder.
Updating Namespaces/tsconfig.json
If you never modified tsconfig.json
you can replace the whole file with this file, then replace the StartSharp.Web
on outFile
to YourProject.Web
, otherwise apply changes below to the Namespaces/tsconfig.json
file.
Set the value of the composite
property to true
, if you don't already have it add the following line after the experimentalDecorators
line inside compilerOptions
, if you don't have the experimentalDecorators
line, add it at the end of the compilerOptions
object.
"composite": true,
Set the value of the noEmitOnError
property to false
, if you don't already have it add the following line after the noEmitHelpers
line inside compilerOptions
, if you don't have the noEmitHelpers
line, add it at the end of the compilerOptions
object.
"noEmitOnError": false,
Set the value of the target
to ES6
, it should look like this:
"target": "ES6",
Set the value of the forceConsistentCasingInFileNames
property to true
, if you don't already have it add the following line after the inlineSources
line inside compilerOptions
, if you don't have the inlineSources
line, add it at the end of the compilerOptions
object.
"forceConsistentCasingInFileNames": true,
Set the value of the rootDir
property to reflect the tsconfig.json
file move, if you don't already have it add the following line after the forceConsistentCasingInFileNames
line inside compilerOptions
, if you don't have the forceConsistentCasingInFileNames
line, add it at the end of the compilerOptions
object.
- "rootDir": ".",
+ "rootDir": "../",
Set the value of the outFile
property to reflect the tsconfig.json
file move, if you don't already have it add it at the end of the compilerOptions
object.
-"outFile": "wwwroot/Scripts/site/YourProject.Web.js",
+"outFile": "../wwwroot/Scripts/site/YourProject.Web.js",
Set the value of the typeRoots
property to reflect the tsconfig.json
file move, if you don't already have it add it at the end of the compilerOptions
object.
"typeRoots": [
- "./node_modules/@types",
- "./typings/"
]
"typeRoots": [
+ "../node_modules/@types",
+ "../typings/"
]
Set the value of the include
property to reflect the tsconfig.json
file move, if you don't already have it add it at the end of the tsconfig.json
(inside the object), also change the ./Modules/**/*
to ./**/*
.
"include": [
- "./Imports/**/*",
- "./Modules/**/*"
]
"include": [
+ "../Imports/**/*",
+ "./**/*"
]
Add New Root tsconfig.json
Create the tsconfig.json
file in the root folder of your startup project and paste this file.
Create Imports/tsconfig.json
Create the tsconfig.json
file in the Imports
folder of your startup project, and paste this file.
Update packages.json
If you have never changed your packages.json
file, you can replace it with this file.
Rename name
value to your projects lowercase name even if you copied the file.
If you copied the packages.json
create a new command prompt in your project directory and type the following to remove the file reference. We don't have the referenced file to the corelib on our project, so the following command is mandatory:
npm uninstall @serenity-is/corelib
npm install @serenity-is/corelib
Skip following if you copied the packages.json
file.
Remove the following values if you are not gonna customize your package.json
: main
, author
, version
, description
, license
, repository
.
Set type
to module
, if you don't have it add it to the end (inside the object).
Set private
to true
, if you don't have it add it to the end (inside the object).
For example it should look like this:
{
"name": "yourproject.web",
"dependencies": {
...
},
"devDependencies": {
...
},
"private": true,
"type": "module"
}
Updating Dependencies
If you haven't specifically installed the following packages or you don't use them remove the following packages on the dependencies and devDependencies array writing these commands on the command prompt.
npm uninstall @types/jquery.cookie @types/jquery.blockui @types/jspdf @types/sortablejs @types/split.js
Write the following command to update the dependency versions and install new packages.
npm install @serenity-is/sleekgrid @serenity-is/corelib @types/jquery.validation@1.16.7 @types/jqueryui@1.12.6 @types/toastr@2.1.39
npm install esbuild -D
Adding ESBuild Script
Create a file named tsbuild.js
next to the package.json
and paste this file.
Add _trigger.js
to the .gitignore
. The _trigger.js
file gets created and deleted by the tsbuild.js
to trigger a TypeScript build.
If you don't have a object named scripts
in your package.json
add it, and add the prepare
value inside.
"scripts": {
"prepare": "node ./tsbuild.js --trigger"
}
Your package.json
should basically look like this:
{
"name": "YourProject.web",
"dependencies": {
"@serenity-is/corelib": "1.3.6",
"@serenity-is/sleekgrid": "1.3.6",
"@types/jquery": "2.0.48",
"@types/jqueryui": "1.12.6",
"@types/jquery.validation": "1.16.7",
"@types/toastr": "2.1.39"
},
"devDependencies": {
"esbuild": "0.15.2"
},
"scripts": {
"prepare": "node ./tsbuild.js --trigger"
},
"private": true,
"type": "module"
}
Removing Files
Delete the following files:
Namespaces/Common/Navigation/SidebarSearch.ts
Update RoleHelper.cs Namespace
Use the built-in refactoring/renaming feature of your IDE to change the namespace on the Modules\Administration\Role\RoleHelper.cs
file to YourProject.Administration
.
Add StaticFileOptions to Startup
Apply the following changes to the Configure
method in the Startup.cs
file under the line with app.UseStaticFiles()
.
app.UseStaticFiles();
+ app.UseStaticFiles(new StaticFileOptions
+ {
+ RequestPath = "/esm",
+ FileProvider = new Serenity.Extensions.NodeLikeModuleResolver(
+ new PhysicalFileProvider(Path.Combine(env.WebRootPath, "esm"))),
+ ServeUnknownFileTypes = true,
+ DefaultContentType = "text/javascript"
+ });
Add SQL Dialect to the ExceptionLog
Add the following code to the ConfigureServices
method in the Startup.cs
file.
Find the Services.Pro.Extensions.ExceptionLog.Initialize method and add an extra dialect parameter(Configuration["Data:Default:Dialect"]
) to the method call.
Serenity.Pro.Extensions.ExceptionLog.Initialize(services, HostEnvironment.ApplicationName,
- Configuration["Data:Default:ConnectionString"], Configuration["Data:Default:ProviderName"]);
+ Configuration["Data:Default:ConnectionString"], Configuration["Data:Default:ProviderName"], Configuration["Data:Default:Dialect"]);
Update LayoutHead
Add the following lines to the Views\Shared\_LayoutHead.cshtml
file.
var rtl = System.Globalization.CultureInfo.CurrentUICulture.TextInfo.IsRightToLeft ? ".rtl" : "";
+ var esm = ViewData["ESModules"] as bool? == true;
<script type="text/javascript">
@Html.Raw(DynamicScriptManager.GetScriptText("Lookup.Administration.Language"))
- @Html.Raw(DynamicScriptManager.GetScriptText("RegisteredScripts"))
</script>
+<script type="application/json" id="RegisteredScripts">@Html.Raw(Serenity.JSON.Stringify(DynamicScriptManager.GetRegisteredScripts()))</script>
Add GridPage.cshtml
Create a file named GridPage.cshtml
in Views\Shared
folder and paste this file.
Open a command prompt and run the following command to generate new view path on the C#.
dotnet sergen mvct
Add GridPageModel.cs
Create a file named GridPageModel.cs
in Modules\Common\GridPage
folder and paste this file.
Update the StartSharp
namespace to your project namespace.
Add GridPageExtensions.cs
Create a file named GridPageExtensions.cs
in Modules\Common\GridPage
folder and paste this file.
Update the StartSharp
namespace to your project namespace.
Restart your IDE
We changed our tsconfig.json
files, so we need to restart our IDE to make sure it picks up the changes.