Table of Contents

Platform Selection

Velocity is available in five different NuGet packages, each tailored for specific database and platform requirements. Your choice depends primarily on whether you need IBM DB2 and/or SQLite support.

Quick Selection Guide

Need DB2 or SQLite?

  • No → Use YndigoBlue.Velocity (standard, works on all platforms)
  • Yes → Use a platform-specific package:
    • YndigoBlue.Velocity.Windows (x64)
    • YndigoBlue.Velocity.Linux (x64)
    • YndigoBlue.Velocity.MacOS (Arm64)
    • YndigoBlue.Velocity.RaspberryPi (Arm64, SQLite only)

Package Comparison

Package Platforms Architecture DB2 Support SQLite Support Other Databases
YndigoBlue.Velocity All .NET 10 platforms Any ❌ ❌ ✅
YndigoBlue.Velocity.Windows Windows x64 ✅ ✅ ✅
YndigoBlue.Velocity.Linux Linux x64 ✅ ✅ ✅
YndigoBlue.Velocity.MacOS macOS Arm64 ✅ ✅ ✅
YndigoBlue.Velocity.RaspberryPi Raspberry Pi OS Arm64 ❌ ✅ ✅

Other Databases: MySQL, Oracle, PostgreSQL, SQL Server, Teradata

YndigoBlue.Velocity (Standard)

The standard package works on all platforms supported by .NET 10 without requiring platform-specific builds.

Use this package if you:

  • Do NOT need IBM DB2 or SQLite support
  • Want maximum platform portability
  • Prefer simpler build configurations
  • Are using MySQL, Oracle, PostgreSQL, SQL Server, or Teradata

Installation:

dotnet add package YndigoBlue.Velocity

Important limitations:

  • DB2 and SQLite .NET providers are not referenced
  • DB2 and SQLite-specific classes and enums are unavailable
  • Cannot connect to DB2 or SQLite databases
Warning

If you might need DB2 or SQLite support in the future, start with a platform-specific package. Switching packages later requires code changes if you've used any database-specific APIs.

Platform-Specific Packages

Platform-specific packages include DB2 and SQLite support but require targeting specific architectures and operating systems.

Architecture Requirements

  • x64 - Windows and Linux packages
  • Arm64 - macOS and Raspberry Pi packages

Package Details

YndigoBlue.Velocity.Windows

dotnet add package YndigoBlue.Velocity.Windows
  • Platform: Windows
  • Architecture: x64
  • Includes: DB2, SQLite, and all other database providers

YndigoBlue.Velocity.Linux

dotnet add package YndigoBlue.Velocity.Linux
  • Platform: Linux
  • Architecture: x64
  • Includes: DB2, SQLite, and all other database providers

YndigoBlue.Velocity.MacOS

dotnet add package YndigoBlue.Velocity.MacOS
  • Platform: macOS
  • Architecture: Arm64
  • Includes: DB2, SQLite, and all other database providers

YndigoBlue.Velocity.RaspberryPi

dotnet add package YndigoBlue.Velocity.RaspberryPi
  • Platform: Raspberry Pi OS
  • Architecture: Arm64
  • Includes: SQLite and all other database providers
  • Note: DB2 is NOT supported on Raspberry Pi

Why Platform-Specific Packages?

Platform-specific packages exist due to native library dependencies that cannot be unified across platforms:

IBM DB2: IBM distributes separate native DB2 data providers for each OS and architecture rather than providing a single managed .NET provider. This means you cannot use one package across all platforms when DB2 support is required.

SQLite Geospatial Support: Velocity provides geospatial capabilities for SQLite through native binaries (leveraging SpatiaLite and related libraries). These native extensions must be compiled separately for each platform architecture, requiring platform-specific packages to bundle the correct binaries for Windows x64, Linux x64, macOS Arm64, and Raspberry Pi Arm64.

Configuring Platform Targets

When using platform-specific packages, you must set the correct platform target in your project configuration to avoid compilation warnings and ensure proper native library loading.

Required Platform Targets

  • Windows/Linux packages: x64
  • macOS/Raspberry Pi packages: Arm64

Setting Platform Target in .csproj

<PropertyGroup>
  <PlatformTarget>x64</PlatformTarget>
</PropertyGroup>

For Arm64:

<PropertyGroup>
  <PlatformTarget>ARM64</PlatformTarget>
</PropertyGroup>

See Microsoft's documentation on Specifying Target Platform for more details.

Multi-Platform Build Strategies

If you need to support multiple platforms with DB2 or SQLite, you'll need to create separate builds for each platform. Here are recommended approaches:

Approach 1: Conditional Package References

Use MSBuild conditions to reference different packages based on the target runtime:

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net10.0</TargetFramework>
  </PropertyGroup>

  <ItemGroup Condition="'$(RuntimeIdentifier)' == 'win-x64'">
    <PackageReference Include="YndigoBlue.Velocity.Windows" Version="2025.1.0" />
  </ItemGroup>

  <ItemGroup Condition="'$(RuntimeIdentifier)' == 'linux-x64'">
    <PackageReference Include="YndigoBlue.Velocity.Linux" Version="2025.1.0" />
  </ItemGroup>

  <ItemGroup Condition="'$(RuntimeIdentifier)' == 'osx-arm64'">
    <PackageReference Include="YndigoBlue.Velocity.MacOS" Version="2025.1.0" />
  </ItemGroup>

  <ItemGroup Condition="'$(RuntimeIdentifier)' == 'linux-arm64'">
    <PackageReference Include="YndigoBlue.Velocity.RaspberryPi" Version="2025.1.0" />
  </ItemGroup>
</Project>

Approach 2: Separate Project Files

Create separate .csproj files for each platform:

  • MyApp.Windows.csproj
  • MyApp.Linux.csproj
  • MyApp.MacOS.csproj

Each references the appropriate Velocity package and shares the same source files using Compile Include.

Approach 3: MSBuild Choose Element

Use the Choose Element for more complex conditional logic:

<Choose>
  <When Condition="'$(OS)' == 'Windows_NT'">
    <ItemGroup>
      <PackageReference Include="YndigoBlue.Velocity.Windows" Version="2025.1.0" />
    </ItemGroup>
    <PropertyGroup>
      <PlatformTarget>x64</PlatformTarget>
    </PropertyGroup>
  </When>
  <When Condition="'$([System.Runtime.InteropServices.RuntimeInformation]::IsOSPlatform($([System.Runtime.InteropServices.OSPlatform]::Linux)))' == 'true'">
    <ItemGroup>
      <PackageReference Include="YndigoBlue.Velocity.Linux" Version="2025.1.0" />
    </ItemGroup>
    <PropertyGroup>
      <PlatformTarget>x64</PlatformTarget>
    </PropertyGroup>
  </When>
  <When Condition="'$([System.Runtime.InteropServices.RuntimeInformation]::IsOSPlatform($([System.Runtime.InteropServices.OSPlatform]::OSX)))' == 'true'">
    <ItemGroup>
      <PackageReference Include="YndigoBlue.Velocity.MacOS" Version="2025.1.0" />
    </ItemGroup>
    <PropertyGroup>
      <PlatformTarget>ARM64</PlatformTarget>
    </PropertyGroup>
  </When>
</Choose>

Building for Multiple Platforms

Use runtime identifiers (RIDs) when publishing:

# Windows
dotnet publish -r win-x64 -c Release

# Linux
dotnet publish -r linux-x64 -c Release

# macOS
dotnet publish -r osx-arm64 -c Release

# Raspberry Pi
dotnet publish -r linux-arm64 -c Release

Switching Between Packages

If you need to switch from the standard package to a platform-specific package (or vice versa):

  1. Uninstall the current package:

    dotnet remove package YndigoBlue.Velocity

  2. Install the new package:

    dotnet add package YndigoBlue.Velocity.Windows

  3. Update your project file to set the correct PlatformTarget

  4. Review your code for any database-specific APIs that may now be available (or unavailable)

  5. Test thoroughly to ensure all database operations work as expected