Skip to content

Latest commit

 

History

History
342 lines (270 loc) · 17.1 KB

v5-0-12-to-v5-0-20.md

File metadata and controls

342 lines (270 loc) · 17.1 KB
Raw

Upgrading from v5.0.12 to v5.0.20

Who should apply these changes?

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

If your project was created with a v3 or earlier version of the template, please first apply changes in v3 to v5 migration document.

If the project was created using a 5.x preview version of StartSharp like 5.0.10 etc. you should apply changes here.

StartSharp customers should use stargen to automate most of the changes listed here.

If you are not sure which version of a template your project was 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 UpgradeInfo section:

"UpgradeInfo": {
    "InitialType": "Premium",
    "InitialVersion": "5.0.20.0"
  }
>

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

Serenity.Assets Changes

Serenity.Assets which was formerly named Serenity.Web.Assets for v3 projects, contains third party assets like scripts, css and images. This library only contains static resources and no .NET code.

As this library changes less often than other Serenity packages, it has a different release cycle and might not exactly match Serenity version. For example, in this document we are talking about upgrading to Serenity 5.0.20 but will be using 5.0.19 version of assets package.

In .NET (Core) SDK style projects (which StartSharp / Serene .NET is) NuGet packages normally can't contain static content, unlike .NET framework packages, which could copy static files into project folders on install. We worked around this limitation with a workaround, namely dotnet sergen restore. This command scans NuGet packages referenced by your project and copies the static content they have into your wwwroot directory.

Serenity.Web.Assets contains common scripts like jQuery, bootstrap, ckeditor etc. But these files had to be copied to your wwwroot directory by sergen to be used. As the initial template creation does this automatically, you may not be aware of this operation. Because of this, sometimes after updating such packages, if you forget to run dotnet sergen restore, you'll still have the old version of such scripts, even if we update them. This is especially critical with Serenity.Scripts package which also contains static assets like Serenity.CoreLib.js. So, if you forget to run dotnet sergen restore after updating Serenity.Scripts, you didn't actually update anything, and will still be using old Serenity.CoreLib.js.

Another issue with static files getting copied to your wwwroot directory is they pollute there even if you don't use or modify them. For example, ckeditor folder contains hundreds of files and they are copied to your wwwroot folder even if you don't use any HtmlContentEditor in your application. Ideally, you shouldn't even commit them to source control as they are not files you modify.

Starting with v5.0.19, we'll be using Static Web Assets feature of razor class libraries. This allows NuGet packages created using Razor SDK to pack static content but allow them to be used without having to get copied to wwwroot folder. For information on static web assets see Create an RCL with static assets section in following ASP.NET Core document:

For example, in StartSharp / Serene projects, we used to have a ~/Scripts/bootstrap.js and ~/Content/bootstrap.css file. After installing newest version Serenity.Assets package, these files no longer have to reside under wwwroot but can be referenced as ~/Serenity.Assets/Scripts/bootstrap.js and ~/Serenity.Assets/Content/bootstrap.css. But you will not see any Serenity.Assets folder under your wwwroot in Visual Studio or file explorer. They will be directly served from the corresponding nuget package. When you publish the project they will be copied to their final locations. So on published output, there will be a Serenity.Assets folder under wwwroot, and files will be served from there instead of the NuGet package.

Update Serenity.Assets

Start by updating Serenity.Assets to the latest version:

<PackageReference Include="Serenity.Assets" Version="5.0.19" />

Update Script References in Bundles

Edit appsettings.bundles.json file and modify it like shown below. Please note that you should only add ~/Serenity.Assets/ prefix to ones listed below, and leave others as is.

{
  "CssBundling": {
    "Bundles": {
      "Base": [
        "~/Serenity.Assets/Content/font-open-sans.css",
        "~/Serenity.Assets/Content/font-awesome.css",
        "~/Serenity.Assets/Content/bootstrap.css",
        "~/Serenity.Assets/Content/css/select2.css",
        "~/Serenity.Assets/Content/pace.css",
        "~/Serenity.Assets/Content/toastr.css",
        "~/Serenity.Assets/Content/slick.grid.css",
        //... leave others as is
      ],
      "Site": [
        "~/Serenity.Assets/Content/jquery.fileupload.css",
        "~/Serenity.Assets/Content/colorbox/jquery.colorbox.css",
        //... leave others as is
      ]
    }
  },
  "ScriptBundling": {
    "Bundles": {
      "Base": [
        "~/Serenity.Assets/Scripts/pace.js",
        "~/Serenity.Assets/Scripts/jquery-{version}.js",
        "~/Serenity.Assets/Scripts/jquery-ui.js",
        "~/Serenity.Assets/Scripts/jquery-ui-i18n.js",
        "~/Serenity.Assets/Scripts/jquery.validate.js",
        "~/Serenity.Assets/Scripts/jquery.blockUI.js",
        "~/Serenity.Assets/Scripts/jquery.cookie.js",
        "~/Serenity.Assets/Scripts/jquery.json.js",
        "~/Serenity.Assets/Scripts/bootstrap.js",
        "~/Serenity.Assets/Scripts/select2.js",
        "~/Serenity.Assets/Scripts/toastr.js",
        "~/Serenity.Assets/Scripts/react.{REACT}.js",
        "~/Serenity.Assets/Scripts/react-dom.{REACT}.js"
        //... leave others as is
      ],
      "Site": [
        "~/Serenity.Assets/Scripts/jquery.autoNumeric.js",
        "~/Serenity.Assets/Scripts/jquery.colorbox.js",
        "~/Serenity.Assets/Scripts/jquery.dialogextendQ.js",
        "~/Serenity.Assets/Scripts/jquery.event.drag.js",
        "~/Serenity.Assets/Scripts/jquery.maskedinput.js",
        "~/Serenity.Assets/Scripts/jquery.scrollintoview.js",
        "~/Serenity.Assets/Scripts/sortable.js",
        "~/Serenity.Assets/Scripts/SlickGrid/slick.core.js",
        "~/Serenity.Assets/Scripts/SlickGrid/slick.grid.js",
        "~/Serenity.Assets/Scripts/SlickGrid/slick.groupitemmetadataprovider.js",
        "~/Serenity.Assets/Scripts/SlickGrid/Plugins/slick.autotooltips.js",
        "~/Serenity.Assets/Scripts/SlickGrid/Plugins/slick.headerbuttons.js",
        "~/Serenity.Assets/Scripts/SlickGrid/Plugins/slick.rowselectionmodel.js",
        "~/Serenity.Assets/Scripts/SlickGrid/Plugins/slick.rowmovemanager.js",
        "~/Serenity.Assets/Scripts/jquery.fileupload.js",
        "~/Serenity.Assets/Scripts/jquery.iframe-transport.js",
        "~/Serenity.Assets/Scripts/jquery.slimscroll.js"
        //... leave others as is
      ],
      "CKEditor": [
        "~/Serenity.Assets/Scripts/ckeditor/ckeditor.js",
        "~/Serenity.Assets/Scripts/ckeditor/lang/en.js",
        "~/Serenity.Assets/Scripts/ckeditor/styles.js"
        //... leave others as is
      ],
    }
  }
}

We only list above the ones that you should modify, other scripts references in that file which are not served by Serenity.Assets should be left unchanged. The ones shown here should only be prefixed by ~/Serenity.Assets/. For example, if you have ~/Content/font-open-sans.css in your bundles.json, it should be changed to ~/Serenity.Assets/Content/font-open-sans.css.

See this folder to understand which files are served by Serenity.Assets:

https://github.com/serenity-is/Serenity/tree/master/src/Serenity.Assets/wwwroot

Also, here is a rough list of files currently there with asterisk pattern:

Content/aristo/*
Content/colorbox/*
Content/css/*
Content/images/*
Content/bootstrap*.*
Content/font-awesome*.*
Content/font-opensans*.*
Content/glyphicons*.*
Content/iconicons*.*
Content/jquery.fileupload.css
Content/pace*
Content/simple-line-icons.css
Content/slick*
Content/toastr*
fonts/FontAwesome.otf
fonts/OpenSans*
fonts/Simple-Line*
fonts/font-awesome*
fonts/glyphicons*
fonts/iconicons*
Scripts/Select2-locales/*
Scripts/SlickGrid/*
Scripts/ckeditor/*
Scripts/saltarelle/*
Scripts/bootstrap*
Scripts/jquery-3.5.1*
Scripts/jquery-ui*
Scripts/jquery.autonumeric*
Scripts/jquery.blockUI*
Scripts/jquery.colorbox*
Scripts/jquery.cookie*
Scripts/jquery.cropzoom*
Scripts/jquery.dialogExtend*
Scripts/jquery.event.drag*
Scripts/jquery.fileupload*
Scripts/jquery.iframe*
Scripts/jquery.json*
Scripts/jquery.maskedinput*
Scripts/jquery.scrollintoview*
Scripts/jquery.slimscroll*
Scripts/jquery.validate*
Scripts/jquery.jspdf*
Scripts/jquery.jsrender*
Scripts/pace*
Scripts/react*
Scripts/rsvp*
Scripts/select2*
Scripts/sortable*
Scripts/toastr*

After updating your appsettings.scriptbundles.json or any other file referencing old locations for these files, like your CSHTML files, you may delete these files from your wwwroot folder. This is not mandatory, but as they will not be updated anymore with Serenity.Assets, leaving them there might cause you to still use older versions if we update them.

Anything matching the list above should be deleted from wwwroot folder. Of course please first ensure that you didn't modify them, or use them in your pages explicitly, without listing them in appsettings.scriptbundles.json.

You may also delete older versions of jQuery left there, for example:

Scripts/jquery-3.3.1.js,
Scripts/jquery-3.3.1.min.js

Enabling Static Assets for Environments Other Than Development

By default, static assets are only served in Development mode by ASP.NET Core. If you for example build your application and run it in Release mode from output, you'll have script errors. To resolve this issue, add this line to your Program.cs:

public class Program
{
    //...

    public static IHostBuilder CreateHostBuilder(string[] args)
    {
        return Host.CreateDefaultBuilder(args)
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStaticWebAssets(); // add this line
                webBuilder.UseStartup<Startup>();
            })
            // ...
    }

Resolving Issues with CKEditor

CKEditor.js file has an issue with Serenity minification system, and it shouldn't be minimized when bundling and minification is enabled. For this there is a setting in appsettings.json:

///...
"ScriptBundling": {
    "NoMinimize": [
      "~/Scripts/ckeditor/ckeditor.js"
    ],
  }
//...

This should also be updated to the new path:

///...
"ScriptBundling": {
    "NoMinimize": [
      "~/Serenity.Assets/Scripts/ckeditor/ckeditor.js"
    ],
  }
//...

Also by default HtmlContentEditor searches for CKEditor at old location (~/Scripts/ckeditor/ckeditor.js) if it is not already included in the page. We didn't yet change it for backward compatibility. Add this line to ScriptInitialization.ts:

    Serenity.EntityDialog.defaultLanguageList = LanguageList.getValue;
    Serenity.HtmlContentEditor.CKEditorBasePath = "~/Serenity.Assets/Scripts/ckeditor"; // add this

Deleting Unused Serenity Images

Serenity used to contain a set of images under wwwroot/Content/serenity/images which are referenced by site.css and serenity.css. Some of them are still there, but we removed most of them from Serenity.Assets. You may still keep them in your project. If you choose to remove unused ones, see this folder to understand which of them can be safely deleted (delete the ones except these if you didn't use them manually).

https://github.com/serenity-is/Serenity/tree/master/src/Serenity.Assets/Content/serenity/images

Please note that unlike other assets, the files under serenity/images/ are not yet served using static web assets as they are still referenced by some CSS files. If we did, it would break existing applications. So don't prefix them with ~/Serenity.Assets for now. They are still copied to your wwwroot folder with dotnet sergen restore.

Once we convert Serenity.Scripts package to Razor class library, we may convert serenity images to static web assets as well or replace them with Font Awesome or similar icons.

Deleting Obsolete Folders and Files

Folders listed below can be safely deleted from wwwroot if you didn't manually use them anywhere:

wwwroot\Content\themes // contains legacy base jquery ui theme, which we never used
wwwroot\Scripts\serenity\Serenity.CodeGenerator.d.ts // not used in app, embedded by sergen
wwwroot\Scripts\serenity\Serenity.CodeGeneration.js // not used in app, embedded by sergen
wwwroot\Scripts\serenity\Serenity.Script.UI.d.ts // legacy file
wwwroot\Scripts\serenity\Serenity.Script.UI.js // legacy script, remove it from appsettings.bundles.json as well
// we'll be releasing a new modular version of Serenity.CoreLib, delete obsolete folders below if you didn't use
wwwroot\Scripts\serenity\serenity-core\* // delete if you didn't use
wwwroot\Scripts\serenity\serenity-dialogs\* // delete if you didn't use
wwwroot\Scripts\serenity\serenity-editors\* // delete if you didn't use
wwwroot\Scripts\serenity\serenity-filterpanel\* // delete if you didn't use
wwwroot\Scripts\serenity\serenity-forms\* // delete if you didn't use
wwwroot\Scripts\serenity\serenity-grids\* // delete if you didn't use
wwwroot\Scripts\serenity\serenity-quickfilter\* // delete if you didn't use
wwwroot\Scripts\serenity\serenity-slick\* // delete if you didn't use
wwwroot\Scripts\serenity\serenity-widget\* // delete if you didn't use

Fix Syntax Error in bootstrap-social.less

bootstrap-social.less under wwwroot\Content\adminlte\bootstrap-social.less has a syntax error that causes it to compile when using less 4.0+.

Find line below:

.btn-social;

And add parenthesis to it:

.btn-social();

Serenity.Demo.ThemeSamples Package

We have a theme samples section in our demo which is shared between Serene and StartSharp. It's code is identical in both applications and we decided to create a separate project for it and share it as a Razor class library. This way, other than copy/pasting code between two applications, and your copy of StartSharp / Serene applications, we'll be able to update them from one point like other Serenity packages.

This is just a AdminLTE theme sample, and won't make it to your production app, but we want to make it easier to remove such demo features from your application. We'll be applying same principle to other demo parts like Northwind in the near future.

We'll also be making the application fully modular, so features like Organization, Mail Client, Reporting, User Management etc. might get their own Razor class libraries. This will make it much more easier to update them when you need to. And if you would like to modify one of them to your needs, and passing parameters through options pattern is not enough, you may just copy paste the relevant project to your solution and add a project reference, and start customizing.

Common features between Serene and StartSharp like Theme Samples and others will be developed in this new repository:

https://github.com/serenity-is/common-features

Features exclusive to StartSharp will be developed directly in StartSharp repository as separate projects / packages.

If you still have Theme Samples, or want to try how it works, add its package to your application:

<PackageReference Include="Serenity.Demo.ThemeSamples" Version="5.0.20.1" />

If you have Modules/AdminLTE folder in your application, you should delete it.

Also you need to register its assembly for ITypeSource service in Startup.cs:

services.AddSingleton<ITypeSource>(new DefaultTypeSource(new[] 
{
    // ...
    typeof(Startup).Assembly,
    typeof(Serenity.Demo.ThemeSamples.AdminLTEController).Assembly // add this line
}));

Now, even if you have no controller for AdminLTE in your project, you'll still have a Theme Samples section in your navigation and it should be functional. After trying you may safely remove package reference and assembly registration from Startup.

Following static files / folders are part of theme samples and can also be safely deleted from your wwwroot folder if you didn't use them anywhere. They are now served from ~/Serenity.Demo.ThemeSamples/... just like ~/Serenity.Assets does.

Scripts/bootstrap-slider/*
Scripts/colorpicker/*
Scripts/flot/*
Scripts/input-mask/*
Scripts/ionslider/*
Scripts/timepicker/*