Update vs Upgrade (Migration)
To avoid confusion, let's start by defining
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 latest versions of binary NuGet packages and most of the time that does not require any manual code modification.
upgrade (or migration) involves breaking changes and there will be some modifications that needs 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 Migrations section on this site to understand what to do. It is also a good idea to visit this site before trying a update to see if there are any breaking changes.
Premium StartSharp customers can use
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.Pro.Scripts" Version="5.0.12" /> <PackageReference Include="Serenity.Net.Web" Version="5.0.20" /> <PackageReference Include="Serenity.Assets" Version="5.0.19" /> <PackageReference Include="Serenity.Scripts" Version="5.0.20" /> <PackageReference Include="Serenity.Demo.ThemeSamples" Version="126.96.36.199" />
Take a note of any
PackageReference include that starts with
Updating Serenity Packages
Serenity packages only updates
Serenity NuGet Packages to their
most recent versions.
Open a command prompt at your project directory and execute following commands in order:
Base Package Updates
dotnet restore dotnet add package Serenity.Net.Web dotnet add package Serenity.Assets dotnet add package Serenity.Scripts
If you use
Package Manager Consolein Visual Studio you may also try
Update-Packagecommand instead of
dotnet add package.
Pro Package Updates
If you are a StartSharp customer, download latest version of
pro-packages.zip from StartSharp repository, extract it to
pro-packages folder under your solution folder and execute following:
dotnet add package Serenity.Pro.Scripts
This is the only pro package as of writing. It contains all pro feature scripts. We'll be splitting them into separate packages and introducing new ones, so please prefer
stargento automate all updates
Updating Feature Packages
If you have common / premium feature packages like
Serenity.Demo.ThemeSamples etc in your project, you'll need to also update them (otherwise you shouldn't):
dotnet add package Serenity.Demo.ThemeSamples
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
C# code (by generating code on build).
You should always keep
sergen up-to-date with 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
dotnet tool update sergen
Copying Content to wwwroot with
dotnet sergen restore
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'll still be using old versions of Serenity and other third party scripts / css files.
We are migrating from
Razor Library Static Web Assetsfeature and this will not be necessary in the future.
Applying Upgrades (Migration)
If you tried to update and had some issues, you should check the migration 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
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.