Hl7.Cql.CodeGeneration.NET 2.6.0

Introduction

This is NCQA's and Firely's official support SDK for working with CQL on the Microsoft .NET (dotnet) platform. It contains an engine for executing ELM, and/or turning the contents of an ELM file into a .NET assembly so it can be called statically.

The engine has been tested by running it against the current NCQA HEDIS measures and CMS measures. There is quite some variation in how CQL is written and interpreted, so it is likely at this early stage that there will be deviations from other engines currently available.

Target Frameworks

The SDK targets .NET 8 (LTS) and .NET 10 (LTS) to provide optimal performance from .NET 10's enhancements (especially in LINQ which CQL heavily relies upon) while maintaining long-term support. All SDK packages (Hl7.Cql.*) are multi-targeted and will run on either framework with identical behavior.

Release Notes

This is release version 2.6.0 of the engine.

The release notes at firely-cql-sdk/releases for each major version document changes and known issues.

1.x releases are maintained with hotfixes only and do not receive new features.

Getting Started

• Read the Getting Started guide included in the repository.
• Explore the Examples for runnable code samples covering packaging and invocation.
• There is a great presentation on the engine from DevDays 2023.
• The CQL section in the Firely .NET SDK documentation.
• The CQL Engine Architecture document with background on the design.
• The Toolkit Services Dependency Diagrams showing the internal dependencies of the CQL SDK toolkit services.
• The Technical README for maintainers contains implementation details, conditional compilation, and multi-targeting information.
• The Demo Projects and CQL Build Pipeline guide covering the build scripts, Java CQL-to-ELM tooling, and PackagerCLI MSBuild targets used by the Demo projects.

Quick Start: Invoking CQL

The recommended way to execute CQL from .NET is through the Invocation Toolkit (Hl7.Cql.Invocation). It handles compiling CQL through ELM to .NET assemblies and exposes a clean API for invoking definitions. Never call generated library classes directly — doing so bypasses caching, version checking, and context management.

using Hl7.Cql.CqlToElm.Toolkit;
using Hl7.Cql.CqlToElm.Toolkit.Extensions;
using Hl7.Cql.Fhir;
using Hl7.Cql.Invocation.Toolkit.Extensions;
using Microsoft.Extensions.Logging;

var loggerFactory = LoggerFactory.Create(builder => builder.AddConsole());

// Define inline CQL (or load from files/FHIR resources)
var cql = (CqlLibraryString)"""
    library HelloWorldLib version '1.0.0'
    define "HelloWorld" : 'Hello from CQL!'
    """;

// Compile and create an invoker
using var invoker = new CqlToolkit(loggerFactory)
    .AddCqlLibraries(cql)
    .CreateLibrarySetInvoker();

// Execute a CQL definition
var context = FhirCqlContext.WithDataSource();
var result = invoker.InvokeLibraryDefinition(context, cql.LibraryIdentifier, "HelloWorld");
Console.WriteLine(result); // Hello from CQL!

See the Examples project for more complete samples including parameters, function arguments, FHIR resource loading, and caching.

SDK Packages

This SDK consists of the following packages:

Core Packages

• Hl7.Cql: The main package providing complete CQL engine functionality
• Hl7.Cql.Abstractions: Core interfaces and abstractions used throughout the SDK
• Hl7.Cql.Runtime: Runtime execution engine for CQL expressions
• Hl7.Cql.Compiler: ELM to .NET compilation
• Hl7.Cql.Invocation: High-level APIs for invoking CQL libraries and expressions. This is the recommended entry point for applications that need to execute CQL — it manages assembly loading, version checking, context lifecycle, and result enumeration. Always use this package instead of calling generated library classes directly.

Integration & Data Packages

• Hl7.Cql.Firely: FHIR integration layer
• Hl7.Cql.Model: Model definitions and metadata
• Hl7.Cql.Packaging: CQL packaging functionality

Conversion & Code Generation

• Hl7.Cql.CqlToElm: CQL to ELM conversion (early development, not production-ready)
• CodeGeneration.NET: .NET code generation utilities
• Elm: ELM abstractions and utilities

Support Packages

• Hl7.Cql.Grammar: CQL grammar definitions using ANTLR4
• Iso8601: ISO 8601 date/time handling

Tools

• PackagerCLI (cql-package): Command-line tool for packaging CQL/ELM into FHIR resources and .NET assemblies

External Dependencies

The SDK depends on the following key external packages:

FHIR Support

• Hl7.Fhir.Base: Version 6.1.0 - Base classes and utilities for FHIR support
• Hl7.Fhir.R4: Version 6.1.0 - FHIR R4 POCOs and serialization support
• Fhir.Metrics: Version 1.3.0 - FHIR units and metrics support

Parsing & Compilation

• Antlr4.Runtime.Standard: Version 4.13.1 - ANTLR4 runtime for CQL grammar parsing
• Microsoft.CodeAnalysis.CSharp: Version 4.12.0 - Roslyn C# compiler APIs

Configuration & Logging

• Microsoft.Extensions.Configuration: Version 10.0.3 - Configuration framework
• Microsoft.Extensions.DependencyInjection: Version 10.0.3 - Dependency injection container
• Microsoft.Extensions.Logging: Version 10.0.3 - Logging abstractions
• Microsoft.Extensions.Hosting: Version 10.0.3 - Generic host for .NET applications

Command-line Tool Dependencies

• Serilog.Extensions.Logging: Version 9.0.1 - Serilog integration with Microsoft.Extensions.Logging
• Serilog.Sinks.File: Version 7.0.0 - Serilog file logging sink
• System.CommandLine: Version 2.0.0-beta4.22272.1 - Command-line argument parsing

Pre-release NuGet Packages

During development, pre-releases will appear on Firely's GitHub Package feed. To use these packages you must add https://nuget.pkg.github.com/FirelyTeam/index.json to your NuGet sources:

• Get a Personal Access token (PAT) from github.com with scope read:packages

• Next open a console on your machine and run dotnet nuget add source --name github --username <USERNAME> --password <PAT> https://nuget.pkg.github.com/FirelyTeam/index.json

USERNAME: your username on GitHub PAT: your Personal access token with at least the scope read:packages

Further information can be found in docs/getting-started.md.

Testing

Multi-Framework Testing

The SDK includes comprehensive tools for testing against both .NET 8 and .NET 10 to verify identical behavior across both LTS frameworks.

Test Categories:

• Multi-Target Tests: CoreTests and CqlToElmTests run on both .NET 8 and .NET 10
• .NET 10 Only: IntegrationRunner and Test.Measures.Demo run only on .NET 10
• Excluded: XsdToCSharpConverterTests

Local Testing Scripts:

# Windows - Test all multi-target projects against both frameworks
.\test-multiframework.ps1

# Windows - Test specific project against both frameworks
.\test-multiframework.ps1 -TestProject CoreTests

# Linux/macOS - Test all multi-target projects against both frameworks
./test-multiframework.sh

# Linux/macOS - Test specific project against both frameworks
./test-multiframework.sh CoreTests

CI/CD Testing: Multi-framework testing is fully integrated into the Azure Pipelines CI/CD workflow. The multiFrameworkTests stage runs after the main build and tests in parallel:

• Job 1: Tests CoreTests and CqlToElmTests on .NET 8
• Job 2: Tests CoreTests, CqlToElmTests, IntegrationRunner, and Test.Measures.Demo on .NET 10
• Job 3: Compares results and reports any framework-specific differences

See build/README.md for complete CI/CD testing documentation and configuration details.

Support

We actively monitor the issues coming in through the GitHub repository at https://github.com/FirelyTeam/firely-cql-sdk/issues. You are welcome to register your bugs and feature suggestions there. For questions and broader discussions, we use the .NET FHIR Implementers chat and CQL chat on Zulip.

Contributing

We are welcoming contributions!

If you want to participate in this project, we're using Git Flow for our branch management. Please submit PRs with changes against the develop branch.

Current 2.x development is done against the develop branch, while hotfixes are done under the support/1.x branch. Please refer to our Git Branching and Workflow Guidelines on the wiki for detailed guidelines on git branching and naming conventions.