Previous Page Next Page

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 &quot;$(TSJavaScriptFile.Replace('build\\..\tools\', 'tools\'))&quot; -p ./tsconfig.json" ContinueOnError="true" />
+ <Exec Command="node &quot;$(TSJavaScriptFile.Replace('build\\..\tools\', 'tools\'))&quot; -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.