Table of Contents

Getting Started

Prerequisites

Before installing Velocity, you'll need:

  • .NET 10 SDK or later (download here)
  • Either:
    • An YndigoBlue subscription with access credentials for the private NuGet feed (for full-featured versions)
    • OR: The free Community Edition from nuget.org (MySQL and PostgreSQL only, with feature limitations)
  • A supported IDE or text editor (Visual Studio, Visual Studio Code, or any editor for command-line development)

Obtaining Access

Community Edition (Free)

The YndigoBlue.Velocity.Community package is freely available on nuget.org without requiring a subscription. This edition provides core Velocity functionality with the following limitations:

Supported Databases:

  • MySQL
  • PostgreSQL

Feature Limitations:

  • ❌ No geospatial data types (Geometry/Geography) or spatial operations
  • ❌ No full-text indexes
  • ❌ No schema versioning or UpdateSchema() functionality
  • ❌ No support for multiple schemas within a database
  • ❌ No support for DB2, Oracle, SQL Server, SQLite, or Teradata

Installing the Community Edition:

dotnet add package YndigoBlue.Velocity.Community

The Community Edition is ideal for:

  • Learning Velocity and evaluating its capabilities
  • Small projects using MySQL or PostgreSQL
  • Applications with basic data access needs
  • Development and testing environments

Cross-Platform Package (Subscription or Partnership Required)

The cross-platform package is distributed either through a private YndigoBlue NuGet feed or downloaded from the YndigoBlue website if you have an active partnership here.

To access this package, you must first subscribe and obtain your credentials or apply for a partnership.

This version includes support for five databases, geospatial operations, full-text indexing, schema versioning, and multi-schema support.

Platform-Specific Packages (Subscription Required)

The platform specific packages are distributed through a private YndigoBlue NuGet feed only. To access these packages, you must first subscribe and obtain your credentials.

This version includes support for all seven databases, geospatial operations, full-text indexing, schema versioning, and multi-schema support.

Configuring the NuGet Feed (with YndigoBlue subscription)

Note: Packages from this feed are repository-signed. Configuring your environment to trust that signature is optional and covered separately below, see Trusting the Repository Signature.

Once you have your credentials, you'll need to configure your development environment to access the YndigoBlue NuGet feed at:

https://www.yndigoblue.com/nuget/v3/index.json

Choose the setup method that matches your development environment:

Visual Studio

  1. Open Visual Studio
  2. Go to Tools > NuGet Package Manager > Package Manager Settings
  3. Navigate to NuGet Package Manager > Sources
  4. Click the + Add button to add a new source
  5. Set the following values:
    • Name: YndigoBlue
    • Source: https://www.yndigoblue.com/nuget/v3/index.json
  6. Click Save
  7. Go to Tools > NuGet Package Manager > Manage NuGet Packages for Solution...
  8. Select YndigoBlue from the package source dropdown
  9. When prompted, enter your username and password provided by YndigoBlue, check Remember Password.

Installing Velocity in a project:

  1. Right-click on your project in Solution Explorer
  2. Select Manage NuGet Packages
  3. Select YndigoBlue from the package source dropdown
  4. Search for YndigoBlue.Velocity (or a platform-specific variant)
  5. Click Install

Visual Studio Code

Visual Studio Code uses the .NET CLI for NuGet operations. Follow the command-line setup below, then use the terminal in VS Code to manage packages.

For a better experience, install the NuGet Package Manager extension:

  1. Open VS Code
  2. Go to Extensions Ctrl+Shift+X (Cmd+Shift+X on macOS)
  3. Search for "NuGet Package Manager"
  4. Install the extension by jmrog

After configuring the NuGet source via command line (see below), you can:

  • Press Ctrl+Shift+P (Cmd+Shift+P on macOS)
  • Type "NuGet: Add Package"
  • Search for and install YndigoBlue.Velocity

Command Line (.NET CLI)

Add the NuGet source:

dotnet nuget add source https://www.yndigoblue.com/nuget/v3/index.json \
  --name YndigoBlue \
  --username YOUR_USERNAME \
  --password YOUR_PASSWORD \
  --store-password-in-clear-text

Security Note: The --store-password-in-clear-text flag stores credentials in plain text. For better security, consider using --configfile to specify a user-specific NuGet.config file with appropriate permissions, or omit the password flag to be prompted interactively.

Alternative: Interactive authentication:

dotnet nuget add source https://www.yndigoblue.com/nuget/v3/index.json \
  --name YndigoBlue \
  --username YOUR_USERNAME

You'll be prompted for the password when accessing packages.

Installing Velocity in a project:

Navigate to your project directory and run:

dotnet add package YndigoBlue.Velocity

Or to specify a particular version:

dotnet add package YndigoBlue.Velocity --version 2026.5.1

For platform-specific packages with DB2 and SQLite support, use:

dotnet add package YndigoBlue.Velocity.Windows
dotnet add package YndigoBlue.Velocity.Linux
dotnet add package YndigoBlue.Velocity.MacOS
dotnet add package YndigoBlue.Velocity.RaspberryPi

Verifying the installation:

dotnet list package

You should see Velocity listed in your project dependencies.

Trusting the Repository Signature

Every package pushed to the YndigoBlue NuGet feed is automatically signed with the feed's own certificate on upload. Restore and build work exactly the same whether or not you configure anything below — without it, you'll simply see a NU3018 warning ("signing certificate is not trusted") on YndigoBlue packages. It's a warning only; nothing fails or breaks, and package content is still checked for tampering either way (NU3008 fires unconditionally, regardless of any trust configuration — a modified package is always rejected).

If you want NuGet to actually recognize our certificate as trusted rather than just warn about it, add the following to a NuGet.Config file at your solution or repository root:

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <trustedSigners>
    <repository name="YndigoBlue" serviceIndex="https://www.yndigoblue.com/nuget/v3/index.json">
      <certificate fingerprint="5EFA184B3DF9A195D16F3C1223ED336DF38D65FEE43DDFFFE3AB045C16B9F887" hashAlgorithm="SHA256" allowUntrustedRoot="true" />
    </repository>
    <repository name="nuget.org" serviceIndex="https://api.nuget.org/v3/index.json">
      <certificate fingerprint="0E5F38F57DC1BCC806D8494F4F90FBCEDD988B46760709CBEEC6F4219AA6157D" hashAlgorithm="SHA256" allowUntrustedRoot="false" />
      <certificate fingerprint="5A2901D6ADA3D18260B9C6DFE2133C95D74B9EEF6AE0E5DC334C8454D1477DF4" hashAlgorithm="SHA256" allowUntrustedRoot="false" />
      <certificate fingerprint="1F4B311D9ACC115C8DC8018B5A49E00FCE6DA8E2855F9F014CA6F34570BC482D" hashAlgorithm="SHA256" allowUntrustedRoot="false" />
    </repository>
  </trustedSigners>
</configuration>
Important

The nuget.org block is required, not optional decoration — omitting it will break your build. The moment a <trustedSigners> section contains any entry, NuGet stops silently accepting signed packages from every other source too, including nuget.org. Without nuget.org's own certificates listed here, any nuget.org package in your dependency tree (which, transitively, is most of them) starts failing to restore with NU3034: This package is signed but not by a trusted signer. We looked hard for a way to trust only our certificate without this side effect — including consulting NuGet's own design documentation for the feature — and confirmed it does not exist: NuGet's trustedSigners mechanism has no per-source scoping, an open, unresolved gap the NuGet team's own spec acknowledges. This is the minimum config that actually works.

nuget.org's certificate is listed three times because it has rotated over the years; older packages in your dependency tree may be signed with an older generation of it than the newest. Do not add an <owners> restriction to the nuget.org entry — Microsoft's own official example config includes one (microsoft;aspnet;nuget), but that silently breaks restoring any nuget.org package not published by one of those three accounts, e.g. Newtonsoft.Json — confirmed directly.

If you don't want to touch nuget.org configuration at all

If adding nuget.org's certificates to your config isn't something you want to take on, you can suppress just the warning on YndigoBlue packages specifically, without any NuGet.Config changes and without mentioning nuget.org anywhere:

<PackageReference Include="YndigoBlue.Velocity" Version="2026.8.1" NoWarn="NU3018" />

Be clear about what this does and doesn't do: it only silences the warning message on that package reference. It does not grant NuGet any actual trust, and it has no effect on tamper detection (NU3008 still fires unconditionally either way, with or without this). It's cosmetic — a way to stop seeing a message you've decided to ignore, not a verification mechanism. If you want NuGet to actively recognize our certificate, use the block above instead.

Once you have both nuget.org and YndigoBlue configured as NuGet sources, it's best practice to set up package source mapping so each source is only consulted for the packages it actually provides. Without it, NuGet queries every configured source for every package your project references — including packages a given source will never have — which adds unnecessary round trips to every restore.

Add a NuGet.Config file at your solution or repository root with the following:

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <packageSourceMapping>
    <packageSource key="nuget.org">
      <package pattern="*" />
    </packageSource>
    <packageSource key="YndigoBlue">
      <package pattern="YndigoBlue.*" />
    </packageSource>
  </packageSourceMapping>
</configuration>

This resolves any package ID starting with YndigoBlue. exclusively from the YndigoBlue feed, and everything else from nuget.org.

Note: The key values (nuget.org, YndigoBlue) must exactly match the names you used when adding each source — see Configuring the NuGet Feed above.

Visual Studio

Visual Studio also provides a graphical editor for package source mapping:

  1. Go to Tools > NuGet Package Manager > Package Manager Settings
  2. Navigate to NuGet Package Manager > Package Source Mapping
  3. Click Add and map the YndigoBlue.* pattern to the YndigoBlue source
  4. Map * to nuget.org, or use the Generate Mappings button to create mappings automatically based on your currently installed packages

See Microsoft's package source mapping documentation for further details.

Troubleshooting

Cannot authenticate to NuGet feed:

  • Verify your credentials are correct
  • Ensure your subscription is active
  • Check that the NuGet source URL is exactly: https://www.yndigoblue.com/nuget/v3/index.json

Package not found:

  • Confirm the YndigoBlue source is listed: dotnet nuget list source
  • Try clearing the NuGet cache: dotnet nuget locals all --clear
  • Verify you're searching in the YndigoBlue source, not just nuget.org

Platform-specific errors:

  • Ensure you're using the correct platform package for your target OS
  • Verify .NET 10 SDK is installed: dotnet --version