Upgrading To New .NET Versions
By: Shaun Walker
Based on the fact that backward compatibility is one of the core philosophies of Oqtane, there are a variety of approaches you can take to allow your development environment to take advantage of newer versions of .NET.
Upgrade Extension To Latest .NET Version
One approach would be to upgrade the dependencies of your custom extensions to use the new version of .NET. This would allow them to use all of the latest .NET features, however it also means that your project would only be compatible with the latest .NET version. So if you need to support environments which are running older versions of .NET which you do not intend to upgrade then you should not update your dependencies to the latest version.
Upgrading to the latest version usually involves a few steps:
1. Update the TargetFramework and PackageReferences in your project (*.csproj) files. You can use the Oqtane Framework itself or a new module created using the Module Creator as a reference. Note that when updating to a new version of .NET, it will utilize a new set of folders under the /bin (ie. /bin/Debug/net8.0). This is important to understand, as you will need to update the folder paths related to assembly deployment in your extension (see #2 and #3).
2. The "Package" project contains a debug.cmd file which is executed as a post-build step when you compile your module or theme in Debug Configuration. This cmd file deploys the assemblies and static assets for your module or theme to the Oqtane framework /bin folder. So if you upgrade to a newer version of Oqtane which is based on a newer version of .NET, you will need to modify the path references in the debug.cmd so that the assets are deployed to the correct location.
XCOPY "..\Client\bin\Debug\net8.0\YourCompany.YourModule.Client.Oqtane.dll" "..\..\oqtane.framework\Oqtane.Server\bin\Debug\net8.0\" /Y
3. The "Package" project also contains a *.nuspec file which is executed as a post-build step using release.cmd when you compile your module or theme in Release Configuration. This nuspec file contains instructions for building a Nuget package and it contains paths which will need to be updated.
<file src="..\Client\bin\Release\net8.0\YourCompany.YourModule.Client.Oqtane.dll" target="lib\net8.0" />
Upgrade Oqtane Environment But Do Not Upgrade Your Extension
Another approach would be to upgrade your Oqtane environment to the latest version of .NET but continue developing your extension on an older version of Oqtane and .NET. This would restrict you from using the latest .NET features, however it would allow your project to remain compatible with older versions. So if you need to support environments which are running older versions of .NET, this approach may be preferable.
In order to do this, there are 2 basic concepts you need to keep in mind:
1. Use package references in your project files. Note that when you scaffold projects using the Module or Theme Creator it is sometimes convenient to target the "Installed Version" - which includes assembly references to the Oqtane framework. If you want to bind your project to a "fixed" version of Oqtane you will want to use package references. You can do this by selecting a specific Version when scaffolding your modules or themes, or by manually modifying your project files. The example below includes a reference to Oqtane 2.3.1 (.NET 5)
<PackageReference Include="Oqtane.Client" Version="2.3.1" />
2. The "Package" project contains a debug.cmd file which is executed as a post-build step when you compile your module or theme. This cmd file deploys the assemblies and static assets for your module or theme to the Oqtane framework /bin folder. So if you upgrade to a newer version of Oqtane which is based on a newer version of .NET, you will need to modify the path references in the debug.cmd so that the assets are deployed to the correct location. The example below is building to the "net5.0" folder but then deploying to the "net8.0" folder.
XCOPY "..\Client\bin\Debug\net5.0\YourCompany.YourModule.Client.Oqtane.dll" "..\..\oqtane.framework\Oqtane.Server\bin\Debug\net8.0\" /Y
And that's all you need to do. The ability to develop on older versions of Oqtane/.NET is definitely a significant developer benefit as you do not need to worry about upgrading all of your Oqtane projects when a new major version is released... yet you are still able to upgrade your Oqtane framework instance to take advantage of the latest features.