Upgrading from v5.2.3 to v 6.0.0

Who should apply these changes?

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

If the project created earlier from 5.2.3 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": "5.2.3"
}

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

Dotnet Version

Serene or StartSharp project 6.0.0 requires .NET 6. You should firstly update your dotnet version to 6.0.0 from your projects YourProject.csproj file.

<Project Sdk="Microsoft.NET.Sdk.Web">
    <PropertyGroup>
-     <TargetFramework>net5.0</TargetFramework>
+     <TargetFramework>net6.0</TargetFramework>

Serenity Package Versions

After upgrade the dotnet version, update your Serenity package versions to 6.0.0 and 6.0.1.

Your serenity package versions should look like this, ignore the packages which doesn't exist in your project.

<PackageReference Include="Serenity.Assets" Version="6.0.0.0" />
<PackageReference Include="Serenity.Scripts" Version="6.0.1.0" />
<PackageReference Include="Serenity.Net.Web" Version="6.0.1.0" />
<PackageReference Include="Serenity.Extensions" Version="6.0.1.0" />
<PackageReference Include="Serenity.Demo.Northwind" Version="6.0.1.0" />
<PackageReference Include="Serenity.Demo.BasicSamples" Version="6.0.1.0" />
<PackageReference Include="Serenity.Demo.AdvancedSamples" Version="6.0.1.0" />

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

<PackageReference Include="Serenity.Pro.Extensions" Version="6.0.1.0" />
<PackageReference Include="Serenity.Pro.Theme" Version="6.0.1.0" />
<PackageReference Include="Serenity.Pro.UI" Version="6.0.1.0" />
<PackageReference Include="Serenity.Pro.DataAuditLog" Version="6.0.1.0" />
<PackageReference Include="Serenity.Pro.DataExplorer" Version="6.0.1.0" />
<PackageReference Include="Serenity.Pro.EmailClient" Version="6.0.1.0" />
<PackageReference Include="Serenity.Pro.EmailQueue" Version="6.0.1.0" />
<PackageReference Include="Serenity.Pro.Organization" Version="6.0.1.0" />
<PackageReference Include="Serenity.Pro.Meeting" Version="6.0.1.0" />
<PackageReference Include="Serenity.Pro.WorkLog" Version="6.0.1.0" />

Updating Other packages

Please check any other packages you have installed and update them for the .NET 6 version. The list of packages you should update are:

<PackageReference Include="FluentMigrator.Runner" Version="3.3.2" />
<PackageReference Include="Microsoft.AspNetCore.Mvc.NewtonsoftJson" Version="6.0.2" />
<PackageReference Include="Microsoft.AspNetCore.Mvc.Razor.RuntimeCompilation" Version="6.0.2" />
<PackageReference Include="Microsoft.Data.Sqlite" Version="6.0.3" />
<PackageReference Include="Microsoft.TypeScript.MSBuild" Version="4.6.2">
    <PrivateAssets>all</PrivateAssets>
    <IncludeAssets>runtime; build; native; contentfiles; analyzers</IncludeAssets>
</PackageReference>

Updating sergen.json

Check your sergen.json file and the ServerTypings section. If you don't have this section, you can add it to your sergen.json file. This configuration generates the local text TypeScript files for IntelliSense. These files contains long text values which will cause conflicts while you merging in the source control. These text files are not necessarily loaded in the browser. We can exclude these local text files. But for the backward compatibility, we added this option for users to able decide to generate them or not. You can exclude or include them by adding this configuration to your sergen.json file. When the value is true, it will generate the local texts. When the value is false, it will not generate the local texts for TypeScript. If you didn't add this configuration, it will not generate the local texts.

{
  "RootNamespace": "StartSharpTest",
  "ServerTypings": {
    "LocalTexts": true
  },
  ...
}

Updating the code files

The upgrade has one breaking change. You should fix the MD5CryptoServiceProvider usages. This class is not available in the .NET 6. You should use the MD5 class instead. These changes should be applied to the UserEndpoint.cs and AccountPage.cs files.

-   var md5 = new MD5CryptoServiceProvider();
+   var md5 = MD5.Create();

Updating sergen.json

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

"AppliedUpgrades": [
    "UP_20220824_1610_Serenity_V6_0_0"
]