Developing on Legacy Versions of Oqtane and .NET


By: Shaun Walker

Based on the fact that Oqtane takes backward compatibility very seriously, it is possible to continue developing modules and themes based on legacy versions of Oqtane and .NET (without upgrading them) using the latest version of the Oqtane framework as a run-time in your development environment.

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.

  <PackageReference Include="Oqtane.Client" Version="2.3.1" />
  <PackageReference Include="Oqtane.Shared" 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 for a module based on Oqtane 2.x which was based on .NET 5 - the module is building to the "net5.0" folder but then deploying to the "net7.0" folder.

XCOPY "..\Client\bin\Debug\net5.0\YourCompany.YourModule.Client.Oqtane.dll" "..\..\oqtane.framework\Oqtane.Server\bin\Debug\net7.0\" /Y
XCOPY "..\Client\bin\Debug\net5.0\YourCompany.YourModule.Client.Oqtane.pdb" "..\..\oqtane.framework\Oqtane.Server\bin\Debug\net7.0\" /Y
XCOPY "..\Server\bin\Debug\net5.0\YourCompany.YourModule.Server.Oqtane.dll" "..\..\oqtane.framework\Oqtane.Server\bin\Debug\net7.0\" /Y
XCOPY "..\Server\bin\Debug\net5.0\YourCompany.YourModule.Server.Oqtane.pdb" "..\..\oqtane.framework\Oqtane.Server\bin\Debug\net7.0\" /Y
XCOPY "..\Shared\bin\Debug\net5.0\YourCompany.YourModule.Shared.Oqtane.dll" "..\..\oqtane.framework\Oqtane.Server\bin\Debug\net7.0\" /Y
XCOPY "..\Shared\bin\Debug\net5.0\YourCompany.YourModule.Shared.Oqtane.pdb" "..\..\oqtane.framework\Oqtane.Server\bin\Debug\net5.0\" /Y
XCOPY "..\Server\wwwroot\Modules\YourCompany.YourModule\*" "..\..\oqtane.framework\Oqtane.Server\wwwroot\Modules\YourCompany.YourModule\" /Y /S /I

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.

Do You Want To Be Notified When Blogs Are Published?

An error has occurred. This application may no longer respond until reloaded. Reload 🗙