DEV Community: Stanislav Silin

You Don't Need a CLAUDE.md

Stanislav Silin — Tue, 20 Jan 2026 12:17:23 +0000

In this article, I want to discuss how to better use LLM agents, specifically how to manage the CLAUDE.md/AGENTS.MD file effectively and it seems like there is no point it in.

Before we start

This article will not cover the standard prompt engineering techniques that have been described many times by Anthropic and other LLM providers. You won't find advice here like "avoid negative examples," "set the LLM role," "be specific in your instructions," or similar well-documented practices. If you need that foundation, check the official documentation from Anthropic or OpenAI—they cover it thoroughly.

Instead, this article focuses on how my workflow evolved through months of using Claude Code on real projects. It's about the practical patterns I discovered for organizing documentation and keeping the LLM effective as projects grow in complexity.

One more clarification: I'm not a "vibe coder." I don't create tasks that let the LLM run autonomously for hours or days. I use the LLM "as a keyboard"—it can read superfast, type superfast, and execute actions to verify what it did. But I'm always in control. If something is too abstract or unclear, I simply won't let it proceed. This hands-on approach is the foundation of everything I describe below.

The problem with growing CLAUDE.md files

Every project should have a CLAUDE.md file. It describes what the project does, how to navigate around it, what development workflows are available, and so on. However, the more you work on a project, the more content accumulates inside this file. At some point, you will end up in a situation where Claude Code cannot read it because it's too large. It can still try to read the first half, then the second half, but you should not allow this to happen at all.

Keep CLAUDE.md "useless"

Here is the catch: your CLAUDE.md should be only around 30 lines maximum. I am not kidding—you don't need more.

The idea is simple. Instead of putting all the documentation into CLAUDE.md, use it as an entry point that defines the workflow. The LLM then decides which docs to read depending on the task at hand.

Here is mine for example:

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

# YOUR ROLE

You are dick! You know it. I know it. Don't pretend you are not.
Pay attention to task and code. If you see stupid thing/idea stop and report it.
Be extremely concise. Sacrifice grammar for the sake of concision.

# THE MAIN FLOW

Create the following to-do list immediately.

- Analyze user request.
- Run `find docs/ -name "*.md" | sort` to see available docs.
- Read docs that may help to solve current task.
- Read tsconfig.app.json to understand what path shortcuts exists.
- Read packages.json to understand commands.
- Analyze examples from the docs.
- Revise execution plan and present it to the user with todo items.
- Once the user accepts, create revised todo items.
- Start work on the task.
- Use skills and commands that may help to solve current task.

DO NOT EDIT THIS FILE
IT IS THE FINAL FORM.

Organizing documentation in the docs folder

This approach implies that everything useful—every guideline, workflow, and explanation—lives inside the docs folder. Organize them logically into different folders with descriptive names so the LLM can understand why it would need to read them.

This structure really helps once the project becomes big and you have different layers and features. Depending on the task, you may need specific knowledge, but most of it won't be required for every task.

For example, here is how the docs structure looks in one of my projects:

docs/backend/graphql-api-patterns.md
docs/backend/rest-api-patterns.md
docs/backend/service-layer.md
docs/backend/data-layer.md
docs/backend/event-system.md
docs/frontend/actions/create-component.md
docs/frontend/actions/create-modal.md
docs/frontend/actions/create-data-form.md
docs/frontend/actions/create-entity-selection.md
docs/frontend/actions/create-graphql-service.md
docs/frontend/actions/create-rest-service.md
docs/frontend/actions/create-route.md
docs/frontend/actions/create-tree-view.md
docs/frontend/architecture.md
docs/frontend/design-tokens.md
docs/frontend/ui-ux.md

docs/build-deployment.md
docs/currency-system.md
docs/documentation.md
docs/error-handling.md
docs/localization.md
docs/security.md
docs/testing.md

As you can see, some documents are global and expand on high-level concepts, while others are targeted at performing specific actions.

Reducing context size while keeping the knowledge

The key benefit of this structure is that it dramatically reduces context size while keeping all the knowledge accessible. When the LLM runs the find command, it only sees file names—a few dozen lines at most. Based on those names alone, it decides which documents are relevant to the current task and reads only those.

You can create as many documentation files as you need without worrying about context limits. The LLM will never load everything at once. For example, if you're working on a front-end task, it will never read about how your data layer, event system, or GraphQL API patterns are designed. You simply don't need that information for the task at hand.

This approach gives you the best of both worlds: comprehensive documentation for your project and minimal context usage per task.

Managing documentation with LLM

Once you have lots of documents, you need a way to properly manage them. My recommendation is to use the LLM itself for this purpose.

Here is the workflow I use. While working on a task, I continuously monitor what the LLM does and try to catch errors it makes. I note how these errors were fixed and continue with the task. Once the task is complete and I'm ready to clean up the context, I run a /refine command.

Think about what we learned during the session. Focus on session memory analysis and minimal file reading to avoid LLM context window overflow. read the documentation, and refine things that you have learned during this session.

Create a todo list to track the refining process:

- Run `find docs/ -name "*.md" | sort` to see available docs.
- Read documentation on how to write documentation.
- Create todo items for new knowledge and guidelines we discovered

This command tells the LLM to reflect on what happened during the session: what kind of errors occurred, how they were overcome, and whether there is something beneficial to add to the documentation so these errors can be avoided in the future.

There is one prerequisite: you need a markdown file that describes how to write documentation for your project. With this in place, the LLM will think about the session, find an appropriate place inside existing documentation—or create a new document if needed—and elaborate on how to avoid the issue in the future.

This way, your documentation evolves organically based on real problems encountered during development. Every session becomes an opportunity to improve the knowledge base.

Action documents for consistent execution

This approach works not only for fixing errors—it works for any case when you create a new system or discover an important action that you want to ensure is done correctly and consistently.

If you look at my example docs folder, you'll notice a bunch of action documents for the frontend: create-modal.md, create-component.md, create-service.md, and so on. These documents define a strict structure of what to do when performing a specific task. They help eliminate the randomness of the LLM to some degree. This is especially useful when the action involves executing CLI commands or following a specific sequence of steps that must be done in a particular way.

Workflow techniques

The following techniques are not directly related to CLAUDE.md, but they significantly improve how you work with Claude Code.

Meta prompting

Instead of asking the LLM to perform a task directly, ask it to investigate the project, read the documentation, find problems in your prompt, and extend it to cover all the cases that were unclear.

This approach helps from two sides. First, you can start with a pretty simple prompt. Then, as you discuss it with the LLM, you can add more requirements, remove some, and adjust the scope—essentially having a conversation about what you plan to do. The LLM might point out edge cases you haven't considered or ask clarifying questions about ambiguous parts.

Second, once you're done refining, you have a well-defined prompt. At this point, you clean up the context and start a fresh session with this polished prompt. The LLM begins with a clear, comprehensive understanding of what needs to be done. Most of the time, you can be confident it will do exactly what you want because the context is well-defined from the start, not built up through a messy back-and-forth.

Don't be afraid to throw out the code

This might feel counterintuitive, but it's important: don't be afraid to discard what the LLM has created and start over.

Here's the scenario. You have a well-defined prompt, the LLM works on it, and it creates a structure based on your description. But then you see it's not exactly what you want. You know the changes could be made, but they would require a lot of back-and-forth, many adjustments, and the context would become cluttered with corrections and clarifications.

Instead of pushing through, just stop. Go back to your prompt, explain what was wrong with the result, add more information about what you actually need, clean up the context, and start from scratch.

With this additional information, the LLM may ask you clarifying questions about edge cases you missed. It might suggest a better approach or provide examples that help you refine your requirements further. The second attempt, armed with the lessons from the first, will almost always be closer to what you actually want—and it will be built on a clean foundation rather than a patchwork of fixes.

Don't be afraid to do it twice

Here's another technique I use often: don't be afraid to repeat an action.

For example, after the first iteration of meta-prompting, you have a nice, well-defined prompt. But what's stopping you from running meta-prompting on that meta-prompt? If everything is already fine, it will be super fast—the LLM will just confirm the prompt is solid. But sometimes, with a fresh context and a fresh look at the codebase, the LLM notices something that wasn't caught the first time.

This applies not only to meta-prompting. You can do the same with implementation: create two implementations and compare them against each other. Given how fast Claude Code types and executes, this is surprisingly easy to do when you have a well-defined prompt. The cost of a second attempt is low, and the potential benefit of catching issues or discovering a better approach is high.

You can also do partial implementations. For example, create a complete UI, but with all database queries and API calls done in memory with mock data. This way, you can quickly try multiple approaches to see which one feels right. Once you're satisfied with the result, you simply ask to replace the mocks with real API calls. This lets you iterate on the hard parts—the structure, the flow, the user experience—without getting bogged down in integration details too early.

Before Claude Code, this approach would be tedious—implement once, verify it works, test it, then repeat. With Claude Code, it's 15 minutes for UI with mock data and another 15 minutes for the database integration. Yes, you do additional work testing it multiple times, but finishing the job in an hour with the predictability you wanted is a much better result. I think it's worth it.

Conclusion

The key takeaway from this article is simple: keep your CLAUDE.md minimal and use it as an entry point, not a knowledge dump. Move everything else into a well-organized docs folder where the LLM can selectively read what it needs. This approach scales with your project—you can have dozens of documentation files without ever hitting context limits.

Use the LLM itself to maintain and evolve your documentation. Every session where you catch and fix an error is an opportunity to improve the knowledge base for future sessions. Create action documents for repetitive tasks to eliminate randomness and ensure consistency.

Finally, embrace the speed that Claude Code gives you. Use meta-prompting to refine your requirements before implementation. Don't be afraid to throw out code and start fresh. Run things twice. Build partial implementations with mocks to iterate quickly. The cost of repetition is low, and the benefit of getting exactly what you want is high.

These patterns transformed how I work with Claude Code. I hope they help you too.

Improve LLM Debugging

Stanislav Silin — Fri, 29 Aug 2025 19:05:30 +0000

Recently, I have been working extensively with LLM-powered coding assistants - Claude Code, Cursor, Windsurf - and I noticed a frustrating pattern. Every time these tools run a command for me, they're processing massive amounts of irrelevant log output. You know how it goes - the LLM runs npm run build for your React app and receives screens full of webpack configs, browserslist warnings, and compilation progress when all it really needs are those few error lines to help you debug.

But what if we could change that? What if there was a way to make every command output exactly what the LLM needs to see?

The Token Problem

Let's have a look at what I mean. Here's what happens when your LLM assistant runs a typical React build:

> npm run build:graphql && react-router typegen && tsc && react-router build


> build:graphql
> graphql-codegen

✔ Parse Configuration
✔ Generate outputs
app/features/tasks/services/atoms.ts:55:60 - error TS2339: Property 'taskId' does not exist on type '{ request: UpdateTaskRequest; }'.

55         const response = await apiClient.updateTask(params.taskId, params.request);
                                                              ~~~~~~


Found 1 error in app/features/tasks/services/atoms.ts:55

That's about 10+ lines of output when the only valuable information for debugging is 1 error line. Does this look familiar? And here's the thing - this problem exists for basically every technology stack:

Python/Django: Pages of pip install progress bars and dependency resolution before showing the actual ImportError
.NET: MSBuild verbosity drowning out the actual CS compiler errors
Java/Spring: Maven downloading half the internet before showing your NullPointerException
Docker: Layer caching information obscuring the actual build failure
Rust: Cargo's detailed compilation progress hiding the borrow checker errors

When your LLM assistant is helping you debug multiple build issues, running tests, and checking git status, it's processing thousands of unnecessary tokens. Whether you're using Claude Code, Cursor, or any other LLM-based coding tool, those tokens add up quickly - both in terms of API costs and response time.

The Half-Solution That Doesn't Work

Now, you might think: "Why not just ask the LLM to use grep or findstr to filter the output?" As for me, I tried that too. You can tell your LLM something like:

"Run npm run build but pipe it through grep to only show errors"

And sometimes you'll get:

npm run build 2>&1 | grep -E "error|Error|ERROR"

But here's the thing - it's an LLM. Sometimes it forgets to add the filter. Sometimes it uses the wrong regex pattern. Sometimes it tries to be helpful and shows you the "full context" anyway. And when you're deep in a debugging session at 2 AM, the last thing you want is to repeatedly remind an LLM to filter output or correct its regex patterns.

Plus, different tools need different patterns. React errors look different from Python tracebacks, which look different from Rust compiler errors. You'd need to remember (or teach the LLM) dozens of different grep patterns for different scenarios.

Building a Real Solution

That's when I thought: what if I build a simple tool that does exactly what we need? No more hoping the LLM remembers to filter. No more copying the wrong grep pattern. Just a tool that knows how to extract errors from any build output.

After dealing with this problem for weeks, I decided to build that tool once and for all. The idea is simple: create a CLI that can execute commands but only show the output that matters.

Meet Apparatus.Exec - a command executor designed specifically for LLM-driven development workflows.

Get Started

Let's jump right in and see how this works.

First, install the tool globally:

npm install -g @apparatus-technology/exec

Now you have access to the aex command. Let's initialize it in your project:

aex init

This creates an exec.config.yml file with predefined shortcuts and filters. Now let's see the magic happen when you run your commands through aex:

$ aex frontend-build
app/features/tasks/services/atoms.ts(55,60): error TS2339: Property 'taskId' does not exist on type '{ request: UpdateTaskRequest; }'.

Done

Done! Just the error. No fluff, no timestamps, no progress bars. When the LLM reads this, it's processing 90% fewer tokens while getting 100% of the useful information.

How to use

The tool operates on two simple concepts: shortcuts and filters. Let's have a look at each one.

Shortcuts

Instead of typing long command sequences repeatedly, you define them once in your config:

shortcuts:
  frontend-build:
    commands:
      - npm ci
      - npm run build
    description: Clean install and build React application
    working-dir: ./frontend

  test-all:
    commands:
      - npm test -- --coverage
      - npm run e2e
    description: Run unit and e2e tests

Now aex frontend-build executes both commands in sequence. But the real trick is in the filters.

Filters

The real power comes from regex filters that extract only relevant output:

filters:
  - name: React Build Errors
    pattern: src/.*\.(tsx?|jsx?):\d+:\d+:.*
    description: ESLint and TypeScript errors with file paths and line numbers

  - name: Test Failures
    pattern: (?i)failed|error|exception|FAIL
    description: Test failures and exceptions

  - name: Module Errors
    pattern: Cannot find module|Module not found
    description: Missing dependencies and import errors

When you run a shortcut, the output passes through these filters. Only lines matching your patterns make it through. Everything else gets discarded.

Real-World Example

Now let's see this in action. I was recently using Claude Code to debug a React component where tests were failing due to a missing import. Here's how the interaction looked:

$ aex test-frontend
FAIL src/components/UserProfile.test.tsx
  ● Test suite failed to run
    Cannot find module '@/hooks/useAuth' from 'src/components/UserProfile.tsx'
Done

$ aex git-status
M  src/components/UserProfile.tsx
M  src/hooks/useAuth.ts
?? src/hooks/useAuth.test.ts
Done

Claude Code immediately saw: "The tests are failing because the useAuth hook can't be found. You've modified UserProfile.tsx and created useAuth.ts but it's not being resolved." The LLM instantly understood the issue and suggested checking my TypeScript path mappings in tsconfig.json.

Without filtering, the LLM would have received hundreds of lines of test runner initialization, webpack bundling messages, and git's verbose status output. The conversation would have been slower, more expensive, and harder to follow.

Advanced Features

As I used the tool more, I kept adding features that made my workflow smoother.

Working Directories

Each shortcut can specify where it should run:

shortcuts:
  frontend-build:
    commands:
      - npm ci
      - npm run build
    working-dir: ./client

  backend-build:
    commands:
      - pip install -r requirements.txt
      - python manage.py runserver
    working-dir: ./server

  mobile-build:
    commands:
      - flutter pub get
      - flutter build apk
    working-dir: ./mobile

No more cding around or forgetting which directory you're in. This is especially useful in monorepos where you have multiple technologies in different folders.

Pattern Templates

When you run aex init, you can choose from predefined pattern collections:

.NET Build Errors
TypeScript Compiler Errors
Docker Build Failures
Test Framework Errors
Git Conflicts

Each template includes regex patterns that I've been using in my workflow. They work well for me, but your mileage may vary depending on your specific tools and setup. The good news is that patterns are just simple regex strings in the config file - you can easily tweak them anytime to match your exact error formats.

Debug Mode

At this point, you might ask: "What if the filters miss something important?" This is where --no-filter becomes essential. When the filters aren't catching what you need, you can see the complete output to understand what patterns to add:

aex frontend-build --no-filter  # See complete output

I use this constantly when setting up filters for a new project. Run the command with --no-filter, see what the actual error format looks like, then adjust your regex patterns accordingly. Every project is a bit different - different linting rules, different error formats, different test runners. The predefined patterns are just a starting point; you'll likely need to tweak them for your specific workflow.

Performance

Think about your typical debugging workflow. You run a command, fix an error, run again, fix another error, and so on. With traditional output:

Failed build: 800 tokens of mostly noise
Successful build: 500 tokens of "everything compiled successfully" messages
Another failed attempt: 800 more tokens
Final success: Another 500 tokens of success messages

With Apparatus.Exec:

Failed build: 60 tokens of actual errors
Successful build: 1 token (just "Done")
Another failed attempt: 40 tokens of the remaining error
Final success: 1 token

Over a debugging session with 20-30 commands, that's a reduction from ~15,000 tokens to ~500 tokens. But here's what really matters - the LLM only sees information when there's something to fix. No more processing "Build succeeded" messages, no more reading through successful test output. The silence itself becomes information: if there's no output, everything worked.

Limitations

This tool doesn't do well:

Complex shell features - It doesn't support pipes, redirects, or shell variables. Each command runs independently.
Interactive commands - Commands that require user input won't work properly.
Real-time output - You only see output after the command completes, not as it runs.

For these cases, you'll still need to use your regular terminal. But for the bread-and-butter commands you run while coding with an LLM, it works perfectly.

The Future

I'm actively using this tool in my daily work and have plans to improve it based on feedback. What features would help your workflow? Feel free to create an issue or submit a PR - I'd love to hear your ideas!

Conclusion

Working with LLMs has changed how we write code, but the tooling hasn't caught up yet. We're using tools designed for human consumption in LLM workflows, and it shows. This tool is my attempt to bridge that gap - at least for command execution and output filtering.

As for me, the difference has been dramatic. My LLM conversations are faster, cheaper, and more focused. The tool pays for itself in saved tokens within a single debugging session.

If you're using LLM-powered coding assistants like Claude Code, Cursor, Windsurf, or Gemini CLI, you know how much unnecessary output gets sent to the LLM when it runs commands for you. Every time these tools execute a build or test command, they're consuming tokens on verbose logs that don't matter. This tool helps reduce that waste significantly.

Thanks for your time! Feel free to leave a comment or create an issue if you have questions or suggestions.

Links: GitHub, NPM

ZeroQL - LINQ Graphql Client Updates

Stanislav Silin — Tue, 18 Jul 2023 07:27:05 +0000

Today I want to showcase the new version of the ZeroQL C# friendly GraphQL client with a Linq-like interface that allows to call GraphQL endpoints without the need to write raw GraphQL queries.

The new version brings a bunch of new features, such as improved initial configuration, compatibility with .Net Framework and Unity, a new way to pass variables into query, optional variables, improved scalar types handling, and the ability to get raw GraphQL query from C# lambda.

Github repository
Full Github wiki

Configuration improvements

ZeroQL's latest update introduces a major simplification to its configuration process, eliminating the need for manual setup and csproj file modifications. This change is centered around the removal of the previous necessity for ZeroQL Command Line Interface (CLI) usage for client generation.

In the past, the initial configuration process required executing the ZeroQL CLI to generate the client using the following command:

dotnet zeroql generate 
  --schema .\schema.graphql 
  --namespace TestServer.Client
  --client-name TestServerGraphQLClient
  --output Generated/GraphQL.g.cs

There was a way to simplify it by using the configuration file:

dotnet zeroql generate -c ./config.zeroql.json

With the new version, there is no need for it anymore. It is enough to generate the config file and add the ZeroQL package to the project. The ZeroQL will detect it and automatically execute generation on the build — no changes to csproj and custom scripts are required.

The generated GraphQL client would be placed inside the obj/ZeroQL folder. In such a way, you would have access to the client and it would not be visible in the solution viewer or git.

.Net Standard Support

The new version brings support for the .Net Standard. It opens the possibility of using ZeroQL inside Xamarin, MAUI, Unity, and even legacy .Net Framework projects.

To make it work, you need to create a netstandard class library and set the language version to the latest in your csproj.

    <LangVersion>latestmajor</LangVersion>

Subsequently, compatibility must be enabled within the ZeroQL configuration, which can be achieved with the following setting:

{
    "netstandardCompatibility": true
}

That's all for classic netstandard projects. The full documentation can be found here.

For Unity, setup is more complicated. More info on it can be found in wiki article

New variables

In previous versions, if you want to pass a variable, you need to create an object, pass it as a parameter, and reuse it inside the lambda:

var input = new { Id = 42 };
var response = client.Query(input, static (i, q) => q.User(i.Id, o => new { ... });

With the new version, there is no need for it. You can just pass a variable into lambda closure like that:

var id = 42;
var response = client.Query(q => q.User(id, o => new { ... });

This approach still has limitations. The variable should be the local variable or the method parameter.

Here is an example with the parameter:

public Task<User> GetUser(int userId)
{
    var response = await client.Query(o => o.User(userId, o => new User(o.Id, o.FirstName, o.LastName)));
    return response.Data;
}

Here is an example that would fail:

public int UserId { get; set; }

public Task<User> GetUser()
{
    var response = await client.Query(o => o.User(UserId, o => new User(o.Id, o.FirstName, o.LastName))); // ZeroQL will report a compilation error here
    return response.Data;
}

To be clear, you don't need actively account for it. ZeroQL will analyze and report errors if something is wrong.

Optional Variables

Now the optional variables work as expected. For example, let's have a look at the next GraphQL schema:

type Query {
    users(page: Int!, size: Int!, filter: String): [User!]!
}

type User {
    Id: ID!
    Name: String!
}

In previous versions, if you needed to get users without filter, you would need to set it to null:

var page = 1;
var size = 10;
var response = await client.Query(q => q
    .Users(page, size, null, o => new { o.Id, o.Name }));

Now you can skip it:

var page = 1;
var size = 10;
var response = await client.Query(q => q
    .Users(page, size, selector: o => new { o.Id, o.Name }));

New Scalar Types

With ZeroQL, you can map GraphQL scalars into C# classes. There are two ways to do it.
First, just generate a ZeroQL GraphQL client. By default, all custom scalars will be mapped into stubs like that:

public sealed record Instant : ZeroQLScalar
{
    public Instant()
    {
    }

    public Instant(string value)
    {
        Value = value;
    }

    public static implicit operator Instant(string value) => new Instant(value);
    public static implicit operator string (Instant scalar) => scalar.Value;
}

If you don't have any special requirements for a scalar, then this way is for you.

The second way allows you to define complex mappings for your scalars.
For example, we have a schema with scalar Instant:

schema {
  query: Query
}

type Query {
  instant: Instant!
}

"Represents an instant on the global timeline, with nanosecond resolution."
scalar Instant

We can create a C# class and JSON serializer and add mapping for it:

public class Instant
{
    public DateTimeOffset DateTimeOffset { get; set; }
}

public class InstantConverter : JsonConverter<Instant?>
{
    public override Instant? Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
    {
        var instant = reader.GetString();
        return new Instant { DateTimeOffset = DateTimeOffset.Parse(instant!) };
    }

    public override void Write(Utf8JsonWriter writer, Instant? value, JsonSerializerOptions options)
    {
        var instant = value.DateTimeOffset.ToString("yyyy-MM-ddTHH:mm:ssZ");
        writer.WriteStringValue(instant);
    }
}

public static class Module
{
    [ModuleInitializer]
    public static void Initialize()
    {
        // don't forget to add serializer to ZeroQL json options
        ZeroQLJsonOptions.Configure(o => o.Converters.Add(new InstantConverter()));
    }
}

Then during generation, pass parameter --scalars Instant=MyApp.Instant or set property scalars in zeroql.json config file

"scalars": {
    "Instant": "MyApp.Instant"
}

It will replace the GraphQL scalar with the correct type in generated GraphQL client.

Get Raw GraphQL Query

Some GraphQL endpoints may accept raw GraphQL queries as arguments. Here example:

 type Query {
  user(id: ID!) User!
  readInBatch(graphql: String!, variables: JSON): JSON!
}

type User {
    id: ID!
    name: String!
}

Now it is possible to generate GraphQL query without execution:

var queryInfo = QueryInfoProvider.Materialize<Query>(q => q
    .User(id, u => new { u.Id, u.Name }));
// {
//  "Query": "query ($id: ID!) { user(id: $id) { id name } }",
//  "QueryBody": "($id: ID!) { user(id: $id) { id name } }",
//  "OperationType": "query",
}

// then pass values into the query
var variables = // ...
var graphqlQuery = queryInfo.QueryBody;
var response = await client.Query(q => q.ReadInBatch(graphqlQuery, variables));

Final thoughts

In conclusion, the newest version of ZeroQL offers many features and improvements that enhance the usability of the GraphQL client. The simplified initial configuration process saves time and effort, while the extended .Net Standard support significantly broadens the client's potential usage. The new variables help to align expectations with a 'classic' LINQ-like interface.

Overall it is a huge update that makes building GrapgQL queries even easier.

The full source code can be found in the Github repository.

Have a look and press the start button. 😊

Convert REST API to GraphQL API

Stanislav Silin — Thu, 22 Jun 2023 13:09:00 +0000

In this article, I want to showcase a new way to create web APIs with GraphQL. We will look at its benefits compared to traditional REST API, and how we can transform existing REST API to support GraphQL.

Over and under fetching

First of all, we need to figure out what issues we can have with the REST APIs and how GraphQL can help solve them. The main two issues would be under-fetching and over-fetching. They are common when we are working with REST APIs. Under-fetching occurs when an initial API request doesn't supply enough data, forcing the application to make additional requests. Over-fetching, on the other hand, happens when an API request returns more data than the client needs.

Consider a scenario where a developer works on a user profile that needs to load user personal information (e.g., name, email, and profile picture) and user roles (e.g., admin, subscriber, etc.). In a traditional RESTful approach, fetching this data could require at least two different endpoints: one for personal information and another for roles.

If you fetch from the personal information endpoint and it doesn't include the user roles, you've been under-fetched and must make an additional request to the roles endpoint. Conversely, if the personal information endpoint returns all available data about a user—including details not needed for the current view—you've over-fetched, wasting bandwidth and potentially slowing down the application.

The GraphQL helps to solve this issue rather easy. Instead of having multiple endpoints, there's a single endpoint that accepts queries. These queries define exactly what data the client needs, eliminating under-fetching. The client can request different data types in a single request.

Let's look at our user profile example. Instead of making separate requests for personal information and roles, we can make a single GraphQL query:


 graphql
query {
  user(id: 1) {
    name
    email
    profilePicture
    roles {
      title
    }
  }
}

This query asks for specific fields (name, email, profilePicture, and roles) for the user with an id of 1. The server will return a JSON object that mirrors the shape of the query and includes just the requested fields.

The flexibility of GraphQL queries also solves the problem of over-fetching. Because the client specifies exactly what data it needs, the server will never send unnecessary data. Using our example, if we don't need the user's profile picture for a certain view, we can simply leave it out of the query:


 graphql
query {
  user(id: 1) {
    name
    email
    roles {
      title
    }
  }
}

In this query, the server will not send the profile picture, even if it's available.

Key differences with REST

Query

GraphQL's strict protocol is an essential part of its power and is a key distinction from REST APIs, where conventions can vary significantly. Nowadays, all major tech companies have their own REST best practices that sometimes can be completely incompatible.

At the same time, GraphQL APIs are organized in terms of types and fields, not endpoints. GraphQL uses a strong type system to describe the capabilities of an API and all the types of data it can return, enabling developer tools and ensuring the APIs behave in predictable ways.

Here is an example how the schema may look:


 graphql
type Query {
  users(page: Int!, size: Int!): [User!]!
  user(id: Int!): User
}

type Mutation {
  createUser(name: String!, email: String!): User!
}

type Role {
  id: Int!
  name: String!
}

type User {
  id: Int!
  name: String!
  email: String!
  roles: [Role!]!
}

Versioning

Versioning is an essential aspect of maintaining APIs, especially when the API undergoes significant changes. In traditional REST APIs, versioning often involves either changing the URL of an endpoint or including a version number in the request header. This approach has the downside of potentially breaking the application for any clients not updated to use the new version of the API. However, GraphQL takes a fundamentally different approach to versioning, helping avoid the issues associated with traditional versioning methods.

Instead of creating new versions of the entire API, developers can simply extend the existing GraphQL schema with new fields to support new functionality. Clients that haven't been updated to understand these new fields will just ignore them, and the API remains backward compatible.

In case when we need to remove a field, GraphQL supports deprication, which signals to developers that a field is no longer in use and will be removed in the future. Even after a field is deprecated, it still works, so clients using that field will not break immediately. This provides time for clients to transition away from the deprecated field.

The strong type system in GraphQL helps to ensure that changes are compatible with existing queries. It prevents incompatible changes like altering the type of a field.

In essence, GraphQL's approach to versioning avoids the need for version numbers and breaking changes. It's more flexible and forgiving, and it lets developers add new features to an API without disrupting existing users. As a result, API evolution becomes a smoother process, fostering a better developer experience and ensuring more reliable applications.

Client Generation

In GraphQL, client generation leverages the API schema and introspection feature. Given that the GraphQL schema is strongly typed and the types and relationships are well defined, it's possible to use this information to automatically generate client code. The client can be in various languages like TypeScript, C#, etc. It reduces the amount of boilerplate code that developers need to write, saving time and minimizing the risk of manual coding errors.

Client generation works harmoniously with GraphQL's field deprecation semantics. When a field is deprecated, it can still be included in the schema and the generated client code, but it's marked as deprecated.

Developers can see the deprecation warning directly in their IDE while they're coding. This helps them move away from using deprecated fields in a smooth and controlled manner. Over time, as developers stop using the deprecated field, it can be safely removed from the schema without breaking any clients.

Converting existing REST API into GraphQL API

Initial setup

Now let's look at how we can convert existing REST API into GraphQL API.
The initial endpoints look like that:


 csharp
app.UseEndpoints(
    o =>
    {
        o.MapSwagger();
        o.MapGet("/users", 
            async (int page, int size, UserService service) => await service.GetUsers(page, size));

        o.MapGet("/users/{id}",
            async (int id, UserService service) => await service.GetUser(id));

        o.MapGet("/users/{id}/roles",
            async (int id, RoleService service) => await service.GetRolesByUserId(new[] { id }));

        o.MapPost("/users", 
            async (UserCreationRequest request, UserService service) => await service.CreateUser(request.Name, request.Name));
    });

The article contains only selected source code to be short.
If you want to see the full source code go to the demo repository https://github.com/byme8/DemoGraphQL
There are two branches:

master - contains initial REST API

graphql - contains final GraphQL API

Endpoints that handle the page from the under-fetching and over-fetching example. The first thing you need to do is to install HotChocolate.AspNetCore Nuget package.


 bash
dotnet add package HotChocolate.AspNetCore

The HotChocolate is a set of tools that allows us to receive and process GraphQL queries. It has a nice integration with the AspNet Core pipeline. The full documentation can be found here.

Now bootstrap GraphQL server:


 csharp
+ services
+    .AddGraphQLServer()
+    .AddQueryType<Query>();

// ...

app.UseEndpoints(
    o =>
    {
+       o.MapGraphQL();
        o.MapSwagger();
        o.MapGet("/users", 
            async (int page, int size, UserService service) => await service.GetUsers(page, size));
// ...
+ public class Query 
+ {
+   public DateTimeOffset Utc() => DateTimeOffset.UtcNow;
+ }

When we launch our application, we can access the GraphQL endpoint http://localhost:1234/graphql. If opened via the browser, we will see a GraphQL IDE. Here we can check the GraphQL schema and execute requests.

The initial setup is ready, and we can start to transform our REST APIs.

Creating queries

Let's transform the next endpoint first:


 csharp
        o.MapGet("/users/{id}",
            async (int id, UserService service) => await service.GetUser(id));

To do it we can just create a new method in our Query class:


 csharp
public class Query 
{
  public DateTimeOffset Utc() => DateTimeOffset.UtcNow;

+ public Task<User?> GetUser(int id, [Service] UserService userService)
+   => userService.GetUser(id);
}

Done! If we open our GraphQL IDE and check GraphQL schema, it would look like that:


 graphql
type Query {
  utc: DateTime!
  user(id: Int!): User
}

type User {
  id: Int!
  name: String!
  email: String!
}

The HotChocolateautomatically detects what types are exposed and add them to the schema.

Let's move on and transform another endpoint. However, do it a bit differently. We can still add it to the Query class, but placing everything into one class is not a great idea. We can split it to look very close to what we have when using controllers from AspNet Core.

To make it work, create a new class UserQueryExtensions and define new "endpoints" there. Moving further, I will use the "GraphQL field" definition to indicate the equivalent to "REST endpoints", but for GraphQL.

It will look like this:


 csharp
 services
    .AddGraphQLServer()
    .AddQueryType<Query>()
+   .AddTypeExtension<UserQueryExtensions>();

// ..
public class Query 
{
  public DateTimeOffset Utc() => DateTimeOffset.UtcNow;

- public Task<User?> GetUser(int id, [Service] UserService userService)
-   => userService.GetUser(id);
}

+ [ExtendObjectType(typeof(Query))]
+ public class UserQueryExtensions
+ {
+     public Task<IEnumerable<User>> GetUsers(int page, int size, [Service] UserService userService)
+         => userService.GetUsers(page, size);
+     
+     public Task<User?> GetUser(int id, [Service] UserService userService)
+         => userService.GetUser(id);
+ }

Here we created a class that extends another GraphQL type. In our case, it is a root type Query. Also, I moved user related GraphQL field from the Query and added it to a new extension. Pay attention to the configuration section at the beginning. You have to add these extensions to the setup manually. Otherwise, the HotChocolate would not detect it.

Now the GraphQL schema will have the following look;


 graphql
type Query {
  utc: DateTime!
+ users(page: Int!, size: Int!): [User!]!
  user(id: Int!): User
}

type User {
  id: Int!
  name: String!
  email: String!
}

As you can see, from the GraphQL persective, there is only one thing that changed. Now, we have a new GraphQL field. It is exactly what we wanted.

More complex type extending

Let's add roles to our GraphQL schema. The initial REST endpoint looks like this:


 csharp
        o.MapGet("/users/{id}/roles",
            async (int id, RoleService service) => await service.GetRolesByUserId(new[] { id }));

We can do this in two ways. First one more REST-like way. We just created another GraphQL field that will return a list of roles for a specific user. The schema would look like this:


 graphql
type Query {
  utc: DateTime!
  users(page: Int!, size: Int!): [User!]!
  user(id: Int!): User
+ userRoles(userId: Int!): [Role!]!
}

type User {
  id: Int!
  name: String!
  email: String!
}

+ type Role {
+  id: Int!
+  name: String!
+ }

But there is a GraphQL way. We can extend the User type itself. So, when we request a user, we can fetch additional user roles. In this case, we will have the next GraphQL schema:


 graphql
type Query {
  utc: DateTime!
  users(page: Int!, size: Int!): [User!]!
  user(id: Int!): User
}

type User {
  id: Int!
  name: String!
  email: String!
+ roles: [Role!]!
}

+ type Role {
+  id: Int!
+  name: String!
+ }

Let's do it to support the second way. To make it work, we need to create another extension class. However, we will extend the User type, not Query:


 csharp
[ExtendObjectType(typeof(User))]
public class UserRolesQueryExtensions
{
    public async Task<Role[]> GetRoles([Parent] User user, [Service] RoleService roleService)
    {
        var rolesByUserId =  await roleService.GetRolesByUserId(ids);
        return rolesByUserId[user.Id];
    }
}

This setup allows us to build the next query from the "under and over fetching" example:


 graphql
query GetUserProfile($userId: Int!) {
  user(id: $userId) {
    id
    name
    email
    roles {
      id
      name
    }
  }
}

But how it works? The GraphQL server receives the request mapped to proper GraphQL extensions. Here it would be two of them - the GetUser and GetRoles. The first extension would be executed, and its result would be passed to the second one. In the end, we have one request from the client and the GraphQL server that executed two GraphQL fields. As a result, the client will receive the final result faster because everything happens locally on the server, which is much closer to a database.

However, there is one issue with such an approach. Let's have a look at the next query:


 graphql
query GetUsers($page: Int!, $size: Int!) {
  users(page: $page, size: $size) {
    id
    email
    roles {
      id
    }
  }
}

Here we have a GraphQL field that returns a list of items. Then for each item, we have an extension. If we keep everything as we have right now, it can be a disaster.

Let's analyze what is happening:

GraphQL server executes GetUsers GraphQL field and gets 5 items.
GraphQL server executes GetUserRoles GraphQL field for 1st item.
GraphQL server executes GetUserRoles GraphQL field for 2nd item.
GraphQL server executes GetUserRoles GraphQL field for 3rd item.
GraphQL server executes GetUserRoles GraphQL field for 4th item.
GraphQL server executes GetUserRoles GraphQL field for 5th item.
GraphQL server returns the final result.

As you can see, it can be an issue when the GetUserRoles goes to a database for every item. It can make performance really bad.
To fix this issue, the GraphQL server has a feature called data loaders. They allow you to batch GraphQL field execution and get data in one go. Here is how improved GetUserRoles would look like:


 csharp
[ExtendObjectType(typeof(User))]
public class UserRolesQueryExtensions
{
    public async Task<Role[]> GetRoles(
        IResolverContext context,
        [Parent] User user, [Service] RoleService roleService)
    {
        return await context.BatchDataLoader<int, Role[]>(async (ids, ct)
            => await roleService.GetRolesByUserId(ids))
            .LoadAsync(user.Id);
    }
}

It creates an instance of batch data loader on the first call and adds the current id to a list. Then for every subsequent call, we just remember user ids. When we have the full list of user ids, it calls a lambda with those user ids, and we can just get user roles for all users at once. so, the log would look like this:

GraphQL server executes GetUsers GraphQL field and gets 5 items.
GraphQL server executes GetUserRoles GraphQL field that creates batch data loader and passes id of the 1st item.
GraphQL server executes GetUserRoles GraphQL field that passes id of the 2nd item.
GraphQL server executes GetUserRoles GraphQL field that passes id of the 3rd item.
GraphQL server executes GetUserRoles GraphQL field that passes id of the 4th item.
GraphQL server executes GetUserRoles GraphQL field that passes id of the 5th item.
GraphQL server executes data loader.
GraphQL server return final result.

Full documenation can be find here.

Creating mutation

Another small thing about the GraphQL. You maybe forgot, but there was another endpoint:


 csharp
        o.MapPost("/users", async (UserCreationRequest request, UserService service) 
              => await service.CreateUser(request.Name, request.Name));

Semantically it has a different meaning compared to previous endpoints. It is a mutation operation that creates a new entity. The GraphQL draws a line between read and edit operations. All read operations have to be defined in Query type, and all edit operations have to be defined in Mutation type. So, defining this endpoint as a mutation would be a good idea.

Here is how we can do it:


 csharp
services
    .AddGraphQLServer()
    .AddQueryType<Query>()
+   .AddMutationType<Mutation>()
+   .AddTypeExtension<UserMutationExtensions>();

// ...

public class Mutation
{

}

// ...

[ExtendObjectType(typeof(Mutation))]
public class UserMutationExtensions
{
    public Task<User> CreateUser(string name, string email, [Service] UserService userService)
        => userService.CreateUser(name, email);
}

It is the same approach as with the Query type, but now we have the Mutation type as a root type.

Conclusion

In the beginning, we had a brief look at the reasons why GraphQL was developed. Under-fetching and over-fetching are common challenges with traditional RESTful APIs, potentially leading to inefficiencies and poor user experiences. GraphQL offers a way how to avoid it, allowing clients to specify precisely what data they need, reducing unnecessary requests and data transfer. This flexibility optimizes performance and bandwidth usage, making GraphQL a compelling choice for modern web development.

In the second part, we had a look on how to set up GraphQL server. We figured out how to create GraphQL fields and what we need to consider when transforming existing REST endpoints into GraphQL fields.

I hope you find this article useful. In the next time, we will look at how to do integration testing of our GraphQL APIs.

ZeroQL V3 - C# friendly GraphQL client

Stanislav Silin — Tue, 28 Feb 2023 15:45:48 +0000

Hello there! I want to share the new features of ZeroQL's latest release. This release contains many improvements, including support for unions and interfaces, automatic scalars generation, and config file support.

Introducing ZeroQL's Config File

With the latest release, ZeroQL introduces support for config files. This means that you no longer have to memorize CLI options or type long commands every time you want to generate a GraphQL client. You can now create a configuration file with all your desired options.

Let's suppose we want to execute the next command:

dotnet zeroql generate --schema .\schema.graphql --namespace TestServer.Client --client-name TestServerGraphQLClient --output Generated/GraphQL.g.cs

We can use dotnet zeroql config init. It will create the zeroql.json file with the following content:

{
  "$schema": "https://raw.githubusercontent.com/byme8/ZeroQL/main/schema.verified.json",
  "graphql": "./schema.graphql",
  "namespace": "TestServer.Client",
  "clientName": "TestServerGraphQLClient",
  "output": "./Generated/GraphQL.g.cs"
}

Now we can use CLI like that:

dotnet zeroql -c ./zeroql.json

Unions and interfaces

ZeroQL's latest update brings proper support for unions and interfaces. This means that you can now work with these GraphQL types in your C# code using an intuitive and straightforward syntax.

To demonstrate this feature, let's take a look at an example GraphQL schema containing interfaces:

schema {
  query: Query
}

interface IFigure {
  perimeter: Float!
}

type Circle implements IFigure {
  center: Point!
  radius: Float!
  perimeter: Float!
}

type Point implements IFigure {
  x: Float!
  y: Float!
  perimeter: Float!
}

type Square implements IFigure {
  topLeft: Point!
  bottomRight: Point!
  perimeter: Float!
}

type Query {
  figures: [IFigure!]!
}

Now we can get figures by writing the next C# query:

var response = await qlClient.Query(static q => q
    .Figures(f => new
    {
        f.Perimeter,
        Circle = f.On<Circle>().Select(c => new
        {
            c.Radius,
            Center = c.Center(p => new { p.X, p.Y })
        }),
        Square = f.On<Square>().Select(s => new
        {
            TopLeft = s.TopLeft(p => new { p.X, p.Y }),
            BottomRight = s.BottomRight(p => new { p.X, p.Y })
        })
    }));

Console.WriteLine(JsonSerializer.Serialize(response)); 
// {
//   "Query": "query { figures { perimeter ... on Circle { radius center { x y }  } ... on Square { topLeft { x y }  topLeft { x y }  } __typename } }",
//   "Data": [
//     {
//       "Perimeter": 6.2831854820251465,
//       "Circle": {
//         "Radius": 1,
//         "Center": {
//           "X": 1,
//           "Y": 1
//         }
//       }
//     },
//     {
//       "Perimeter": 40,
//       "Square": {
//         "TopLeft": {
//           "X": 1,
//           "Y": 1
//         },
//         "BottomRight": {
//           "X": 11,
//           "Y": 11
//         }
//       }
//     }
//   ]
// }

Basically, every interface is treated as a C# interface. Then we can use the extension method On to select the concrete implementation we want.

The same logic applies to unions too. Here is the GraphQL schema example:

schema {
  query: Query
}

type TextContent {
  text: String!
}

type ImageContent {
  imageUrl: String!
  height: Int!
}

union PostContent = TextContent | ImageContent

type Query {
  posts: [PostContent!]!
}

And here is how we can write a query to get a result:

var response = await qlClient.Query(static q => q
        .Posts(
            o => new
            {
                Image = o.On<ImageContent>().Select(oo => new
                {
                    oo.ImageUrl,
                    oo.Height
                }),
                Text = o.On<TextContent>().Select(oo => new
                {
                    oo.Text
                }),
            }));

Console.WriteLine(JsonSerializer.Serialize(response));
// {
//   "Query": "query { posts { ... on ImageContent { imageUrl height } ... on TextContent { text } __typename } }",
//   "Data": [
//     {
//       "Image": {
//         "ImageUrl": "http://example.com/image.png",
//         "Height": 1920
//       }
//     },
//     {
//       "Text": {
//         "Text": "Hello World!"
//       }
//     }
//   ]
// }

As you can see on the C# level, there is no difference between the interface and the union types. All of them have identical syntax and behavior.

Automatic Scalar Generation

ZeroQL now supports automatic scalar generation, which means that you no longer have to define custom types and JSON serializers for every scalar type you use in your GraphQL schema. This feature automatically generates C# types and JSON serializers for every scalar type used in your schema, making it easier and faster to work with GraphQL.

To use this feature, you simply define your scalar types in your GraphQL schema like this:

schema {
  query: Query
}

scalar PostId;

type Post {
  id: PostId,
  text: String!
  imageUrl: String!
  height: Int!
}

type Query {
  myPosts: [Post!]!
}

When you generate your client using ZeroQL, it will automatically generate a C# record for the PostId scalar type, along with a JSON serializer. This makes it easy to work with scalars in your C# code without manually defining custom types and serializers. In this case, it would look like that:

public sealed record PostId : ZeroQLScalar
{
    public PostId()
    {
    }

    public PostId(string value)
    {
        Value = value;
    }

    public static implicit operator PostId(string value) => new PostId(value);
    public static implicit operator string (PostId scalar) => scalar.Value;
}

As a result, you can have as many scalars as you want, and all of them will have a proper representation on the C# level automatically.

Conclusion

It is a solid update for ZeroQL. It extends support for GraphQL capabilities, simplifies configuration management, and, at the same time, maintains the outstanding performance of a raw HTTP request.

If you have any questions or want to find more detailed instructions on how to use the library, you can find them on Github.

ZeroQL V2 - C# GraphQL client

Stanislav Silin — Sun, 09 Oct 2022 15:07:56 +0000

In this article, I want to present the major update for ZeroQL. It brings new features and support for more complex workflows.
Such as file uploads, new request-like way to define queries and mutations, persisted queries, and more.
If you are interested, continue reading.

What is ZeroQL?

If you read my previous articles[1][2] you know that ZeroQL is a C# GraphQL client that allows you to write GraphQL queries with C# in a Linq-like way. I will give you a quick overview for those who don't know.

Let's suppose that we have a GraphQL schema like that:

schema {
  query: Query
  mutation: Mutation
}

type Query {
  me: User!
  user(id: Int!): User
}

type Mutation {
  addUser(firstName: String!, lastName: String!): User!
  updateUser(userId: Int!, firstName: String!, lastName: String!): User!
  addAvatar(userId: Int!, avatar: Upload!): Boolean!
}

type User {
  id: Int!
  firstName: String!
  lastName: String!
  role: Role!
}

type Role {
  id: Int!
  name: String!
}

The ZeroQL allows to generate a fully-typed client:

# create console app
dotnet new console -o QLClient
# go to project folder 
cd QLClient
# fetch graphql schema from server(depends on your web server)
curl http://localhost:10000/graphql?sdl > schema.graphql 
# create manifest file to track nuget tools
dotnet new tool-manifest 
# add ZeroQL.CLI nuget tool
dotnet tool install ZeroQL.CLI
# add ZeroQL nuget package
dotnet add package ZeroQL 
# to bootstrap schema.graphql file from graphql schema
dotnet zeroql generate --schema .\schema.graphql --namespace TestServer.Client --client-name TestServerGraphQLClient --output Generated/GraphQL.g.cs

Now we can write GraphQL queries like that:

var httpClient = new HttpClient();
httpClient.BaseAddress = new Uri("http://localhost:10000/graphql");

var client = new TestServerGraphQLClient(httpClient);
var response = await client
  .Query(static o => o
    .Me(o => new { o.Id, o.FirstName, o.LastName }));

Console.WriteLine($"GraphQL: {response.Query}"); // GraphQL: query { me { id firstName lastName } }
Console.WriteLine($"{response.Data.Id}: {response.Data.FirstName} {response.Data.LastName}"); // 1: Jon Smith

The q.Me method is a query field from the schema, and the o => new { o.Id, o.FirstName, o.LastName } is a selection set.
When we call the Query method, the ZeroQL generates a GraphQL query from the C# code at compile time. Then at runtime, it sends the query to the server and gets the response.
As a result, the performance is the same as if we write a GraphQL query manually.

File uploading

The new version supports the official way to upload files. I mean the Upload scalar type.
Here is a sample GraphQL query:

mutation AddAvatar($id: Int!, $file: Upload!) {
  addAvatar(id: $id, file: $file)
}

Now we can replicate it like that:

var variables = new
{
    Id = id,
    File = new Upload("avatar.png", imageStream)
};
var response = await client.Mutation(variables, static (i, m) => m.AddAvatar(i.Id, i.File));

The GraphQL client will create the multipart request and send the request in parts. For more info about the protocol, you can look here.

Request Syntax

ZeroQL brings a new way to define GraphQL queries. The main goal of it is to provide a way to extract complex queries into a separate entity and then reuse them inside the business layer.
For example, here is a more complex query:

mutation UpdateUser($id: Int!, $avatar: Upload!, $firstName: String!, $lastName: String!) {
  updateUser(firstName: $firstName, lastName: $lastName) {
    id,
    firstName,
    lastName,
  },
  addAvatar(userId: $id, avatar: $avatar)
}

The lambda syntax will look like that:

var variables = new 
{
    Id = id,
    FirstName = firstName,
    LastName = lastName,
    Upload = new Upload("avatar.png", imageStream)
};

var response = await client
    .Mutation(variables, static (i, m) => new
    {
        User = m.UpdateUser(i.Id, i.FirstName, i.LastName, o => new UserResponse(o.Id, o.FirstName, o.LastName)),
        AvatarUpdated = m.AddAvatar(i.Id, i.Upload)
    });

Such implementation inside a service looks clunky and too verbose. The request syntax makes it much simple:

// somewhere in a proper place
public record UpdateUserResponse(UserResponse User, bool AvatarUpdated);

public record UpdateUser(int Id, string FirstName, string LastName, Upload File) 
  : GraphQL<Mutation, UpdateUserResponse>
{
    public override UpdateUserResponse Execute(Mutation mutation) => new UpdateUserResponse(
        mutation.UpdateUser(Id, FirstName, LastName, o => new UserResponse(o.Id, o.FirstName, o.LastName)),
        mutation.AddAvatar(Id, File));
}

// ...

// inside the service
var response = await client.Execute(new UpdateUser(id, firstName, lastName, new Upload("avatar.png", imageStream)));

As I said, the main advantage is splitting the query declaration and query execution. Also, it can be useful if you execute a query via AOT runtime. The "lambda"-like syntax relay on anonymous types to pass the query variables. It is fine when you need just to serialize the instance, but it has issues when you want to get some value from the fields. A good example would be the Upload type. It requires special handling, and in the case of an anonymous type, it requires reflection and Reflection.Emit to handle it with acceptable performance. As a result, when the app is compiled in AOT mode, it will fail at runtime. The request-like syntax doesn't have such an issue because query variables would have a concrete type, and we can interact with it without the need for reflection.

Persisted queries

The new version brings support for graphql persisted queries. The ZeroQL supports "static persisted queries" and "automatic persisted queries" pipelines.

The persisted queries can generally reduce the request size and execution time. For example, if we have the next request:

{
  "variables" : { "id" : 1, "avatar": null, "firstName": "John", "lastName": "Smith" },
  "query": "mutation UpdateUser($id: Int!, $avatar: Upload!, $firstName: String!, $lastName: String!) {
  updateUser(firstName: $firstName, lastName: $lastName) {
    id,
    firstName,
    lastName,
  },
  addAvatar(userId: $id, avatar: $avatar)
}"
}

With persistent queries it will be transformed into this:

{
  "variables" : { "id" : 1, "avatar": null, "firstName": "John", "lastName": "Smith" },
  "persistedQuery": {
    "version":1,
    "sha256Hash":"420548026ac8cec25f7c4c592c3adc9140c9a9d70a9cfbda8a21b92b01b548f2"
  }
}

It brings a bunch of improvements. First, the request is smaller, and the network usage is lower. Secondly, the hash works like an id. The GraphQL server can cache and reuse the execution pipeline without the need to parse the GraphQL syntax on every request. As a result, the request execution time can be much lower. You can think about it like a "sql procedure." You pass the name, and the SQL server knows what to do next.

Automatic persisted queries

Basically, on the first attempt, the client will send the "hashed" request. Then if the server identifies the hash, it will execute the appropriate query. If such hash is missing on the server, the request is rejected.
Then the client will send another request like that:

{
  "variables" : { "id" : 1, "avatar": null, "firstName": "John", "lastName": "Smith" },
  "query": "mutation UpdateUser($id: Int!, $avatar: Upload!, $firstName: String!, $lastName: String!) {
  updateUser(firstName: $firstName, lastName: $lastName) {
    id,
    firstName,
    lastName,
  },
  addAvatar(userId: $id, avatar: $avatar)
}",
  "persistedQuery": {
    "version":1,
    "sha256Hash":"420548026ac8cec25f7c4c592c3adc9140c9a9d70a9cfbda8a21b92b01b548f2"
  }
}

The server will remember the hash and the query. So, the next time when the client sends the hash, the request will be executed as expected.

You can enable it for the ZeroQL client by passing PersistedQueryPipeline pipeline into the client constructor like that:

var client = new TestServerGraphQLClient(httpClient, new PersistedQueryPipeline()); 
var response = await client.Execute(new GetUserQuery(1)); 

Console.WriteLine($"GraphQL: {response.Query}"); // GraphQL: 8cc1ee42eecdac2a8590486826856c041b04981a2c55d5cc560c338e1f6f0285:query GetUserQuery($id: Int!) { user(id: $id) { id firstName lastName } }
Console.WriteLine(response.Data); // UserModel { Id = 1, FirstName = Jon, LastName = Smith }

From the ZeroQL client perspective, it is all you need to do. Additionally, you will need to configure your GraphQL server, but it is a totally different story. You can find more information about how to do it with the HotChocolate server here.

Static persisted queries

This workflow requires additional interaction between a server and a client at build time. The idea is the same, but the server expects to know about all possible queries and their hashes before the request happens. To make it possible, you need to export queries from the client.
For ZeroQL it can be done via ZeroQL.CLI like that:

 dotnet zeroql queries extract -a .\bin\Debug\net6.0\TestProject.dll -c TestServer.Client.TestServerGraphQLClient -o ./queries

The queries folder will contain a bunch of "hashed" GraphQL files. Inside they will have a GraphQL query associated hash in file name:

8cc1ee42eecdac2a8590486826856c041b04981a2c55d5cc560c338e1f6f0285.graphql # query GetUserQuery($id: Int!) { user(id: $id) { id firstName lastName } }
21cc96eaf0c0db2b5f980c8ec8b5aba2e40eb24f370cfc0cd7e4825509742ae2.graphql # mutation AddAvatar($id: Int!, $file: Upload!) { addUserProfileImage(userId: $id, file: $file)}

Then you need to configure your server to access them. How to do it for the HotChocolate server is described here.

Conclusion

That is all that I wanted to share right now. I would say it is a big release with improvements that extend the capabilities of ZeroQL. The support for file uploading, persisted queries, and request-like syntax opens possibilities for new workflows and optimizations.

The ZeroQL repository is Github.
Feel free to create issues and ask questions.

ZeroQL - C# GraphQL client adds fragments support

Stanislav Silin — Sat, 23 Jul 2022 09:44:00 +0000

In my previous article I introduce you to ZeroQL.
It is a C# "native" graphql client with a Linq-like interface with no compromises on the performance.
In this article, I want to present support for fragments.

What do fragments mean?

In the graphql, you have to specify every field that you want to fetch from the server like that:

query GetMe {
    me {
        id
        firstName
        lastName
    }
}

It is fine if you need to do it only once, but, in some cases, you may want to get the same set of fields again and again. It may become too verbose:

query GetMeAndFriend($friendId: Int!) {
    me {
        id
        firstName
        lastName
    }
    user(id: $friendId) {
        id
        firstName
        lastName
    }
}

To make life easier, GraphQL has support fragments. They allow to define a set of fields and then reuse them when needed.

fragment UserFields on User {
    id
    firstName
    lastName
}

query GetMeAndFriend($friendId: Int!) {
    me {
        ...UserFields
    }
    user(id: $friendId) {
        ...UserFields
    }
}

I guess the idea is clear. Now let's see how we can create fragments in side the C#.

We will work with next GraphQL schema:

schema {
  query: Query
  mutation: Mutation
}

type Query {
  me: User!
  user(id: Int!): User
}

type Mutation {
  addUser(firstName: String!, lastName: String!): User!
}

type User {
  id: Int!
  firstName: String!
  lastName: String!
  role: Role!
}

type Role {
  id: Int!
  name: String!
}

How to setup the ZeroQL you can find in this article.

The GetMeAndFriend GraphQL query from the sample above looks like that:

var variables = new { FriendId = 2 };
var response = await client.Query(
    variables, 
    static (i, q) => new
    {
        Me = q.Me(o => new { o.Id, o.FirstName, o.LastName }),
        User = q.User(i.FriendId, o => new { o.Id, o.FirstName, o.LastName }),
    });

Console.WriteLine(response.Query); // query ($friendId: Int!) { me { id firstName lastName }  user(id: $friendId) { id firstName lastName } }
Console.WriteLine(response.Data); //  { Me = { Id = 1, FirstName = Jon, LastName = Smith }, User = { Id = 2, FirstName = Ben, LastName = Smith } }

Let's move user fields into a fragment. For this, we need a user model and an extension method::

public record UserModel
{
    public int Id { get; set; }
    public string FirstName { get; set; }
    public string LastName { get; set; }
}

public static class UserFragments
{
    [GraphQLFragment]
    public static UserModel AsUserModel(this User user)
    {
        return new UserModel
        {
            Id = user.Id,
            FirstName = user.FirstName,
            LastName = user.LastName
        };
    }
}

Now we can rewrite the query like that:

var variables = new { FriendId = 2 };
var response = await client.Query(
    variables, 
    static (i, q) => new
    {
        Me = q.Me(o => o.AsUserModel()),
        User = q.User(i.FriendId, o => o.AsUserModel()),
    });

Console.WriteLine(response.Query); // query ($friendId: Int!) { me { id firstName lastName }  user(id: $friendId) { id firstName lastName } }
Console.WriteLine(response.Data); // { Me = UserModel { Id = 1, FirstName = Jon, LastName = Smith }, User = UserModel { Id = 2, FirstName = Ben, LastName = Smith } }

And everything works as expected. If you look at the generated GraphQL query, you will see that, strictly speaking, it is not a "graphql fragment." It is more of a sub-query that is inserted into a final query. So, we can go further and combine multiple queries like that:

var variables = new { FriendId = 2 };
var response = await client.Query(
    variables, 
    static (i, q) => q.GetMeAndFriend(i.FriendId));

Console.WriteLine(response.Query); // query ($friendId: Int!) { me { id firstName lastName }  user(id: $friendId) { id firstName lastName } }
Console.WriteLine(response.Data); // MeAndFriendResponse { Me = UserModel { Id = 1, FirstName = Jon, LastName = Smith }, Friend = UserModel { Id = 2, FirstName = Ben, LastName = Smith } }

// ...

public record MeAndFriendResponse
{
    public UserModel Me { get; set; }
    public UserModel Friend { get; set; }
}

public static class QueryFragments
{
    [GraphQLFragment]
    public static MeAndFriendResponse GetMeAndFriend(this Query query, int friendId)
    {
        return new MeAndFriendResponse
        {
            Me = query.Me(o => o.AsUserModel()),
            Friend = query.User(friendId, o => o.AsUserModel())
        };
    }
}

And again, everything works as expected.

Limitations

There is one thing that can make life a bit complicated. The source generator looks through the source code to generate the query. It also needs to look into every sub-query, which is fine until it is defined in another assembly/project. In this case, the source generator can't dig into it because the source code for such assemblies is not available. As a result, we can't generate a query for them. If we want to make the fragment work, it should be defined in the same assembly that we call the client.Query or client.Mutation methods. This requirement definitely can break some workflows and expectations. At the same time, how often do you need to split your SQL queries into different assemblies? This happens, but not so often. In the worst-case scenario, you must copy-paste fragments from one project to another.

Again, it doesn't mean this issue can not be fixed in the future. I have some ideas on how to solve it, but at the moment, it is just ideas with tricky implementation. Meanwhile fight is not over.

Performance

I have said that the ZeroQL has excellent performance. But how excellent is it?
The repository contains a benchmark. It compares raw graphql request, StrawberryShake, and ZeroQL.

The short version looks like that:

[Benchmark]
public async Task<string> Raw()
{
    var rawQuery = @"{ ""query"": ""query { me { firstName }}"" }";
    var response = await httpClient.PostAsync("", new StringContent(rawQuery, Encoding.UTF8, "application/json"));
    var responseJson = await response.Content.ReadAsStreamAsync();
    var qlResponse = JsonSerializer.Deserialize<JsonObject>(responseJson, options);

    return qlResponse["data"]["me"]["firstName"].GetValue<string>();
}

[Benchmark]
public async Task<string> StrawberryShake()
{
    var firstname = await strawberryShake.Me.ExecuteAsync(); // query { me { firstName }}
    return firstname.Data.Me.FirstName;
}

[Benchmark]
public async Task<string> ZeroQL()
{
    var firstname = await zeroQLClient.Query(static q => q.Me(o => o.FirstName));

    return firstname.Data;
}

Here results:


BenchmarkDotNet=v0.13.1, OS=macOS Monterey 12.4 (21F79) [Darwin 21.5.0]
Apple M1, 1 CPU, 8 logical and 8 physical cores
.NET SDK=6.0.302
  [Host]     : .NET 6.0.7 (6.0.722.32202), Arm64 RyuJIT
  DefaultJob : .NET 6.0.7 (6.0.722.32202), Arm64 RyuJIT

Method	Mean	Error	StdDev	Gen 0	Allocated
Raw	182.5 μs	1.07 μs	1.00 μs	2.4414	5 KB
StrawberryShake	190.9 μs	0.74 μs	0.69 μs	3.1738	6 KB
ZeroQL	185.9 μs	1.39 μs	1.30 μs	2.9297	6 KB

As you can see, the Raw method is the fastest.
The ZeroQL method is a bit faster than the StrawberryShake method.
But in absolute terms, all of them are pretty much the same. The difference is negligible.

Summary

So, with the ZeroQL you can forget about the graphql and just use a fully typed Linq-like interface. It will have little effect on performance. In the future, I plan to figure out how to generate queries for fragments defined in another assembly and think about how to make the initial setup more straightforward.

Thank you for your time!
If you like what I am working on. Please, give a start to the Github repository so more people can see it.

Links

Github
NuGet

ZeroQL - C# friendly GraphQL

Stanislav Silin — Sat, 16 Jul 2022 08:39:44 +0000

Nowadays, GraphQL has become a more and more popular technology for building web servers. At the same time, the C# lacks a "native" client for it. Under "native" I mean an ability to build queries inside the C# without the need to write raw GraphQL and be sure that if your project could compile, it would work as expected.

The idea

I was looking for such a tool continuously, and the closes what I managed to find was Strawberry Shake. It requires you to write a raw GraphQL. At the same time, it will generate all the necessary wrappings for C#, and you will have a nice type-safe API to work with.

I have been using it a lot but wanted to have something even more native to simplify integration between different app parts.
My goal is to have a public interface that allows to execute queries like that:

var response = await client.Query(q => q.User(42, user => new { user.Id, user.FirstName, user.LastName });

It will be equivalent to following GraphQL query:

query { user(id: 42) { id firstName lastName } }

ZeroQL

After a few weeks of digging, I made a library that does exactly that.

Meet the ZeroQL! It is C# friendly GraphQL client with a Linq-like interface and excellent performance equivalent to a simple HTTP call.

Let's see it in action with an example. Let's suppose that we have a local HotChocolate server on localhost:10000, and it serves the following GraphQL schema:

schema {
  query: Query
  mutation: Mutation
}

type Query {
  me: User!
  user(id: Int!): User
}

type Mutation {
  addUser(firstName: String!, lastName: String!): User!
}

type User {
  id: Int!
  firstName: String!
  lastName: String!
  role: Role!
}

type Role {
  id: Int!
  name: String!
}

Initial setup

Now, let's create a console app that can access it. We can do it with the next commands:

dotnet new console -o QLClient # create console app
cd QLClient # go to the project folder
curl http://localhost:10000/graphql?sdl > schema.graphql # fetch graphql schema from server
dotnet new tool-manifest # create manifest file to track NuGet tools
dotnet tool install ZeroQL.CLI # add ZeroQL.CLI NuGet tool
dotnet add package ZeroQL # add ZeroQL NuGet package
dotnet zeroql generate --schema .\schema.graphql --namespace TestServer.Client --client-name TestServerGraphQLClient --output Generated/GraphQL.g.cs # generate wrappers from the schema.graphql

The last step can be placed in a separate target inside the csproj file to ensure we have the latest changes from schama.graphql. It may look like that:

<Target Name="GenerateQLClient" BeforeTargets="BeforeCompile">
    <Exec Command="dotnet zeroql generate --schema .\schema.graphql --namespace TestServer.Client --client-name TestServerGraphQLClient --output Generated/GraphQL.g.cs" />
</Target>

It may look a bit complicated at first glance, but don't be afraid we need to do it only once.

The initial setup is ready, and we can execute our first query. Let's modify the Program.cs to look like that:

var httpClient = new HttpClient();
httpClient.BaseAddress = new Uri("http://localhost:10000/graphql");

var client = new TestServerGraphQLClient(httpClient);

var response = await client.Query(static q => q.Me(o => new { o.Id, o.FirstName, o.LastName }));

Console.WriteLine($"GraphQL: {response.Query}"); // GraphQL: query { me { id firstName lastName } }
Console.WriteLine($"{response.Data.Id}: {response.Data.FirstName} {response.Data.LastName}"); // 1: Jon Smith

As you can see, the workflow is straightforward. Create the GraphQL client, write a query in C#, execute it and get results. Let's look at this sample in detail.

How it works

The class TestServerGraphQLClient is generated via ZeroQL.CLI. It has a method, Query, that accepts a "graphql" lambda*(not expression)*. This "graphql" lambda takes one argument of type Query. It generated too. Then the source generator will look inside the lambda, analyzes, and transforms it into the corresponding GraphQL. After that, it is placed in a "special" dictionary. This dictionary contains the stringified lambda and the associated graphql. If you look at the Query method itself, you will see that it has a hidden argument queryKey:

public async Task<GraphQLResult<TResult>> Query<TResult>(
    Func<TQuery, TResult> query,
    [CallerArgumentExpression("query")] string queryKey = null!)
{
    return await Execute<Unit, TQuery, TResult>(OperationKind.Query, null, null, (i, q) => query(q), queryKey);
}

The CallerArgumentExpression is a new feature of C# 10. It allows us to get a stringified representation of the expression that was passed inside the argument. In our case are looking for the argument query which is equal to static q => q.Me(o => new { o.Id, o.FirstName, o.LastName }) as a result the argument queryKey will contain hardcoded string "static q => q.Me(o => new { o.Id, o.FirstName, o.LastName })" — that exact representation that required to get the corresponding graphql from the "special" dictionary. As a result, we always know what graphql we need for each call. The crucial thing here is that the graphql is generated at compile-time. So, there is nothing to do at runtime except executing the HTTP call. As a result, we have zero overhead at runtime.

Another important thing is that the "graphql" lambda must be a static one. There are two reasons for that. First, analyzing it via the source generator is much easier because there are no outside-scope variables that can make things complicated. Second, if you plan to have graphql variables like that:

var variables = new { Id = 1 };
var response = await client.Query(variables, static (i, q) => q.User(i.Id, o => new { o.Id, o.FirstName, o.LastName }));

It is the simplest way to ensure that all inputs are analyzed. With such an approach, we have them as parameters and can serialize them to add to the request.

Supported features

Now let's see what features are supported at the moment.
For exmaple, we can get deeply nested fields:

var variables = new { Id = 1 };
var response = await client.Query(
    variables,
    static (i, q) => q
        .User(i.Id,
            o => new
            {
                o.Id,
                o.FirstName,
                o.LastName,
                Role = o.Role(role => role.Name)
            }));

Console.WriteLine($"GraphQL: {response.Query}"); // GraphQL: query GetUserWithRole($id: Int!) { user(id: $id) { id firstName lastName role { name }  } }
Console.WriteLine($"{response.Data.Id}: {response.Data.FirstName} {response.Data.LastName}, Role: {response.Data.Role}"); // 1: Jon Smith, Role: Admin

Also, touch multiple fields at the same time:

var variables = new { Id = 1 };
var response = await client.Query(
    variables,
    static (i, q) => new
    {
        MyFirstName = q.Me(o => o.FirstName),
        User = q.User(i.Id,
            o => new
            {
                o.FirstName,
                o.LastName,
                Role = o.Role(role => role.Name)
            })
    });

Console.WriteLine($"GraphQL: {response.Query}"); // GraphQL: query GetUserWithRole($id: Int!) { me { firstName }  user(id: $id) { firstName lastName role { name }  } }
Console.WriteLine($"Me: {response.Data.MyFirstName}, User: {response.Data.User.FirstName} {response.Data.User.LastName}, Role: {response.Data.User.Role}"); // Me: Jon, User: Jon Smith, Role: Admin

Execute mutations:

var response = await client.Mutation(m => m.AddUser("Jon", "Doe", o => o.Id));

Console.WriteLine($"GraphQL: {response.Query}");
Console.WriteLine($"Id: {response.Data}");

Limitations

The biggest limitations will be the fact that you can run this library only with .Net 6. It is required because of the CallerArgumentExpression attribute I mentioned earlier. Maybe there is a trick to fix it, but I have not spent much time on it.
Also, the library is in the early stages of development. Some features are not implemented yet.
For example:

fragments
@defer attribute
@stream attribute
subscriptions

Some of them, I would say, are really important, like fragments. At the same time, I thought it would be nice to share what I have done and get some feedback. It may definitely help to guide future developments.

Links

Github

NuGet

Making Dapper and JSON friends

Stanislav Silin — Mon, 06 Dec 2021 18:03:54 +0000

Let's speak about improvements that we can bring to the Dapper. Improvements in the 'quality of life' category, to be precise. I think that everyone, who had some experience with SQL in the past, had a situation like that. You have a model that you want to show to the user. The data is stored in the SQL database. The model itself is straightforward from the C# perspective.

Here is it:

class User 
{
    public int Id { get; set;}
    public string Login { get; set;}
    public PhoneNumber[] Phones { get; set;}
}

class PhoneNumber 
{
    public string Number { get; set; }
    public PhoneNumberKind Kind { get; set; } 
}

enum PhoneNumberKind
{
    Office,
    Mobile,
    Home
}

It consists of a few fields and an array inside. As you may guess, the main problem will be the array because SQL doesn't have an easy way to put a list of items in the column. So, to fill the model, we will need to execute multiple queries or play around with a SQL reader. Still, both cases require additional manipulation with numerous rows to construct a model.

Sample with multiple requests:

var usersData = await connection.QueryAsync<(int Id, string Login)>("select Id, Login from Users");

var phoneNumbersData = await connection.QueryAsync<(int UserId, string Number, PhoneNumberKind Kind)>(
    "select UserId, Number, Kind from PhoneNumbers where UserId in @UserIds", new { UserIds = usersData.Select(o => o.Id)});

var phoneNumbersByUserId = phoneNumbersData
    .GroupBy(o => o.UserId)
    .ToDictionary(o => o.Key, o => o.ToArray());

var users = usersData
    .Select(o => 
        new User() 
        { 
            Id = o.Id, 
            Login = o.Login, 
            PhoneNumbers = phoneNumbersByUserId.ContainsKey(o.Id) ? 
                phoneNumbersByUserId[o.Id]
                    .Select(phone => new PhoneNumber 
                        { 
                            Number = phone.Number, 
                            Kind = phone.Kind 
                        })
                    .ToArray() :
                Array.Empty<PhoneNumber>()
        })
    .ToArray();

As for me, such a solution looks clunky and has huge potential for mistakes. Also, in this sample, we are keeping the whole result set in the memory. That is not great either. To avoid it, we need to introduce batching. At the same time, we may need to add more joins. All of that makes logic even more complex.

Making Dapper and JSON friends

At this point, we can remember the fact that the modern SQL databases have support for JSON. The MSSQL server, for example, can execute selectors and pack results into columns as a JSON. In our case, the query can be simplified to look like that:

select 
    Id,
    Login,
    (select UserId, Number, Kind from PhoneNumbers where UserId = u.Id FOR JSON PATH) as PhonesJson
from Users u

The result of the query will be next:

Id	Login	PhonesJson
16	Karita_Ringo	[{"UserId":16,"Number":"3377787","Kind":2}]
17	Chiquia_Dud	NULL
18	Caprice_Hugibert	[{"UserId":18,"Number":"8454027","Kind":0}]
19	Pat_Tedie	[{"UserId":19,"Number":"4646231","Kind":1}]
20	Vally_Fitzgerald	[{"UserId":20,"Number":"1836548","Kind":2}]
21	Jasmina_Xerxes	NULL
22	Kristy_Nathaniel	[{"UserId":22,"Number":"7018212","Kind":1}]
23	Farica_Ives	[{"UserId":23,"Number":"0874725","Kind":2}]
24	Clementine_Gun	NULL
25	Jerry_Whit	[{"UserId":25,"Number":"0013362","Kind":0}]

Now lets fill the User model based on the new query:

var usersData = await connection.QueryAsync<(int Id, string Login, string PhonesJson)>(@"
    select 
        Id,
        Login,
        (select UserId, Number, Kind from PhoneNumbers where UserId = u.Id FOR JSON PATH) as PhonesJson
    from Users u");

var users = usersData
    .Select(o => 
        new User 
        { 
            Id = o.Id, 
            Login = o.Login, 
            PhoneNumbers = !string.IsNullOrEmpty(o.PhonesJson) ? 
                JsonSerializer.Deserialize<PhoneNumber[]>(o.PhonesJson) :
                Array.Empty<PhoneNumber>()
        })
    .ToArray();

Done! The logic flow now is much simple. At the same time, this approach allows us to enable un-buffered mode and fetch rows in batches. In some scenarios, it can be a life-saving feature. We can start processing much earlier and free memory from processed rows. And all of this without the need to build complex logic.

Making Dapper and JSON even closer friends

Can we make our solution even better? Yes, we can. The Dapper has a way to add custom user-defined types. So, what if we can create a type like Json<T> and use it as a column type? It can achieve it via the SqlMapper.TypeHandler. Lets create our JsonTypeHandler<T>.

For System.Text.Json it will look like that:

public class JsonTypeHandler<T> : SqlMapper.TypeHandler<Json<T>>
{
    public override void SetValue(IDbDataParameter parameter, Json<T> value)
    {
        parameter.Value = JsonSerializer.Serialize(value.Value);
    }

    public override Json<T> Parse(object value)
    {
        if (value is string json)
        {
            return new Json<T>(JsonSerializer.Deserialize<T>(json));
        }

        return new Json<T>(default);
    }
}

If we want to use the Json<T> with PhoneNumber[] then we need to add it to SqlMapper like that:

SqlMapper.AddTypeHandler(new JsonTypeHandler<PhoneNumber[]>());

Now, lets have a look at updated sample:

var usersData = await connection.QueryAsync<(int Id, string Login, Json<PhoneNumber[]>? PhoneNumbers)>(@"
    select 
        Id,
        Login,
        (select UserId, Number, Kind from PhoneNumbers where UserId = u.Id FOR JSON PATH) as PhoneNumbers
    from Users u");

var users = usersData
    .Select(o => 
        new User 
        { 
            Id = o.Id, 
            Login = o.Login, 
            PhoneNumbers = o.PhoneNumbers?.Value ?? Array.Empty<PhoneNumber>()
        })
    .ToArray();

Such an approach allows us to expose our intention about the query more clearly. At the same time, keep the simplicity of the source code.

But there is an issue. If we want to use other Json<T> of different types like Json<User[]>, Json<EmailDetails>, Json<Role> and so on. We will need to manually add type handlers to SqlMapper for each of them. Like that:

SqlMapper.AddTypeHandler(new JsonTypeHandler<User[]>());
SqlMapper.AddTypeHandler(new JsonTypeHandler<EmailDetails>());
SqlMapper.AddTypeHandler(new JsonTypeHandler<Role>());

That's not great. It completely ruins the ease of use. I have tried to find a way to register all types at once, but the Dapper documentation didn't provide any way to achieve such behaviour. So, the only way is to add type handlers of each type. It would be a disaster, but it is the C#! It has a lot of tricks up his sleeves!

The trick

The trick that we will use is source generators! By itself, it is like an extension for the Roslyn compiler. It allows to analyze the existing source code and, based on it, generate a new one. So, the idea is simple. Let's look for usages of Json<T> and create a module initializer(another new trick) that will add all required types to SqlMapper auto-magically.

The source generator consists of the syntax receiver and the source generator. Our syntax receiver will be really stupid. Its single task will be to find the Json<T>.

It looks like that:

public class DapperSourceGeneratorSyntaxReceiver : ISyntaxReceiver
{
    public List<GenericNameSyntax> Types { get; } = new();

    public void OnVisitSyntaxNode(SyntaxNode syntaxNode)
    {
        // select all generic type usages of Json<>
        if (syntaxNode is GenericNameSyntax { Identifier.ValueText: "Json", } type)
        {
            Types.Add(type);
        }
    }
}

The source generator is a bit more complex, but the basic idea should be clear.


    [Generator]
    public class DapperJsonSourceGenerator : ISourceGenerator
    {
        public void Initialize(GeneratorInitializationContext context)
        {
            // register our syntax reciver 
            context.RegisterForSyntaxNotifications(() => new DapperSourceGeneratorSyntaxReceiver());
        }

        public void Execute(GeneratorExecutionContext context)
        {
            if (context.SyntaxReceiver is not DapperSourceGeneratorSyntaxReceiver syntaxReceiver)
            {
                return;
            }

            try
            {
                // neccesary to make sure that it is our Json<T>
                var jsonType = context.Compilation.GetTypeByMetadataName("Dapper.Json.Json`1");

                var types = syntaxReceiver.Types
                    .Select(o =>
                    {
                        var semanticModel = context.Compilation.GetSemanticModel(o.SyntaxTree);
                        var type = semanticModel.GetTypeInfo(o);
                        if (type.Type is INamedTypeSymbol namedTypeSymbol &&
                            namedTypeSymbol.ConstructedFrom.Equals(jsonType))
                        {
                            // extracting the generic type
                            return namedTypeSymbol.TypeArguments.First();
                        }

                        return null;
                    })
                    .Where(o => o != null)
                    .Distinct(SymbolEqualityComparer.Default)
                    .ToArray();

                // create a module initializer and add all types to SqlMapper
                var source = @$"using System;

namespace Dapper.Json
{{
    public static class DapperJsonModuleInitializer
    {{
        [global::System.Runtime.CompilerServices.ModuleInitializer]
        public static void Init()
        {{
{types.Select(o => $@"            SqlMapper.AddTypeHandler(new JsonTypeHandler<{o.ToGlobalName()}>());").JoinWithNewLine()}
        }}
    }}
}}
";

                context.AddSource("Dapper.Json.g.cs", source.ToSourceText());
            }
            catch (Exception e)
            {
                // some error handeling to simplify source generator debuging experiance
                context.AddSource("Dapper.Json.Error.g.cs", @$"

namespace Dapper.Json
{{
    public static class DapperJsonError
    {{
        public static string Error = ""{e.Message}"";
    }}
}}");
            }
        }
    }

The final module initializer may look like that:

using System;

namespace Dapper.Json
{
    public static class DapperJsonModuleInitializer
    {
        [global::System.Runtime.CompilerServices.ModuleInitializer]
        public static void Init()
        {
            SqlMapper.AddTypeHandler(new JsonTypeHandler<global::PhoneNumber[]>());
            SqlMapper.AddTypeHandler(new JsonTypeHandler<global::User[]>());
            SqlMapper.AddTypeHandler(new JsonTypeHandler<global::EmailDetails>());
            SqlMapper.AddTypeHandler(new JsonTypeHandler<global::Role>());
        }
    }
}

Done! Whenever we use the Json<T>, it will automatically be added to SqlMapper.

How to use it

The complete instruction you can find at the repository on github. There is nothing complicated. You need to install two NuGet packages, and you are ready to go.

That is all for today. Feel free to leave a comment or create an issue on GitHub.

Thanks for your time!

Improving C# with TypeScript. KeyOf

Stanislav Silin — Sat, 02 Oct 2021 13:59:19 +0000

In my previous article was presented a way how you can improve reflection performance in some scenarios. Now I want to show how you can make it safer. The source of inspiration will be TypeScript. The keyof keyword to be precise.

What `keyof` does in TypeScript

The keyof keyword allows you to declare a special enum-like type containing only the associated type's property names. Let's have a look at the folloving example:

interface User {
    firstName: string,
    lastName: string
}

function dotIt<T>(value: T, propertyName: keyof T) : any {
    return value[propertyName]
}

let user: User = { firstName: 'Jon', lastName: 'Smith' }
let firstName = dotIt(user, 'firstName') // no error
let lastName = dotIt(user, 'lastName') // no error
let missingProperty = dotIt(user, 'test') // error because there is not property 'test'

It is a convenient way to make sure that nothing breaks when trying to get property value by property name.

The `keyof` in `C#`

Now let's build an identical sample for C# utilizing the AOT.Reflection library from the previous article. It looks like that;

using Apparatus.AOT.Reflection;

var user = new User { FirstName = "Jon", LastName = "Smith" };
var firstName = DoIt(user, "FirstName");
var lastName = DoIt(user, "LastName");
var missingProperty = DoIt(user, "Test");

object DoIt<T>(T value, string propertyName)
{
    var property = value.GetProperties()[propertyName];
    if (property.TryGetValue(value, out var propertyValue))
    {
        return propertyValue;
    }

    return null;
}

class User
{
    public string FirstName { get; set; }
    public string LastName { get; set; }
}

As you may guess, everything will compile and we will get an exception at runtime. If we investigate further, we will find out that C# doesn't have any way to express the idea like that. It wasn't new for me. First of all the TypeScript is the script language that works on top of JavaScript. The keyof looks wonderful feature in this context. At the same time, the C# is the strongly typed language where you can't just take a value by property name so easily. But if you take to account libraries like the AOT.Reflection then you can start wondering 'what if?' and 'why not?'

Meet `KeyOf<T>`

After a brief investigation, I found that adding such a concept to C# will be relatively easy. So, I started working on it because it would be a nice addition for AOT.Reflection in multiple ways.
Firstly, it makes your code safer because it allows you to validate it during the compilation stage.
Secondly, if you read the article about AOT.Reflection, you know that it has some limitations while interacting with the generics. The KeyOf<T> allows us to overcome some of them. For example, we have no idea what type to use in the generic method because it is just a T. Also, there is no indication in the method signature that can help figure out a reflection inside. With KeyOf<T> we have such indication. Let's have a look at how to use it by rewriting the previous sample.

using Apparatus.AOT.Reflection;

var user = new User { FirstName = "Jon", LastName = "Smith" };
var firstName = DoIt(user, "FirstName"); // no error
var lastName = DoIt(user, "LastName"); // no error
var missingProperty = DoIt(user, "Test"); // compilation error


object DoIt<T>(T value, KeyOf<T> propertyName)
{
    var property = value.GetProperties()[propertyName];
    if (property.TryGetValue(value, out var propertyValue))
    {
        return propertyValue;
    }

    return null;
}

class User
{
    public string FirstName { get; set; }
    public string LastName { get; set; }
}

The only part that changed is the signature of the method. Now it expects KeyOf<T> as a property name. This change allows us to add indications about the intention to use the reflection inside. So, we can run the source generator on it, and, at the same, it is the obvious place to analyze with the Roslyn analyzer. As a result, we can find all invocations and report a compilation error if you pass the wrong name.

Right now, the analyzer checks of the next case:

string as keyof:

DoIt(user, "FirstName"); // no error
DoIt(user, "Test"); // compilation error

nameof as keyof:

DoIt(user, nameof(User.FirstName)); // no error
DoIt(user, nameof(User)); // compilation error

variable as keyof:

var propertyName = "FirstName";
DoIt(user, propertyName); // compilation error, can't be validated at compile time

if(KeyOf<User>.TryParse(propertyName, out var key))
{
    DoIt(user, key); // no error
}

const as keyof:

const string propertyName = "FirstName";
DoIt(user, propertyName); // no error, can be validated at compile time
if(KeyOf.TryParse(propertyName, out var key))
{
    DoIt(user, key); // no error
}

It is possible that I forgot about something. So, if you know how to break it, please create a ticket!

How to use it in your project

To make it work, just install the NuGet package Apparatus.AOT.Reflection:

dotnet add package Apparatus.AOT.Reflection

Then you will have access to aot reflection and KeyOf<T> itself. The reflection is not the only place where you can use it. For example, it works nicely when you need to generate some sql for tools like Dapper, when you need to serialize something, managing bindings in WPF, Xamarin, and AvaloniaUI.

Conclusion

When I started working on the KeyOf<T> I was fascinated by the abilities that Roslyn analyzers and source generators can give you and how easily you can add new concepts with them. Stay tuned. The name Improving C# with TypeScriptwas selected for a reason. More TypeScript features are coming to C# soon.

Links

Github, Nuget

The end

ZeroIoC - IoC container powered via Source Generators

Stanislav Silin — Wed, 22 Sep 2021 18:31:08 +0000

The main goal of the ZeroIoC is to provide IoC for AOT platforms such as Xamarin, Unity, and Native AOT. It is powered by Roslyn Source Generator as a result executed on build and doesn't require Reflection.Emit to function.

Get Started

Install the NuGet package ZeroIoC to your project.

dotnet add package ZeroIoC

Declare your container that is inherited from ZeroIoCContainer as a partial class


    public interface IUserService
    {
    }

    public class UserService : IUserService
    {
        public Guid Id { get; } = Guid.NewGuid();

        public UserService(Helper helper)
        {
        }
    }

    public class Helper
    {
        public Guid Id { get; } = Guid.NewGuid();
    }

    public partial class Container : ZeroIoCContainer
    {
        protected override void Bootstrap(IZeroIoCContainerBootstrapper bootstrapper)
        {
            bootstrapper.AddSingleton<Helper>();
            bootstrapper.AddTransient<IUserService, UserService>();
        }
    }

Use your container:

  var container = new Container();
  var userService = container.Resolve<IUserService>();

How it works

The NuGet is deployed with the source generator and analyzer. Then it looks for class declarations that are inherited from the ZeroIoCContainer. Inside the generator looks for the ZeroIoCContainer.Bootstrap method. Based on its content, the source generator will generate another part of a partial class. For the case described above, it will look like that(skipping the performance magic):


public partial class Container
{

    public Container()
    {
        Resolvers = Resolvers.AddOrUpdate(typeof(global::Helper), new SingletonResolver(static resolver => new global::Helper()));
        Resolvers = Resolvers.AddOrUpdate(typeof(global::IUserService), new TransientResolver(static resolver => new global::UserService(resolver.Resolve<global::Helper>())));
    }

    protected Container(ImTools.ImHashMap<Type, InstanceResolver> resolvers, ImTools.ImHashMap<Type, InstanceResolver> scopedResolvers, bool scope = false)
        : base(resolvers, scopedResolvers, scope)
    {
    }

    public override IZeroIoCResolver CreateScope()
    {
        var newScope = ScopedResolvers
            .Enumerate()
            .Aggregate(ImHashMap<Type, InstanceResolver>.Empty, (acc, o) => acc.AddOrUpdate(o.Key, o.Value.Duplicate()));

        return new Container(Resolvers, newScope, true);
    }
}

It is pretty simple stuff. The logic is based on a dictionary with Type as a key and instance resolver as a value. Such a class is generated for each separate class declaration, and because there is no static logic, you can safely define as many containers as you like.

Limitations

Let's talk about the ZeroIoCContainer.Bootstrap method. It is not an ordinary method. It is a magic one. It allows you to define the relations between interface and implementation, but the .net runtime will never execute it.

The ZeroIoCContainer.Bootstrap is just a declaration that will be parsed by source generation, and based on it, the mapping will be generated.
It means that there is no point to use statements like that:

 public partial class Container : ZeroIoCContainer
    {
        protected override void Bootstrap(IZeroIoCContainerBootstrapper bootstrapper)
        {
            if(Config.Release)
            {
              bootstrapper.AddSingleton<IHelper, ReleaseHelper>();
            }
            else 
            {
              bootstrapper.AddSingleton<IHelper, DebugHelper>();
            }

            bootstrapper.AddTransient<IUserService, UserService>();
        }
    }

All of them will be just ignored.
To prevent the bunch of WTF situations(and introduce a new one), I added a special analyzer that will warn you about it if you forget.

But If you want to do something at runtime, you can do it like that:

var container = new Container();
if(Config.Release)
{
    container.AddInstance<IHelper>(new ReleaseHelper());
}
else 
{
    container.AddInstance<IHelper>(new DebugHelper());
}

var userService = container.Resolve<IUserService>();

Such an approach doesn't use any reflection underhood and can be safely used inside the AOT environment.

Features

I would say it is in the MVP stage. Under MVP, I mean that the set of features is big enough to be helpful in real projects.
This set contains:

Multiple IoC containers can be active at the same time.
Support for the singleton, scoped, and transient lifetimes => basic things that cover 99% of all needs.
Powered by source generation to avoid reflection and Reflection.Emit => you can use it inside the AOT Xamarin/Unity app.
Fast enough, with minimal overhead => the end-user of the Xamarin app will not notice a difference.

About the performance. There are two kinds of it. Performance in "hot runtime" and startup performance - «cold start.» As contestants, I selected the next IoCs:

Microsoft.Extensions.DependencyInjection — default IoC in the Asp.Net Core
Grace — IoC that takes first places in different benchmarks in the internet

I will not show the complete source code for benchmarks. You can find it here: github.com/byme8/ZeroIoC

In the beginning, let's look at performance in «hot runtime» — the benchmark measures time required to resolve an instance. All benchmarks are recorded via BenchmarkDotNet and have a following look:

[Benchmark]
public IUserService ZeroTransient()
{
    return (IUserService)_zeroioc.Resolve(typeof(IUserService));
}

And we have the next results:


// * Summary *

BenchmarkDotNet=v0.13.0, OS=Windows 10.0.19043.1165 (21H1/May2021Update)
11th Gen Intel Core i7-11700KF 3.60GHz, 1 CPU, 16 logical and 8 physical cores
.NET SDK=6.0.100-preview.7.21379.14
  [Host]     : .NET 5.0.7 (5.0.721.25508), X64 RyuJIT
  DefaultJob : .NET 5.0.7 (5.0.721.25508), X64 RyuJIT


|             Method |      Mean |     Error |    StdDev |  Gen 0 | Gen 1 | Gen 2 | Allocated |
|------------------- |----------:|----------:|----------:|-------:|------:|------:|----------:|
|     GraceSingleton |  3.027 ns | 0.0026 ns | 0.0025 ns |      - |     - |     - |         - |
|      ZeroSingleton |  6.862 ns | 0.0056 ns | 0.0050 ns |      - |     - |     - |         - |
| MicrosoftSingleton | 12.575 ns | 0.0649 ns | 0.0542 ns |      - |     - |     - |         - |
|     GraceTransient | 42.975 ns | 0.1765 ns | 0.1474 ns | 0.0038 |     - |     - |      32 B |
|      ZeroTransient | 47.505 ns | 0.1450 ns | 0.1285 ns | 0.0038 |     - |     - |      32 B |
| MicrosoftTransient | 53.098 ns | 1.0928 ns | 1.2585 ns | 0.0038 |     - |     - |      32 B |

As we can see, Grace won in every case, but if we have check the Microsoft.Extensions.DependencyInjection our ZeroIoc is twice as fast. I was tinkering with the Grace to understand why it is so fast. It looks like the main advantage lies in Grace's having its custom-written dictionary. It allows to avoid a bunch of redundant method calls and that all. So, at the moment, I have decided to leave it as is. Maybe in the future, I will come back to it.

Now let's have a look at startup performance. This benchmark will include instantiation of the container and resolving the instance of a class.

Here are the results:

// * Summary *

BenchmarkDotNet=v0.13.0, OS=Windows 10.0.19043.1165 (21H1/May2021Update)
11th Gen Intel Core i7-11700KF 3.60GHz, 1 CPU, 16 logical and 8 physical cores
.NET SDK=6.0.100-preview.7.21379.14
  [Host]     : .NET 5.0.7 (5.0.721.25508), X64 RyuJIT
  DefaultJob : .NET 5.0.7 (5.0.721.25508), X64 RyuJIT


|           Method |         Mean |       Error |      StdDev |  Gen 0 |  Gen 1 | Gen 2 | Allocated |
|----------------- |-------------:|------------:|------------:|-------:|-------:|------:|----------:|
|      ZeroStartup |     168.5 ns |     0.76 ns |     0.63 ns | 0.0908 |      - |     - |     760 B |
| MicrosoftStartup |   2,442.5 ns |     7.26 ns |     6.79 ns | 0.8392 | 0.0153 |     - |   7,040 B |
|     GraceStartup | 294,460.6 ns | 1,884.45 ns | 1,762.72 ns | 3.9063 | 1.9531 |     - |  33,551 B |

In this case, the ZeroIoc is much faster than other candidates. 10x times faster than Microsoft.Extensions.DependencyInjection and more than 1000x times faster than the Grace. It happens because ZeroIoC doesn't do any work at runtime to start working correctly. Everything was done at compile time.

I would say that such IoC container is not very useful for the asp.net core application right now. But Microsoft is working on the NativeAOT that will allow us to compile C# code to native binaries directly. The ZeroIoC can be handy in this scenario because it can work in the AOT environment without any limitations. Also, it is nice for Xamarin apps. If you want to improve the startup performance of your app, it is essential to use the AOT for android and iOS(you don't have another choice here) platforms, and the ZeroIoC will work as smoothly as possible there.

Thanks for your time!

Links: GitHub, NuGet

Reflection via source generators

Stanislav Silin — Tue, 14 Sep 2021 17:57:40 +0000

Lately, I have been experimenting with source generation and got an idea. What if I build a reflection via source generation. How will it differ from the default one? And I did it.

So, this library aims to create a subset of reflection that will be faster than the default one and will not break at the platforms with the AOT compilation support. The source generators will help us with that.

How to use

To make it work, you will need to install a NuGet package Apparatus.AOT.Reflection:

dotnet add package Apparatus.AOT.Reflection

Then you can use it like that:

public class User
{
    [Required]
    public string FirstName { get; set; }
    [Required]
    public string LastName { get; set; }
}

public static void Main()
{
    var user = new User();
    var properties = user.GetProperties().Values;
    foreach (var property in properties)
    {
        Console.WriteLine(property.Name);
    }
}

This sample will print the names of properties.

FirstName
LastName

Also, it works for enums too:


public enum UserKind 
{
    User,
    Admin
}

// ...

public static void Main()
{
    var values = EnumHelper.GetEnumInfo<UserKind>();
    foreach (var value in values)
    {
        Console.WriteLine(value.Name);
    }
}

You will see:

User
Admin

It does not end with the only property names. You can get property values and assigned attributes.

Here is an example:

var requiredProperties = _user
    .GetProperties()
    .Values
    .Where(o => o.Attributes.Any(attr => attr is RequiredAttribute))
    .ToArray();

foreach (var requiredProperty in requiredProperties)
{
    if (requiredProperty.TryGetValue(_user, out var value))
    {
        Console.WriteLine($"{requiredProperty.Name} => {value}");
    }
}

The same applies to enums too. Let have a look at the following sample:

public enum AccountKind
{
    [Description("User account")]
    User,
    [Description("Admin account")]
    Admin,
    [Description("Customer account")]
    Customer,
    [Description("Manager account")]
    Manager
}

// ...

var values = EnumHelper.GetEnumInfo<AccountKind>();
foreach (var value in values)
{
    var description = value.Attributes
        .OfType<DescriptionAttribute>()
        .First();

    Console.WriteLine($"{value.Name} => {description.Description}");
}

Performance

Let's imagine that we need to find a property with Required attribute and the name FirstName.
If it exists, then print the value of the property, otherwise return the empty string. The implementation will be messy because I don't want to measure the LINQ performance, but the overall idea must be clear.

Here is the source code with default reflection:

var type = _user.GetType();
var property = type.GetProperty(nameof(User.FirstName));

var required = false;
foreach (var o in property.GetCustomAttributes())
{
    if (o.GetType() == typeof(RequiredAttribute))
    {
        required = true;
        break;
    }
}

if (required)
{
    return (string)property.GetMethod?.Invoke(_user, null);
}

return string.Empty;

Here the source code with aot reflection:

var entries = _user.GetProperties();
var firstName = entries[nameof(User.FirstName)];

var required = false;
foreach (var o in firstName.Attributes)
{
    if (o is RequiredAttribute)
    {
        required = true;
        break;
    }
}

if (required)
{
    if (firstName.TryGetValue(_user, out var value))
    {
        return (string)value;
    }

    return string.Empty;
}

return string.Empty;

Here are the benchmark results:

BenchmarkDotNet=v0.13.1, OS=Windows 10.0.19043.1165 (21H1/May2021Update)
11th Gen Intel Core i7-11700KF 3.60GHz, 1 CPU, 16 logical and 8 physical cores
.NET SDK=6.0.100-preview.7.21379.14
  [Host]     : .NET 5.0.7 (5.0.721.25508), X64 RyuJIT
  DefaultJob : .NET 5.0.7 (5.0.721.25508), X64 RyuJIT


|        Method |        Mean |    Error |   StdDev |  Gen 0 | Allocated |
|-------------- |------------:|---------:|---------:|-------:|----------:|
|    Reflection | 1,758.91 ns | 2.714 ns | 2.406 ns | 0.1278 |   1,072 B |
| AOTReflection |    16.01 ns | 0.090 ns | 0.075 ns |      - |         - |

As you can see, the AOT.Reflection is significantly faster comparing to default reflection.

Now let's have a look at enums performance. Imagine that we have the enum value, and we need to get a description associated with it.
Here how it will look:

var attributes = _account.GetEnumValueInfo().Attributes;
for (int i = 0; i < attributes.Length; i++)
{
    var attribute = attributes[i];
    if (attribute is DescriptionAttribute descriptionAttribute)
    {
        return descriptionAttribute.Description;
    }
}

return "";

Here is the results:

|              Method |       Mean |     Error |    StdDev |  Gen 0 | Allocated |
|-------------------- |-----------:|----------:|----------:|-------:|----------:|
|        GetValuesAOT |   6.253 ns | 0.0394 ns | 0.0329 ns |      - |         - |
| GetValuesReflection | 734.563 ns | 2.3173 ns | 1.9351 ns | 0.0324 |     272 B |

And again, the AOT reflection works much faster.

The complete source code of benchmarks you can find here.

Limitations

I would recommend being careful when you try to use these APIs inside the generic methods because, at this point, there is no easy way to analyze them and identify the correct signatures. It means the source generation will not happen. As a result, we will have an error at runtime.
Let's have a look at the following sample:

public class Program
{
    public static string? GetDescription<T>(T enumValue)
        where T : Enum
    {
        return enumValue
            .GetEnumValueInfo()
            .Attributes
            .OfType<DescriptionAttribute>()
            .FirstOrDefault()
            ?.Description;
    }

    public static void Main()
    {
        var account = AccountKind.Admin;
        Console.WriteLine(GetDescription(account));
    }
}

We will have an exception if we run it because the source generator could not figure out the signatures. The type T is the mystery for it.
But we can fix it with a small trick:

public class Program
{
    private void DontCallMe()
    {
        EnumHelper.GetEnumInfo<AccountKind>();
    }

    public static string? GetDescription<T>(T enumValue)
        where T : Enum
    {
        return enumValue
            .GetEnumValueInfo()
            .Attributes
            .OfType<DescriptionAttribute>()
            .FirstOrDefault()
            ?.Description;
    }

    public static void Main()
    {
        var account = AccountKind.Admin;
        Console.WriteLine(GetDescription(account));
    }
}

Pay attention to the DontCallMe method. We do not have any intention to use it anywhere. It is here to help the source generator to analyze the source code. Now, if we run it, everything works as expected.
The same issue exists for the properties reflection, and we can use the same trick to avoid it.

Support

Right now, only public properties and enums are supported. Regarding the private members, I doubt them because they would ruin the performance, but we will see.

The end

Thank you for your time!

Links: Github, Nuget