Introduction
Update vs Upgrade (Migration)
To avoid confusion, let's start by defining Update
and Upgrade (Migration)
which have completely different meanings.
When we say Update
it generally means Updating Serenity NuGet Packages
to their latest versions
. This is just about fetching the latest versions of binary NuGet packages and most of the time that does not require any manual code modification.
Meanwhile, an upgrade (or migration)
involves breaking changes and there will be some modifications that need to be applied to your code manually.
Migration is sometimes confused with Database Migration so we refer to it as a upgrade.
If you update Serenity packages and see that something does not work as it should, you should visit the Migrations section on this site to understand what to do. It is also a good idea to visit this site before trying an update to see if there are any breaking changes.
Premium StartSharp customers can use the stargen
tool to automate updates and upgrades if any.
Identifying Packages to Update
To see which Serenity
packages you need to update, first have a look at your .csproj file:
<PackageReference Include="Serenity.Net.Web" Version="6.5.2" />
<PackageReference Include="Serenity.Assets" Version="6.5.2" />
<PackageReference Include="Serenity.Scripts" Version="6.5.2" />
<PackageReference Include="Serenity.Demo.AdvancedSamples" Version="6.5.2.0" />
<PackageReference Include="Serenity.Pro.Coder" Version="6.5.2.0" />
<PackageReference Include="Serenity.Pro.Extensions" Version="6.5.2.0" />
Take note of any PackageReference
include that starts with Serenity.
Updating Serenity Packages
Updating Serenity
packages only updates Serenity NuGet Packages
to their most recent versions
.
Open a command prompt in your project directory and execute the following commands in order:
Base Package Updates
dotnet restore
dotnet add package Serenity.Assets
dotnet add package Serenity.Scripts
dotnet add package Serenity.Net.Web
dotnet add package Serenity.Extensions
If you use
Package Manager Console
in Visual Studio you may also tryUpdate-Package
command instead ofdotnet add package
.
Pro (Premium) Package Updates
If you are a StartSharp customer, please make sure you have serenity.is premium package source configured, and execute the following commands only for the packages you use:
Please follow directions at https://serenity.is/Dashboard if you don't have serenity.is premium package source configured.
# these are fundamental packages thare usually referenced
dotnet add package Serenity.Pro.Coder
dotnet add package Serenity.Pro.Extensions
dotnet add package Serenity.Pro.Theme
Not all pro packages might be listed above. Please check your project file for references starting with a Serenity.Pro
prefix.
Updating Feature Packages
If you have common/premium feature packages like Serenity.Demo.Northwind
etc in your project, you'll need to also update them (otherwise you shouldn't):
dotnet add package Serenity.Demo.Northwind
dotnet add package Serenity.Demo.BasicSamples
# the ones below are premium ones
dotnet add package Serenity.Demo.AdvancedSamples
dotnet add package Serenity.Pro.DataAuditLog
dotnet add package Serenity.Pro.DataExplorer
dotnet add package Serenity.Pro.EmailClient
dotnet add package Serenity.Pro.EmailQueue
dotnet add package Serenity.Pro.Meeting
dotnet add package Serenity.Pro.OpenIddict
dotnet add package Serenity.Pro.Organization
dotnet add package Serenity.Pro.UI
dotnet add package Serenity.Pro.WorkLog
Updating Sergen (Serenity Code Generator)
Sergen
is a dotnet tool
developed for Serenity applications and is used to generate new entities/services/pages.
It is also integrated with the build process to perform some transformations and share types between TypeScript
and C#
code (by generating code on build).
You should always keep sergen
up-to-date with the Serenity version (e.g. their versions should match). Otherwise, as the code generated by an older version might not be compatible with a recent Serenity version, it may result in compile / runtime errors.
Run the following command to update the sergen
tool:
dotnet tool update sergen
Updating the NPM package references
You should generally update the following package references in your package.json to their latest available version:
{
"@serenity-is/corelib": "6.6.0",
"@serenity-is/tsbuild": "6.6.0"
}
This is important especially if you are using ES modules (any project after 6.1.x does by default).
The version numbers don't always match the latest Serenity version. Visual Studio should provide autocomplete support to identify the latest NPM package version. Or you may look at the package.json file in StartSharp
/Serene
repository. Stargen
can also automatically update them during migration.
After changing the versions in package.json
please run npm install
in the project directory, and restart Visual Studio so that the TypeScript language service will be aware of the changes.
Copying Content to wwwroot with dotnet sergen restore
Most of our premium packages uses Razor class library and static web assets feature now, and the situation explained below should not apply to them.
This part is critical
and is usually ignored or forgotten by some users leading to runtime script errors
.
Normally .NET Core NuGet packages can no longer have content like scripts, css and have them copied to project itself e.g. to wwwroot
folder in ASP.NET Core projects.
We implemented a workaround for that limitation by using sergen
. Everytime you update Serenity
packages you should run the following command:
dotnet sergen restore
Otherwise you might still be using old versions of Serenity and other third-party script/stylesheet files.
This also restores (or updates) TypeScript .d.ts
to your typings
directory from Serenity packages.
Applying Upgrades (Migration)
If you tried to update and had some issues, you should check the migration notes and release notes that are listed on the left navigation.
It is also a good idea to check them even when no errors occur during the update. There might be some critical security issues etc. that should be handled.
You should start from the version you created your project from, and apply all of the migrations in order (from bottom to top).
For example, if you created your project from a v3.14.x template, and the latest version is 5.0.20, you should apply upgrade notes in following order:
- 3.14.x to 5.0.12
- 5.0.12 to 5.0.20
If you don't see an upgrade on the Migration
or Release Notes
sections, there may not be any special upgrade steps required other than updating the packages.
Since version 6.1.8 we are no longer providing separate migration guides and all the required changes are listed under the Release Notes
section, which you may also find under the navigation. You should also check the Serenity Change Log for information about changes, and non-mandatory fixes that you might need to apply.
StartSharp customers should see the following document and use Stargen tool to automate the update / upgrade process:
Stargen automates all updates listed here in addition to upgrades. In a feature version it will also be able to convert a Serene project to StartSharp one by adding missing features.