Forem: Natan Podbielski

Enhancing your .NET API with query language

Natan Podbielski — Thu, 06 Nov 2025 07:48:28 +0000

What is query language? SQL is Structured Query Language and you use it to query your database for data you are interested in. It does not have to do anything with your API. If you ever were working with big XML files you probably used XQuery or XPath, query languages designed to XML for data. There are specialized languages that are designed to work with APIs to query them for data. For example, you probably heard about GraphQL or even used it when you were working with some API.

Do you need one for you API?

If you try to use online marketplace search and enter “SPF”, for example, you will see a lot of sun creams in the result. But you are interested in transceivers for your new 100G switch instead. You will try limit search to category of “electronics” or “networking”. In the query string of the browser page you maybe will see something like:

"?_nkw=spf&_from=R40"
"k=spf&i=computers&crid=YIPWAZPBD3BT&sprefix=spf%2Ccomputers%2C87&ref=nb_sb_noss"
"networking-4413?string=spf"

This is very hard to decipher and not a problem if you are developing a website. Most users do not care about those strange signs in the browser address. But if you are developing an API, this does matter. Those “strange letters and numbers” is part of your product! Ease of use for every product is very important. Even if this is very technical product, for technically apt people.

I was working on commercial and non-commercial applications that were trying to reinvent API query language in some way. In example API or website had few query string parameters for filters (like “name” or “date” or “active=true”) then somewhere in application logic it would be translated into SQL query parameters:

dbContext.Persons.Where(p => p.Name.ToLower().Contains(name)).ToList()
eventsStorage.Events.Where(e => e.Date.Date == date).ToList();
ordersRepository.Find(o => o.Status.ToString().ToLower() == "active").ToArray();

Which is fine. But when project grows and consists of more parts and more modules, it is hard to keep things consistent and lack of consistency is a problem for users. They do not care if feature or microservice was developed two years ago and still is using ‘old approach ™’. Concise approach to search across your API is much more important.

You can do that using query language. GraphQL, as already mentioned is a possibility, but it also allows your users to create very complex, heavy and time-consuming queries. Personally, I find it very hard to use. There is also Dynamic Linq and I saw it being used in one project I worked for. But probably allowing your users to write dynamic code for your application to run is not the best idea. There are also libraries, like RQL.NET, but when you search for .NET query language you will get results connected to Linq mostly. This means that for .NET simplest solution would be to use Linq or something similar for API query language. This is the logical solution.

HLinq: Linq to HTTP

HLinq is single Nuget package that allows you to add query language capabilities into your API very easily. Syntax is also quite clear to understand, especially if you already used Linq before.

For example filtering is done with following syntax:

where[ x.name == John ]                                                            - search for people with name "John"
where[ x.name != John ]                                                            - search for people with name not being "John"
where[ x.id == 1 ]                                                                 - search for specific record by its Id
where[ x.id == 77774169-BB9D-4DF9-A4A7-52019C4A445D ]                              - the same as above but with GUID instead
where[ x.name == John Smith ]                                                      - name search but with space inside
where[ x.email == null ]                                                           - look for people that have no email set
where[ x.number == 1 ]                                                             - integral value search
where[ x.Number == 1.2323 ]                                                        - exact fractional number value search
where[ x.Number > 1.2322 && x.Number < 1.2324 ]                                    - look for range of numbers
where[ x.placed == 2025-10-05T19:43:07.3693705Z ]                                  - exact date time filter
where[ x.placed==2011-01-30 15:55:20.433+01:00 ]                                   - date time and zone filter
where[ x.dateOfBirth >= 2010-08-31 ]                                               - search records with date greater or equal than specified value
where[ x.name.EndsWith(s) || x.Name.StartsWith(d) ]                                - search with either one condition OR another condition
where[ x.status == active && x.count > 10 ]                                        - both conditions must be TRUE
where[ ( x.Id==1 || x.Name.StartsWith(d) ) && x.dateOfBith >= 2010-08-31 00:00 ) ] - search with AND and OR logical operators applied to conditions or group of conditions enclosed with '(' ')'
where[ x.name.contains(Han) ]                                                      - case-sensitive 'like' search
where[ x.name.contains(han, StringComparison.InvariantCultureIgnoreCase) ]         - case-insensitive search using memory-only collection search
where[ ilike(x.name, han) ]                                                        - case-insensitive search using DB specific function
where[x.name==John]                                                                - white space is optional
where[                                                                             - white space really does not matter!
  (
     p.name.contains(Kowalski)
     && p.name.startsWith(Jan)
  )
  ||
  p.dateOfBirth > 2010-01-01
]
where[ x.name=="John " ]                                                           - except for search parameters values
where[ x.Name.Contains(Jan) ]                                                      - casing of properties and methods does not matter

Also, very useful for users is ability to order records in a specific way:

orderBy[x.name]                                         - order by name in ascending order
orderByDescending[x.name]                               - the same but in reverse order
orderBy[x.age].thenBy[x.lastActive]                     - order by two properties, first by age, then by last activity date
orderBy[x.age].thenByDescending[x.lastActive]           - the same but most active users put on top
orderByDescending[x.age].thenByDescending[x.lastActive] - the same but oldest users first

It is possible to count number of records in your query:

count[]                              - count all records
where[x.date <= 2020-01-01].count[]  - count only records that satisfy condition

If you are building front end or some kind of client of your API, it is necessary to limit number of records returned or only fetch records from specific offset.

take[200]            - return only 200 records
skip[1000].take[200] - take only 200 records but from offset 1000

There is also possibility to transform response, to limit it to only specific properties that user is interested in.

select[ x.name ]                                       - return only one property
select[ x.name, x.age ]                                - return only two properties
select[ fullName = x.name, x.age ]                     - the same two properties but name will be renamed to "fullName"
select[ fullName = x.name, active=true ]               - you can add syntactic property to the response
where[ x.age > 22 ].select[ fullName = x.name ]        - get names of people that are older than specific age
select[ fullName = x.name ].where[ x.age > 22 ]        - but this will not work because age does not exist after applying "select[]" transformation

All of this is relatively easy to understand on the first glance. Or at least easier to grasp than something like that (RQL.NET):

var rqlExpression = {
  filter: {
    "isDone": 1,
    "$or":[
        {"updatedAt": {"$lt": "2020/01/02", "$gt":1577836800}},
      ],
  },
  limit : 1000,
  offset: 0,
  sort:["-updatedAt"],
}

Or json query of GraphQL:

{
  search(text: "an") {
    __typename
    ... on Human {
      name
    }
  }
}

Install HLinq

Using HLinq in your API is quite simple. Install Nuget package in your project:

<PackageReference Include="HamsterWheel.HLinq.AspNet" Version="0.4.0" />

After that add initialization of HLinq, in your Program.cs
file or similar place when you have access to instance of ServicesCollection:

services.ConfigureHLinq();

Then you need to add HLinqQuery<MyEntity>
model into your endpoint which is actual HLinq query mapped from HTTP Query String into type safe structure. MyEntity
type is important to be the actual type your API exposes to the clients.

app.MapGet("/endpoint",
    (DbContext dbContext, HLinqQuery<Superhero> query, CancellationToken cancellationToken) =>
    {
        var queryable = dbContext.MySet; 
        return query.ApplyTo(queryable, cancellationToken);
    });

If you are using Controllers instead of Minimal API you can do this instead:

[HttpGet("my-endpoint")]
public IActionResult GetData(HLinqQuery<MyEntity> query, CancellationToken cancellationToken) =>
    Ok(query.ApplyTo(dbContext.MySet, cancellationToken));

And that is it!

You can now call this endpoint with HLinq query filters, ordering, paging and selects! This will work with db collections and in memory collections or any other collections backed by IQueryable.

For example if you have endpoint that responds with the collection of persons serialized from following type:

public class Person
{
    public int Id { get; set; }
    public string FirstName { get; set; } = null!;
    public string LastName { get; set; } = null!;
    public string Email { get; set; } = null!;
    public string? IpAddress { get; set; }
}

If you add HLinq query model to that endpoint, apply it to a collection and return transformed collection to the client.

For example if you will call this endpoint without HLinq query at all, it will return everything all 1000 at most records if collection is bigger. This is a safety mechanism to prevent user from fetching your entire database in few requests (though it may be configured to be different value).

If you call it with:

?count[]

You will get a response that is just an integral value.

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Date: Thu, 30 Oct 2025 09:30:12 GMT
Server: Kestrel
Transfer-Encoding: chunked
2000

If you call it with:

?where[x.firstName.contains(tra)]

It will return all persons with first name containing ‘tra’.

[
  {
    "id": 546,
    "firstName": "Demetra",
    "lastName": "Kauffman",
    "email": "dkauffmanf5@wufoo.com",
    "ipAddress": "6.84.100.186"
  },
  {
    "id": 965,
    "firstName": "Anitra",
    "lastName": "MacGraith",
    "email": "amacgraithqs@mozilla.org",
    "ipAddress": "241.235.111.149"
  }
]

If you need wildcard search done on DB query side it can be done with DB function. I.e. For PgSql it is "?where[ilike(x.firstName,tra%)]"
but since character ‘%’ cannot be placed directly in HTTP url it have to be encoded as %25.

?where[ilike(x.firstName,tra%25)]

This is equivalent to doing EF query like below.

persons.Where(x => EF.Functions.ILike(x.FirstName, "tra%"));

And both will be translated directly to similar SQL:

SELECT p."Id", p."Email", p."FirstName", p."IpAddress", p."LastName"
FROM "Persons" AS p
WHERE p."FirstName" ILIKE 'tra%'
LIMIT @__p_0

And you will get response:

[
  {
    "id": 46,
    "firstName": "Travers",
    "lastName": "Carsberg",
    "email": "tcarsberg19@yandex.ru",
    "ipAddress": "156.239.72.190"
  },
  {
    "id": 1001,
    "firstName": "Tracey",
    "lastName": "Bellard",
    "email": "tbellardrs@wikipedia.org",
    "ipAddress": "145.78.92.113"
  }
]

If collection that your API is exposing to the client is not DB function, similar case-insensitive search can be done with the following query:

?where[x.name.contains(b, StringComparison.InvariantCultureIgnoreCase)]

This is similar to Linq query:

persons.Where(p => p.Name.Contains("b", StringComparison.InvariantCultureIgnoreCase))

Conclusion

HLinq does not offer all the capabilities of Linq, for example grouping for now is not supported (but it is on the roadmap!), but it is pretty powerful tool as it is now. It is also designed to be easily configurable and extensible, but I think the biggest upside is ease of use in already existing Asp.NET application.

Writing a simple C# source code generator with Fluent API

Natan Podbielski — Thu, 02 Oct 2025 14:33:53 +0000

Introduction

Usually in .NET world when you want to write generic code you use generic method or classes. But sometimes it is still not enough when you want to automate some things. I.e. you want to dynamically register in DI all the classes that implements some interface. Probably, in this case, you would do something like that:

var implementations = typeof(MyClass).Assembly.Types
   .Where(t => t.GetInterfaces().Any(i => i == typeof(IMyInterface))
foreach(var implementation in implementations)
{
   services.AddScoped<IMyInterface>(implementation);
}

And it would be completely fine. Even if Reflection is pretty slow, your application would not be getting significantly slower because of that. Certainly you would not notice the slow down.

For some other similar requirements some people used Fody or similar tool, that alters your assembly based on specified weavers. It works, though I always found if very confusing during debugging (because source code is no longer valid).

But we are not here to do the 'ok' job. We want better, more efficient code, that is generic but still close to native code. We strife for greatness!

Ok, maybe this is a bit too much, but following new .NET optimizations, we want to use new tools at our disposal to write simple but yet, efficient code.

We can do that by meta programming in C# and .NET using Roslyn Source Generators.

Source code generator

Writing your own source code generator is not that easy as it could be. Certainly it is a bit mode advanced topic and Microsoft is not putting as much money (and attention) into it as into new and groovy features that supposed to get you hook up into C#. But it should not stop you because it is also really cool seeing your source code generator generating new code on the fly, while you are making changes in your IDE. Seeing an error becoming valid code because code was generated in the background based on logic you coded is really great feeling!

In above video you can see my IDE, Rider, generating a code, class Hi with method Log generated on the fly based on new text file that is added to the project. First new Hi().Log() method call in the Program.cs is invalid, but when new txt file is added, source code generator generates new class, Program.cs becomes valid and when application is running, new line is written to the console. Pretty cool!

This may sound a bit complicated, and to some extent it is, but it probably won't be most complicated thing you did or will do.

Creating new project

As with many C# examples, also in this, you have to create a new project.

This new project to be valid source code generator, it have to target .NET Standard 2.0. It is pretty simple to do with dropdown selection in your IDE or you can just change .csproj file directly:

<TargetFramework>netstandard2.0</TargetFramework>

Then mark your project as Roslyn component. You need to add following properties to section in your project file:

<IsRoslynComponent>true</IsRoslynComponent>
<EnforceExtendedAnalyzerRules>true</EnforceExtendedAnalyzerRules>

After that install one package that helps you a bit with Roslyn APIs. For me personally they were a bit hard to understand when I first started working with them:

<PackageReference Include="HamsterWheel.FluentCodeGenerators" Version="0.4.0" PrivateAssets="all" />

You need to add also importing all of code generator Nuget packages to the output directory of your generator. Without it it will throw errors like below:

CSC : warning CS8784: Generator 'DemoIncrementalGenerator' failed to initialize. It will not contribute to the output and compilation errors may occur as a result. Exception was of type 'FileNotFoundException' with message 'Could not load file or assembly 'HamsterWheel.FluentCodeGenerators, Version=0.4.1.0, Culture=neutral, PublicKeyToken=null'. The system cannot find the file specified. [/builds/hamster-wheel/fluentcodegenerators/demo/HamsterWheel.FluentCodeGenerators.Demo.Use/HamsterWheel.FluentCodeGenerators.Demo.Use.csproj]

To fix that add following tags to your project file:

<Content Include="$(PKGHamsterWheel_FluentCodeGenerators)\lib\netstandard2.0\*.dll" Pack="true" PackagePath="analyzers/dotnet/cs" Visible="False" />
<Content Include="$(PKGHamsterWheel_FluentCodeGenerators_Abstractions)\lib\netstandard2.0\*.dll" Pack="true" PackagePath="analyzers/dotnet/cs" Visible="False" />

and also change the package reference tags:

<ItemGroup>
  <PackageReference Include="HamsterWheel.FluentCodeGenerators" Version="0.4.1" GeneratePathProperty="true" />
  <PackageReference Include="HamsterWheel.FluentCodeGenerators.Abstractions" Version="0.4.1" GeneratePathProperty="true" />
</ItemGroup>

This is enough to work on the Nuget package but if you want to develop your source code generator, it is much easier to have it in the same solution you want generate code for. To do this you need to do one additional change:

<PropertyGroup>
  <GetTargetPathDependsOn>$(GetTargetPathDependsOn);GetDependencyTargetPaths</GetTargetPathDependsOn>
</PropertyGroup>

<Target Name="GetDependencyTargetPaths">
  <ItemGroup>
     <TargetPathWithTargetPlatformMoniker Include="$(PKGHamsterWheel_FluentCodeGenerators_Abstractions)\lib\netstandard2.0\*.dll" IncludeRuntimeDependency="false"/>
     <TargetPathWithTargetPlatformMoniker Include="$(PKGHamsterWheel_FluentCodeGenerators)\lib\netstandard2.0\*.dll" IncludeRuntimeDependency="false"/>
  </ItemGroup>
</Target>

Above directives will make sure that all necessary packages, that are referenced by your source code generator project, are copied to appropriate directory from where your IDE and dotnet build are using your code generator .dll file. Without it it would be another FileNotFoundException during initialization.

After that your project should look similar too below:

<Project Sdk="Microsoft.NET.Sdk">

    <PropertyGroup>
        <TargetFramework>netstandard2.0</TargetFramework>
        <LangVersion>latestmajor</LangVersion>
        <ImplicitUsings>enable</ImplicitUsings>
        <Nullable>enable</Nullable>

        <EnforceExtendedAnalyzerRules>true</EnforceExtendedAnalyzerRules>
        <IsRoslynComponent>true</IsRoslynComponent>
        <CopyLocalLockFileAssemblies>true</CopyLocalLockFileAssemblies>
        <IsPackable>false</IsPackable>
    </PropertyGroup>

    <ItemGroup>
        <PackageReference Include="HamsterWheel.FluentCodeGenerators" Version="0.4.1" GeneratePathProperty="true" PrivateAssets="all" />
        <PackageReference Include="HamsterWheel.FluentCodeGenerators.Abstractions" Version="0.4.1" GeneratePathProperty="true" PrivateAssets="all" />
    </ItemGroup>

    <PropertyGroup>
        <GetTargetPathDependsOn>$(GetTargetPathDependsOn);GetDependencyTargetPaths</GetTargetPathDependsOn>
    </PropertyGroup>

    <Target Name="GetDependencyTargetPaths">
        <ItemGroup>
            <TargetPathWithTargetPlatformMoniker Include="$(PKGHamsterWheel_FluentCodeGenerators_Abstractions)\lib\netstandard2.0\*.dll" IncludeRuntimeDependency="false"/>
            <TargetPathWithTargetPlatformMoniker Include="$(PKGHamsterWheel_FluentCodeGenerators)\lib\netstandard2.0\*.dll" IncludeRuntimeDependency="false"/>
        </ItemGroup>
    </Target>

</Project>

Writing the generator

With project fully prepared we can jump to writing actual generator. First we need to add incremental generator class.

Lets start with following:

[Generator(LanguageNames.CSharp)]
public class DemoSolutionIncrementalGenerator : IIncrementalGenerator
{
    public void Initialize(IncrementalGeneratorInitializationContext context)
    {
    }
}

This is bare minimum code for incremental Roslyn source code generator. But as minimal starting point it does not do anything, so it is not quite useful. Yet.

Lets add following lines into Initializer method:

context.RegisterPostInitializationOutput(c =>
{
    c.AddSource("DummyFile.g.cs", """
                                  public class MyDummyGeneratedClassFile
                                  {
                                  }
                                  """);
});

This will instruct generator to emit single file called Dummy.g.cs with following content:

public class MyDummyGeneratedClassFile
{
}

This is just single, empty public class. Not very helpful, but as a starting demo is just fine.

This is good for very simple types that are to be added to the project before actual incremental generator is being used. In example if you coded you generator to enhance definition of user classes decorated by a specific attribute the flow would be:

Your generator package is installed
Incremental generator runs and RegisterPostInitializationOutput is executed.
This will add generated attribute to user project
User is coding new class using this attribute
Your incremental generator is looking at source code for this specific attribute
If any was found incremental source code generation is executed

This is how Regex code generators works with GeneratedRegex attribute.

Steps 5 and 6 require to use Roslyn API for obtaining IValueProvider. For example if we want to add new class for each of text files added to the project, like in demo above, we should add few line of code:

var additionalFilesProvider = context.AdditionalTextsProvider
            .Where(AdditionalTextPredicates.FileNameExtensionIs(".txt"))
            .Select(AdditionalTextSelectors.FileNamePathAndContent)
            .Collect();

This will instruct Roslyn to look for all the additional text files. Additional text is another type of file linked to the C# project via project directive. Then Roslyn is looking in that collection for files that ends with txt extension. Then selects name of the file and its content. After that it is collected into single collection and fed to your source code generator.

But this is just a provider. Actual implementation of the class that logs additional file content to the console will have the template like below:

public class {{ File Name }}
{
   public void Log()
   {
       Console.WriteLine("{{ file content }}");
   }
}

Above template can be generated within code generator:

context.RegisterSourceOutput(additionalFilesProvider,
    (pc, files) =>
    {
        foreach (var file in files)
        {
            pc.AddSource(Path.GetFileNameWithoutExtension(file.FileName), $$"""
                                                                          public class {{Path.GetFileNameWithoutExtension(file.FileName)}}
                                                                          {
                                                                              public void Log()
                                                                              {
                                                                                  Console.WriteLine({{file.Content.TripleQuote()}});
                                                                              }
                                                                          }
                                                                          """);
        }
    });

Lets brake it down into steps:

It iterates through every additional file
- for each one registers new generator output
- each output is named the same as additional file is named
- each output contains class that is named the same as additional file
- each class contains Log() method that push additional file content to the console

This is totally fine for simple classes and it will work for them. Things starts to brake down a bit:

when you have to share logic between different classes.
when you need to make sure all used types are imported with using statement
when you need to balance multiple levels of different parenthesis
when you need to make sure everything is properly indented
when you need to make sure parameter names match, all ; are added and all returns are in proper places

When it is true, you have giant spaghetti of strings, interpolated strings, imports and methods calls.

It is getting even more complicated, when you have few dozens of files connected to the one generator logic (in example Hamster Wheel Source Generator project contains over 300 files!). Then you have to take into account that different logic can run in different places in different generated classes. Taking care of just the idea of type you are generating without taking care of specific C# syntax it will be using is much easier to wrap your head around.

This is where HamsterWheel.FluentCodeGenerator library is coming in. It helps with all of that and more.

In example above generator code can be rewritten as:

context.WithClass(Path.GetFileNameWithoutExtension(file.FileName),
    c => c.WithMethod("Log",
            m => m.WithBody(b => b.Append($"Console.WriteLine({file.Content.TripleQuote()});")))
);

This generator will emit very similar code:

[GeneratedCode("HamsterWheel.FluentCodeGenerators", "Version=0.4.2.0")]
public class Hi
{
    public void Log()
    {
        Console.WriteLine("""
        Hi!
        """);
    }
}

It adds GeneratedCode attribute to each type it generates so other parts of the system knows it was automatically generated code. Also it have better indentation in triple quoted strings.

Maybe it does not seems to be much but this package have much more features. My favorite is automated usings management. I can count how many times during development of mine code generators I had an error when some type was not imported. This is something your rarely keep count of when writing production code yourself. Usually it is done automatically by your IDE - you just write few letters and choose correct type from drop-down of IDE hints, you IDE takes over the rest. When you do something similar inside FluentCodeGenerators fluent API, it does something very similar. In example following code:

var ipAddressType = typeof(IPAdress);
classContext.WithProp<Type>("MyType", p => p.MakeComputed().WithExpressionBody(b => b.Append($"typeof({ipAddressType})")))

Generator will automatically add appropriate namespace using statement:

using System.CodeDom.Compiler;
using System.Net; //<-- this namespace was added automatically

[GeneratedCode("HamsterWheel.FluentCodeGenerators", "Version=0.4.1.0")]
public class MyClass
{
    public Type MyType => typeof(IPAddress);
}

This is done by having InterpolatedStringHandler being used instead of regular string. This way you can handle specific chunks of it and act differently when chunk is actual type.

Summary

Writing your own C# source code generator may look quite complicated at the beginning, when you are trying to figure it out. APIs are not very friendly (at least to me). When you try to find relevant docs (code comments in those APIs basically are not existent), you find out that MSDN docs about Roslyn code generators are lacking a bit in the usual quality.

But when you actually get a hand of it and won't be scared by bugs in IDE or compiler pipeline - the end result is feels great! Especially with Fluent API.