Build and Publish Demo Applications

This topic explains how to build and publish the HiQPdf Next ASP.NET demo applications which can be downloaded as a ZIP file from the HiQPdf website. It should be used after completing the Getting Started guide for Windows and the corresponding Getting Started guide for Linux. The topic includes instructions for the Windows, Linux, macOS and Cross-Platform demos, covering both x64 and ARM64 architectures.

The sources of each demo application exist once in the ZIP file, in the AspNetDemo and ConsoleDemo folders. The platform and the .NET version are chosen by opening the matching project file, for example HiQPdf_Next_AspNetDemo_Linux_net10.0.csproj. The projects of a folder share their sources but keep their own bin and obj subfolders, so they never overwrite each other. For the same reason, give each publish command its own output folder.

The Windows demo is built from the AspNetDemo folder. It provides a Windows x64 and a Windows ARM64 project, each in a .NET 10 and a .NET 8 variant.

The Windows x64 demo application can be deployed to Windows servers, Azure App Service Windows, Azure Functions Windows or Docker Windows containers. The ARM64 build is intended for Windows ARM64 servers and desktops.

Windows x64

The Windows x64 demo project file is HiQPdf_Next_AspNetDemo_Windows_net10.0.csproj and it uses the HiQPdf.Next.Windows package from NuGet, which contains .NET Standard 2.0 assemblies and the Windows x64 runtimes for all HiQPdf Next components. The .NET 8 project has the same name with the _net8.0 suffix, as described in the Change Target Framework section below.

Build the application:

dotnet build -c Release -r win-x64 HiQPdf_Next_AspNetDemo_Windows_net10.0.csproj

Publish the application:

dotnet publish -c Release -r win-x64 -o publish/windows-x64-net10.0 HiQPdf_Next_AspNetDemo_Windows_net10.0.csproj

Run the published application. Change into the publish folder first so that the application can locate its content files:

cd publish/windows-x64-net10.0
dotnet HiQPdf_Next_AspNetDemo_Windows_net10.0.dll

Windows ARM64

The Windows ARM64 demo project file is HiQPdf_Next_AspNetDemo_Windows.Arm64_net10.0.csproj and it uses the HiQPdf.Next.Windows.Arm64 package from NuGet, which contains .NET Standard 2.0 assemblies and the Windows ARM64 runtimes for all HiQPdf Next components.

Build the application:

dotnet build -c Release -r win-arm64 HiQPdf_Next_AspNetDemo_Windows.Arm64_net10.0.csproj

Publish the application:

dotnet publish -c Release -r win-arm64 -o publish/windows-arm64-net10.0 HiQPdf_Next_AspNetDemo_Windows.Arm64_net10.0.csproj

Run the published application. Change into the publish folder first so that the application can locate its content files:

cd publish/windows-arm64-net10.0
dotnet HiQPdf_Next_AspNetDemo_Windows.Arm64_net10.0.dll

Change Target Framework

Each demo comes with a project file for .NET 10.0 and one for .NET 8.0, both long term support releases. Open the _net10.0 project with Visual Studio 2026 or with the .NET 10 SDK and the _net8.0 project with Visual Studio 2022, which cannot target .NET 10. To target another .NET version, change the TargetFramework element in the .csproj project file.

<PropertyGroup>
  <TargetFramework>net10.0</TargetFramework>
</PropertyGroup>

Self-Contained Deployment

You can add the --self-contained true option to the publish command to create a self-contained deployment that does not require the .NET runtime to be installed on the target machine.

Notes

The published application listens on http://localhost:5000 by default. To use another address, set the ASPNETCORE_URLS environment variable or add the --urls option to the run command, for example --urls http://localhost:28100. When the demo is started from Visual Studio or with dotnet run, it uses its launch profile and opens at http://localhost:28100. To access the demo from another machine, listen on all network interfaces, for example --urls http://0.0.0.0:28100, and allow the port in the firewall.

On Windows, no additional configuration is normally required. For platform-specific deployment details, consult the Getting Started on Windows guide as well as the specific guides for Publishing to Azure App Service Windows, Publishing to Azure Functions Windows or Publishing to Docker on Windows.

The Linux demo is built from the AspNetDemo folder. It provides a Linux x64 and a Linux ARM64 project, each in a .NET 10 and a .NET 8 variant.

The Linux x64 demo application can be deployed to Linux servers, Azure App Service Linux, Azure Functions Linux or Docker Linux containers. The ARM64 build targets Linux ARM64 servers and Linux ARM64 Docker containers.

Linux x64

The Linux x64 demo project file is HiQPdf_Next_AspNetDemo_Linux_net10.0.csproj and it uses the HiQPdf.Next.Linux package from NuGet, which contains .NET Standard 2.0 assemblies and the Linux x64 runtimes for all HiQPdf Next components. The .NET 8 project has the same name with the _net8.0 suffix, as described in the Change Target Framework section below.

Build the application:

dotnet build -c Release -r linux-x64 HiQPdf_Next_AspNetDemo_Linux_net10.0.csproj

Publish the application:

dotnet publish -c Release -r linux-x64 -o publish/linux-x64-net10.0 HiQPdf_Next_AspNetDemo_Linux_net10.0.csproj

Run the published application. Change into the publish folder first so that the application can locate its content files:

cd publish/linux-x64-net10.0
dotnet HiQPdf_Next_AspNetDemo_Linux_net10.0.dll

Linux ARM64

The Linux ARM64 demo project file is HiQPdf_Next_AspNetDemo_Linux.Arm64_net10.0.csproj and it uses the HiQPdf.Next.Linux.Arm64 package from NuGet, which contains .NET Standard 2.0 assemblies and the Linux ARM64 runtimes for all HiQPdf Next components.

Build the application:

dotnet build -c Release -r linux-arm64 HiQPdf_Next_AspNetDemo_Linux.Arm64_net10.0.csproj

Publish the application:

dotnet publish -c Release -r linux-arm64 -o publish/linux-arm64-net10.0 HiQPdf_Next_AspNetDemo_Linux.Arm64_net10.0.csproj

Run the published application. Change into the publish folder first so that the application can locate its content files:

cd publish/linux-arm64-net10.0
dotnet HiQPdf_Next_AspNetDemo_Linux.Arm64_net10.0.dll

Change Target Framework

Each demo comes with a project file for .NET 10.0 and one for .NET 8.0, both long term support releases. Open the _net10.0 project with Visual Studio 2026 or with the .NET 10 SDK and the _net8.0 project with Visual Studio 2022, which cannot target .NET 10. To target another .NET version, change the TargetFramework element in the .csproj project file.

<PropertyGroup>
  <TargetFramework>net10.0</TargetFramework>
</PropertyGroup>

Self-Contained Deployment

You can add the --self-contained true option to the publish command to create a self-contained deployment that does not require the .NET runtime to be installed on the target machine.

Notes

The published application listens on http://localhost:5000 by default. To use another address, set the ASPNETCORE_URLS environment variable or add the --urls option to the run command, for example --urls http://localhost:28100. When the demo is started from Visual Studio or with dotnet run, it uses its launch profile and opens at http://localhost:28100. To access the demo from another machine, listen on all network interfaces, for example --urls http://0.0.0.0:28100, and allow the port in the firewall.

On Linux, additional packages must be installed before running HTML to PDF conversion. For platform-specific deployment details and the list of required system dependencies, consult the Getting Started on Linux guide as well as the specific guides for Publishing to Azure App Service Linux, Publishing to Azure Functions Linux or Publishing to Docker on Linux.

The macOS demo is built from the AspNetDemo folder. macOS is supported on Apple Silicon (ARM64) only, so a single project is provided, in a .NET 10 and a .NET 8 variant.

The macOS demo project file is HiQPdf_Next_AspNetDemo_MacOS_net10.0.csproj and it uses the HiQPdf.Next.MacOS package from NuGet, which contains .NET Standard 2.0 assemblies and the macOS ARM64 runtimes for all HiQPdf Next components. The .NET 8 project has the same name with the _net8.0 suffix, as described in the Change Target Framework section below.

Build and Publish

Build the application:

dotnet build -c Release -r osx-arm64 HiQPdf_Next_AspNetDemo_MacOS_net10.0.csproj

Publish the application:

dotnet publish -c Release -r osx-arm64 -o publish/macos-net10.0 HiQPdf_Next_AspNetDemo_MacOS_net10.0.csproj

Run the published application. Change into the publish folder first so that the application can locate its content files:

cd publish/macos-net10.0
dotnet HiQPdf_Next_AspNetDemo_MacOS_net10.0.dll

Change Target Framework

Each demo comes with a project file for .NET 10.0 and one for .NET 8.0, both long term support releases. Open the _net10.0 project with Visual Studio 2026 or with the .NET 10 SDK and the _net8.0 project with Visual Studio 2022, which cannot target .NET 10. To target another .NET version, change the TargetFramework element in the .csproj project file.

<PropertyGroup>
  <TargetFramework>net10.0</TargetFramework>
</PropertyGroup>

Self-Contained Deployment

You can add the --self-contained true option to the publish command to create a self-contained deployment that does not require the .NET runtime to be installed on the target machine.

Notes

The published application listens on http://localhost:5000 by default. To use another address, set the ASPNETCORE_URLS environment variable or add the --urls option to the run command, for example --urls http://localhost:28100. When the demo is started from Visual Studio or with dotnet run, it uses its launch profile and opens at http://localhost:28100.

macOS deployment targets version 12.0 (Monterey) or later on Apple Silicon.

The Cross-Platform demo is built from the AspNetDemo folder. It shows how to target several platforms from a single project by combining HiQPdf Next NuGet packages. Two projects are provided, one for x64 and one for ARM64, each in a .NET 10 and a .NET 8 variant.

The x64 demo application can be deployed to Windows and Linux servers, Azure App Service, Azure Functions or Docker containers for both Windows and Linux. The ARM64 build targets Windows and Linux ARM64 servers, including Linux ARM64 Docker containers.

Cross-Platform x64

The x64 project file is HiQPdf_Next_AspNetDemo_MultiPlatform_net10.0.csproj and it references the HiQPdf.Next.Windows and HiQPdf.Next.Linux packages for the Windows x64 and Linux x64 runtimes. Referencing the HiQPdf.Next metapackage instead gives the same result, since it depends on these two packages. The .NET 8 project has the same name with the _net8.0 suffix, as described in the Change Target Framework section below.

Build the portable version:

dotnet build -c Release HiQPdf_Next_AspNetDemo_MultiPlatform_net10.0.csproj

Publish the portable version, which runs on Windows x64 and Linux x64 where the .NET runtime is installed:

dotnet publish -c Release -o publish/portable-net10.0 HiQPdf_Next_AspNetDemo_MultiPlatform_net10.0.csproj

Run the portable build. Change into the publish folder first so that the application can locate its content files:

cd publish/portable-net10.0
dotnet HiQPdf_Next_AspNetDemo_MultiPlatform_net10.0.dll

Alternatively, publish for a specific runtime. For Windows x64:

dotnet publish -c Release -r win-x64 -o publish/multiplatform-windows-x64-net10.0 HiQPdf_Next_AspNetDemo_MultiPlatform_net10.0.csproj

Run it. Change into the publish folder first so that the application can locate its content files:

cd publish/multiplatform-windows-x64-net10.0
dotnet HiQPdf_Next_AspNetDemo_MultiPlatform_net10.0.dll

For Linux x64:

dotnet publish -c Release -r linux-x64 -o publish/multiplatform-linux-x64-net10.0 HiQPdf_Next_AspNetDemo_MultiPlatform_net10.0.csproj

Run it. Change into the publish folder first so that the application can locate its content files:

cd publish/multiplatform-linux-x64-net10.0
dotnet HiQPdf_Next_AspNetDemo_MultiPlatform_net10.0.dll

Cross-Platform ARM64

The ARM64 project file is HiQPdf_Next_AspNetDemo_MultiPlatform.Arm64_net10.0.csproj and it references the HiQPdf.Next.Windows.Arm64 and HiQPdf.Next.Linux.Arm64 packages for the Windows ARM64 and Linux ARM64 runtimes.

Build the portable version:

dotnet build -c Release HiQPdf_Next_AspNetDemo_MultiPlatform.Arm64_net10.0.csproj

Publish for Windows ARM64:

dotnet publish -c Release -r win-arm64 -o publish/multiplatform-windows-arm64-net10.0 HiQPdf_Next_AspNetDemo_MultiPlatform.Arm64_net10.0.csproj

Run it. Change into the publish folder first so that the application can locate its content files:

cd publish/multiplatform-windows-arm64-net10.0
dotnet HiQPdf_Next_AspNetDemo_MultiPlatform.Arm64_net10.0.dll

Publish for Linux ARM64:

dotnet publish -c Release -r linux-arm64 -o publish/multiplatform-linux-arm64-net10.0 HiQPdf_Next_AspNetDemo_MultiPlatform.Arm64_net10.0.csproj

Run it. Change into the publish folder first so that the application can locate its content files:

cd publish/multiplatform-linux-arm64-net10.0
dotnet HiQPdf_Next_AspNetDemo_MultiPlatform.Arm64_net10.0.dll

Adding macOS

To also target macOS ARM64, add the HiQPdf.Next.MacOS package to either the x64 or the ARM64 project. The single-platform packages can be referenced in any combination to target exactly the platforms and architectures your application needs.

Change Target Framework

Each demo comes with a project file for .NET 10.0 and one for .NET 8.0, both long term support releases. Open the _net10.0 project with Visual Studio 2026 or with the .NET 10 SDK and the _net8.0 project with Visual Studio 2022, which cannot target .NET 10. To target another .NET version, change the TargetFramework element in the .csproj project file.

<PropertyGroup>
  <TargetFramework>net10.0</TargetFramework>
</PropertyGroup>

Limit to a Specific Platform

Building for all the platforms referenced by the project may bring many files into the output folder. During development it is often useful to restrict build output to a single OS by setting the RuntimeIdentifier property in the project file.

To limit to Windows x64:

<PropertyGroup>
  <RuntimeIdentifier>win-x64</RuntimeIdentifier>
</PropertyGroup>

To limit to Linux x64:

<PropertyGroup>
  <RuntimeIdentifier>linux-x64</RuntimeIdentifier>
</PropertyGroup>

Notes

The HiQPdf Next libraries automatically detect the operating system at runtime and use the appropriate files for the platform.

On Linux, additional packages must be installed before running HTML to PDF conversion. For platform-specific deployment details, consult the Getting Started on Windows and Getting Started on Linux guides.

You can now continue with the platform-specific deployment guides such as Publishing to Azure App Service Windows or Publishing to Azure App Service Linux for Azure App Service, Publishing to Azure Functions Windows or Publishing to Azure Functions Linux for Azure Functions, Publishing to Docker on Windows or Publishing to Docker on Linux for Docker.

Reference

Other Resources