Oqtane 6.0 and .NET 9

[sbwalker]

.NET 9 will be released the week of Nov 12 during .NET Conf - which is ~3 weeks from now. Oqtane has always followed the release cadence of .NET for major version releases, so the plan is to release Oqtane 6.0 at the same time that .NET 9 is released. I will be merging the primary changes to migrate Oqtane to .NET 9 RC2 into the Dev branch within the next few days.

In addition to moving the framework dependencies to .NET 9 I would like to integrate a few of the new .NET 9 features into Oqtane:

• use MapStaticAssets middleware
• ensure new Blazor Server Reconnect UI behaves properly and potentially remove the custom JavaScript reconnect logic in Oqtane
• replace MemoryCache with HybridCache (this is required as part of a larger "scale out" enhancement which will be implemented in subsequent Oqtane 6.x releases)
• replace Swagger with OpenAPI

Oqtane will NOT be integrating the following new feature available in .NET 9:

• ExcludeFromInteractiveRouting attribute (relies on the default Blazor router and is not compatible with Oqtane's rendering approach)

Note that this also means that Oqtane 5.2.4 is the last official release on .NET 8.

[sbwalker]

#4761 migrates the framework to .NET 9 RC2. This includes updating the Oqtane version to 6.0.0 and updating the default Module and Theme templates.

There are a few ways to install .NET 9 RC2 onto your machine:

• download and install the latest version of Visual Studio Preview (https://visualstudio.microsoft.com/vs/preview/)
• or download the .NET 9 SDK (https://dotnet.microsoft.com/en-us/download/dotnet/9.0)

Please refer to the following blog post to understand how existing module and theme projects can be updated to work with .NET 9:

https://www.oqtane.org/blog/!/73/upgrading-to-new-net-versions

The most important thing to remember is that your assemblies need to be copied to the bin\Debug\net9.0 folder (whereas previously they were copied to bin\Debug\net8.0 for Oqtane 5.x)

[sbwalker]

Only one breaking change was discovered so far in the upgrade to .NET 9 RC2. The issue affected the install wizard:

An Error Occurred Provisioning The Master Database. This Is Usually Related To The Master Database Not Being In A Supported State. System.InvalidOperationException: An error was generated for warning 'Microsoft.EntityFrameworkCore.Migrations.PendingModelChangesWarning': The model for context 'MasterDBContext' has pending changes. Add a new migration before updating the database. This exception can be suppressed or logged by passing event ID 'RelationalEventId.PendingModelChangesWarning' to the 'ConfigureWarnings' method in 'DbContext.OnConfiguring' or 'AddDbContext'. at Microsoft.EntityFrameworkCore.Diagnostics.EventDefinition1.Log[TLoggerCategory](IDiagnosticsLogger1 logger, TParam arg) at Microsoft.EntityFrameworkCore.Diagnostics.RelationalLoggerExtensions.PendingModelChangesWarning(IDiagnosticsLogger`1 diagnostics, Type contextType) at Microsoft.EntityFrameworkCore.Migrations.Internal.Migrator.Migrate(String targetMigration) at Microsoft.EntityFrameworkCore.RelationalDatabaseFacadeExtensions.Migrate(DatabaseFacade databaseFacade) at Oqtane.Infrastructure.DatabaseManager.MigrateMaster(InstallConfig install) in C:\Source\Projects\oqtane.framework\Oqtane.Server\Infrastructure\DatabaseManager.cs:line 271

This issue had been reported previously here:

dotnet/efcore#34431

The workaround was implemented in Oqtane to allow the install wizard to function properly.

[sbwalker]

Another issue that still needs to be resolved on .NET 9 RC2... the Oqtane.Client project reports a critical warning:

warning NU1904: Package 'System.Text.Encodings.Web' 4.5.0 has a known critical severity vulnerability

System.Text.Encodings.Web is a dependency of Microsoft.AspNetCore.Localization version 2.2.0:

Microsoft.AspNetCore.Localization version 2.2.0 has been flagged as deprecated for quite some time (dotnet/announcements#217) - @thabaum brought this up previously in the migration to .NET 8. The problem is that there is no guidance from Microsoft on what developers are supposed to use to replace this functionality in their applications. It is also very strange that the exact same Nuget package (ie. version 2.2.0) is flagged as a critical severity issue in .NET 9 - but not in .NET 8 (yet the CVE has existed since 2021 - GHSA-ghhp-997w-qr28).

The primary thing which Oqtane uses Microsoft.AspNetCore.Localization for is accessing the CookieRequestCultureProvider. ie.

var localizationCookieValue = CookieRequestCultureProvider.MakeCookieValue(new RequestCulture(culture));
await interop.SetCookie(CookieRequestCultureProvider.DefaultCookieName, localizationCookieValue, 360, true, "Lax");

One solution is to create a local copy of the class in Oqtane (and remove the Microsoft.AspNetCore.Localization dependency):

https://github.com/dotnet/aspnetcore/blob/main/src/Middleware/Localization/src/CookieRequestCultureProvider.cs

Another problem related to the removal of Microsoft.AspNetCore.Localization is that there is no longer access to HttpContext in the Client project. Adding a reference to Microsoft.AspNetCore.Http has similar issues as the package is deprecated and has a security vulnerability. This has now been logged as an issue in the ASP.NET Core report: dotnet/aspnetcore#58593

[sbwalker]

#4774 removes Microsoft.AspNetCore.Localization by copying CookieRequestCultureProvider and RequestCulture classes to the Oqtane solution. However due to other dependencies in the Client project I needed to add a project reference to Microsoft.AspNetCore.Http to get the system to compile. However this package also contains the same critical severity vulnerability so it will need to be removed as well. The challenge is that it is not yet clear how to remove it.

[sbwalker]

#4779 removes the Microsoft.AspNetCore.Http dependency.

[sbwalker]

Upon further investigation, we are not going to be able to use MapStaticAssets in Oqtane. As usual, the "marketing" info about this feature sounds great... but once you read the fine print, the limitations become obvious. You can read about this feature here:

https://learn.microsoft.com/en-us/aspnet/core/blazor/fundamentals/static-files?view=aspnetcore-9.0

In particular:

"Map Static Assets Middleware operates by combining build and publish processes to collect information about the static assets in the app. This information is utilized by the runtime library to efficiently serve the static assets to browsers. Map Static Assets Middleware can replace UseStaticFiles in most situations. However, Map Static Assets Middleware is optimized for serving the assets from known locations in the app at build and publish time. If the app serves assets from other locations, such as disk or embedded resources, UseStaticFiles should be used."

Basically this means that the feature is designed for monolithic tightly-coupled application scenarios where all of the static assets are known during build/deployment. It will not support modular application scenarios where there are multiple independent projects which are built/deployed separately and composed at runtime. It will also not support the upload of static content files at run-time. It will also not support other enhancements which are expected in Oqtane 6.0 such as Folder Providers which will allow content to be stored in other locations (which is essential to scale out scenarios).

[sbwalker]

If you investigate the implementation of MapStaticAssets() on GitHub you will see that it relies on a "manifest" file which is named "ApplicationName.staticwebassets.endpoints.json". This manifest file is only created during deployment of an app (ie. it is not enabled when developing the app locally) and the deployment process also compresses all of the static assets to create new gzipped versions which are deployed with the app. The manifest looks like:

{
  "Version": 1,
  "ManifestType": "Publish",
  "Endpoints": [
    {
      "Route": "BlazorApp20.68o4gdxw9n.styles.css",
      "AssetFile": "BlazorApp20.styles.css.gz",
      "Selectors": [
        {
          "Name": "Content-Encoding",
          "Value": "gzip",
          "Quality": "0.000566893424"
        }
      ],
      "ResponseHeaders": [
        {
          "Name": "Accept-Ranges",
          "Value": "bytes"
        },
        {
          "Name": "Cache-Control",
          "Value": "max-age=31536000, immutable"
        },
        {
          "Name": "Content-Encoding",
          "Value": "gzip"
        },
        {
          "Name": "Content-Length",
          "Value": "1763"
        },
        {
          "Name": "Content-Type",
          "Value": "text/css"
        },
        {
          "Name": "ETag",
          "Value": "\"I71HNZkw7e26hTlDA6JAwoAbFnU2sd8vPWayhfEqIKU=\""
        },
        {
          "Name": "ETag",
          "Value": "W/\"WjiKg3qw5l++uFuWh/tM6FjGu6UD3RIufuTAr0VFQXU=\""
        },
        {
          "Name": "Last-Modified",
          "Value": "Wed, 23 Oct 2024 12:27:56 GMT"
        },
        {
          "Name": "Vary",
          "Value": "Content-Encoding"
        }
      ],

So it is a static approach that is unable to adapt to any changes in the run-time environment. I am fairly certain that most developers will not understand this and will wonder why apps which include any type of uploading of static files do not get the performance benefits.

The good news is that the Oqtane "/files" server already handles uploaded content assets and uses eTags and response caching (and more granular permission support).

[mdmontesinos]

Perhaps there could be a way to integrate this for the "static" assets in Oqtane, basically the ones that are "registered" and discoverable on build time in the module resources. I guess this should be done when packaging a module/theme for release. Obviously, any dynamic assets that are uploaded through the file manager would be excluded from this system, but at least the "static" ones would benefic from the performance improvements.

In this way, the handling of the assets would be different depending on its type.

Static assets from module/theme definitions (css and js):

• ETag
• Caching
• gzip compression
• Fingerprinting (similar to what was asked in Cache Busting for Static Assets #4745)

(new functionality from MapStaticAssets)

Dynamic assets served by "/files":

• ETag
• Caching

(current functionality)

[sbwalker]

@mdmontesinos although this is possible it would only support the limited set of static assets which are part of the Oqtane solution - it would not support custom modules or themes. As I described above, the ApplicationName.staticwebassets.endpoints.json file is generated when you execute the "dotnet publish" command on a .NET project - and it will only include the assets which are statically linked to the main Blazor project. Custom modules and themes are not statically linked to Oqtane - they are discovered and loaded dynamically at run-time. So MapStaticAssets() will not support custom modules and themes.

[mdmontesinos]

@sbwalker What about creating an individual "ApplicationName.staticwebassets.endpoints.json" per module/theme that is created when publishing them and includes its static assets? Then, Oqtane could implement a way of discovering these files on run-time and recover the assets from there.

[sbwalker]

My understanding is that the MapStaticAssets middleware only supports a single ApplicationName.staticwebassets.endpoints.json manifest. Basically this feature was not designed for modular applications. So I am going to focus on other general compatibility issues related to .NET 9.

[sbwalker]

When using Blazor Server for interactivity the SignalR reconnection experience has been improved in .NET 9

https://learn.microsoft.com/en-us/aspnet/core/release-notes/aspnetcore-9.0?view=aspnetcore-9.0#improved-server-side-reconnection-experience

[sbwalker]

Investigated OpenAPI integration and ran into an issue so I reported it here:

dotnet/aspnetcore#58805

[sbwalker]

In the Oqtane Developer meeting today we discussed assemblies which were included as part of .NET 8 which are no longer included as part of .NET 9 (and therefore will not be included by default in Oqtane 6.0). If a third party module is dependent on any of these assemblies, it means that they would need to include them in their module installation package:

Microsoft.AspNetCore.Authorization.dll
Microsoft.AspNetCore.Components.Authorization.dll
Microsoft.AspNetCore.Components.dll
Microsoft.AspNetCore.Components.Forms.dll
Microsoft.AspNetCore.Components.Web.dll
Microsoft.AspNetCore.Cryptography.Internal.dll
Microsoft.AspNetCore.Cryptography.KeyDerivation.dll
Microsoft.AspNetCore.Metadata.dll
Microsoft.Extensions.Caching.Memory.dll
Microsoft.Extensions.Configuration.Binder.dll
Microsoft.Extensions.Configuration.FileExtensions.dll
Microsoft.Extensions.Configuration.Json.dll
Microsoft.Extensions.DependencyInjection.Abstractions.dll
Microsoft.Extensions.DependencyInjection.dll
Microsoft.Extensions.Diagnostics.Abstractions.dll
Microsoft.Extensions.Diagnostics.dll
Microsoft.Extensions.Http.dll
Microsoft.Extensions.Identity.Core.dll
Microsoft.Extensions.Identity.Stores.dll
Microsoft.Extensions.Localization.Abstractions.dll
Microsoft.Extensions.Localization.dll
Microsoft.Extensions.Logging.Abstractions.dll
Microsoft.Extensions.Logging.dll
Microsoft.Extensions.Options.dll
Microsoft.JSInterop.dll
System.Runtime.Caching.dll
System.Text.Json.dll

Note that this only includes the Oqtane.Server project

[mdmontesinos]

Could you further explain this? How does Oqtane work properly if it doesn't include basic assemblies such as JSInterop or Logging?

[sbwalker]

@mdmontesinos I did a Publish and compared an Install.zip package from Oqtane 5.2.4 to Oqtane 6.0.0 and it appears that some of the assemblies which used to be included in the root (ie. bin) folder are now included in the /refs folder. I am guessing this means that Microsoft has moved some assemblies which are commonly used in ASP.NET Core applications into the "framework" package (ie. Microsoft.AspNetCore.App) so that they are included by default. So the only assembly which is no longer included in the root or /refs appears to be System.Runtime.Caching.dll. You can see the comparison report here:

https://www.oqtane.org/files/Public/NET9.html

[mdmontesinos]

Will Oqtane 6.0 be finally released together with .NET 9?

[sbwalker]

Yes, that is the plan. Obviously .NET 9 needs to be released first so that all of the package references can be updated in Oqtane to the official release packages. And then some final testing before the actual release. So I would expect Oqtane to be released on Wed or Thu this week. The Oqtane 6.0 release launch will be on Nov 20 - https://www.linkedin.com/events/announcingoqtane6-0on-net97260284727931129858/comments/

[mdmontesinos]

Awesome, thanks for the great work! I assume HybridCache won't be on the first release right? Because Microsoft is also delaying it.

HybridCache is currently still in preview but will be fully released after .NET 9.0 in a future minor release of .NET Extensions.

[sbwalker]

Interesting... I was not aware that HybridCache is delayed. I had integration challenges with the current version of HybridCache as it only offers asynchronous methods, so perhaps there is still time to raise this to Microsoft before the official release.

[sbwalker]

.NET 9 is now officially released... so I will be updating Oqtane to the official packages shortly.

[sbwalker]

There is a build issue with the final .NET 9 packages which did not exist with RC2. It is related to the PostgreSQL database provider:

Version conflict detected for Microsoft.EntityFrameworkCore. Install/reference Microsoft.EntityFrameworkCore 9.0.0 directly to project Oqtane.Database.PostgreSQL to resolve this issue.
Oqtane.Database.PostgreSQL -> Microsoft.EntityFrameworkCore.Relational 9.0.0 -> Microsoft.EntityFrameworkCore (>= 9.0.0)
Oqtane.Database.PostgreSQL -> EFCore.NamingConventions 8.0.3 -> Microsoft.EntityFrameworkCore (>= 8.0.0 && < 9.0.0).

A 9.0 package had not yet been released for EFCore.NamingConventions:

efcore/EFCore.NamingConventions#295

[sbwalker]

Since PostgreSQL is still in RC status and does not have an official .NET 9 release yet, perhaps Oqtane 6.0 should use the .NET 8 packages.

[sbwalker]

problem with PostgreSQL Database provider was resolved by @zyhfish using the .NET 9 packages with the EFCore.NamingConventions 8.0.3 (we will update EFCore.NamingConventions to 9.x once it is available)

[sbwalker]

A new issue is happening when trying to run Oqtane.MAUI solution - the project will not run and displays the message:

"The project needs to be deployed before we can debug. Please enable Deploy in the Configuration Manager"

However Deploy is already enabled in Configuration Manager.

This was working fine on .NET 9 RC2

Logged here (with other people who are experiencing the same problem):

dotnet/maui#25832

[sbwalker]

.NET MAUI issue is now resolved