2sic Imageflow Oqtane module middleware

Imageflow.NET Server image processing and optimizing middleware with querystring API for Oqtane

Release notes

Because nuget package with dependencies for all runtimes is very big separate smaller packages are created for different platforms. Recommendation is to install only packages that targets platforms in use. Installing more packages in same oqtane installation will effectively append runtime dependence from last package.

• ToSic.Imageflow.Oqtane.x.x.x.nupkg (19 MB) - all runtimes,
• ToSic.Imageflow.Oqtane.x.x.x-linux.nupkg (6 MB) - linux, unix runtimes,
• ToSic.Imageflow.Oqtane.x.x.x-osx.nupkg (6 MB) - osx runtime,
• ToSic.Imageflow.Oqtane.x.x.x-win.nupkg (8 MB) - win runtimes.

Install Imageflow module in Oqtane

Install it in standard way, as any other oqtane module.

Option a)

1. Open Module Management in Admin Dashboard. On Download tab find Imageflow in list of modules. Click on its Download button. After download click on Install.

   

Option b)

1. From https://github.com/2sic/oqtane-imageflow/releases download latest ToSic.Imageflow.Oqtane.x.x.x-*.nupkg.

2. Open Module Management in Admin Dashboard and select Upload tab. Upload ToSic.Imageflow.Oqtane.x.x.x-*.nupkg and Install,

Option c)

1. From https://github.com/2sic/oqtane-imageflow/releases download latest ToSic.Imageflow.Oqtane.x.x.x-*.nupkg.

2. Just copy ToSic.Imageflow.Oqtane.x.x.x-*.nupkg package to your Oqtane.Server\wwwroot\Modules\ and next oqtane website restart will auto-install Imageflow module as part of oqtane application startup process.

Development in Oqtane.Framework with Imageflow nuget dependency

1. It is required to have Oqtane.Framework development environment in folder oqtane.framework.

   git clone https://github.com/oqtane/oqtane.framework.git

2. In Visual Studio open oqtane.framework\Oqtane.sln.

3. Open Manage nuget packages for solution.., find ToSic.Imageflow.Oqtane nuget package and Install to Oqtane.Server project as dependency.

   

4. Or, from https://github.com/2sic/oqtane-imageflow/releases download latest ToSic.Imageflow.Oqtane.x.x.x-*.nupkg and just copy ToSic.Imageflow.Oqtane.x.x.x-*.nupkg package to your Oqtane.Server\wwwroot\Modules\

Develop Imageflow module in Oqtane.Framework

1. It is required to have Oqtane.Framework development environment in folder oqtane.framework.

   git clone https://github.com/oqtane/oqtane.framework.git

2. By convention if you place the Imageflow module root folder at the same level as the oqtane.framework, then you will not have to modify any folder configuration in the oqtane-imageflow\Src\Package\ToSic.Imageflow.Oqtane.Package.csproj project.

   git clone https://github.com/2sic/oqtane-imageflow.git

How to deploy Imageflow to Oqtane.Framework?

1. In Visual Studio open oqtane-imageflow\Src\ToSic.Imageflow.Oqtane.sln.

2. Build Debug configuration to deploy Imageflow module to Oqtane.Framework. A Release build creates the installation packages.

3. In Visual Studio open oqtane.framework\Oqtane.sln and Run it.

How to locally package ToSic.Imageflow.Oqtane.x.x.x-*.nupkg?

1. Build release version and pack to ToSic.Imageflow.Oqtane.x.x.x-*.nupkg

   cd InstallPackages
   pack.cmd

The wrapper runs the Release build once. Its post-build step publishes the server and creates all four packages, stopping if publishing or packing fails.

• InstallPackages/NuGet/ToSic.Imageflow.Oqtane.x.x.x.nupkg contains all runtimes. Use only InstallPackages/NuGet as the local NuGet source and publish this package to NuGet.
• InstallPackages/Platforms/ToSic.Imageflow.Oqtane.x.x.x-{linux,osx,win}.nupkg contains the platform-specific installers for manual upload or GitHub release assets.

All variants share the same NuGet ID and version. Keep platform installers and older packages in the parent InstallPackages folder out of the NuGet source, so restore cannot select a platform-specific package instead of the all-runtimes package.

Native runtime upgrades

Native libraries use versioned names, for example runtimes/win-x64/native/imageflow-2.3.1-rc01.dll. The binaries are unchanged; the build embeds their SHA-256 hashes from the resolved NuGet packages. The startup filter registers the native resolver before registering the Imageflow middleware. It checks the packaged runtime's hash and ABI, and also supports the flat native layout produced by a publish for a specific RID.

This avoids overwriting a loaded native library and Oqtane's FileVersion comparison, which can silently skip native Windows DLLs without a numeric file version. A compatible standard native library remains supported when the versioned payload is absent.

On Linux and macOS the module loads a verified, hash-addressed copy under the current user's temporary directory. This also isolates the loaded library from a reinstall that truncates the packaged .so or .dylib. The cache works with a read-only application directory; a writable temporary directory is required.

On Windows, if the standard library is missing or incompatible, the module can recover from an Oqtane temp.dll left in the native directory. It requires the exact SHA-256 for the current runtime, copies it atomically to the versioned filename, and loads the copy. It leaves the original DLL and temp.dll unchanged and does not keep temp.dll loaded. Selection, ABI and fallback use are logged. An unknown or wrong-architecture temp.dll is rejected before native code is loaded.

Native runtime verification

See the test guide for the purpose and expected result of every case, fixture requirements, runnable examples, result files and the limits of a passing run. The tests are executable integration checks, started with dotnet run, rather than tests discovered by dotnet test.

Run the process-isolated HTTP tests with .NET 10 installed:

dotnet run --project Src/Tests/ToSic.Imageflow.Oqtane.Tests.csproj -c Release

Each case starts a fresh process because native imports and their resolver are cached for the process lifetime. Tests cover startup, versioned and standard layouts, rejection of corrupted payloads, and actual 176x176 PNG responses through Imageflow and HybridCache. On Windows, pass --old-native <path-to-ABI-3.0-imageflow.dll> after -- to include an already loaded old library, verified temp.dll recovery and restart. The test directory can be set with --output <directory>.

After packaging, run pwsh -File Src/Tests/Verify-Packages.ps1 to verify all four archives, hashes and isolated NuGet consumers on .NET 9 and .NET 10, including a win-x64 publish. Optional -OldNativePath, -OqtaneServerPath and -PreviousPackagePath parameters enable legacy recovery and upgrade tests using the real Oqtane installer against isolated fixtures. The original installation is not changed. This script requires PowerShell 7 and both .NET SDKs; it uses fresh package and HTTP caches.

More info

1. Querystring API documentation
2. Imageflow.NET Server
3. Imageflow
4. Oqtane