graphql-dotnet — GraphQL Server Implementation for .NET

Introduction

graphql-dotnet is the most widely adopted open-source GraphQL library for the .NET ecosystem. It provides a complete implementation of the GraphQL specification, allowing developers to build GraphQL APIs using C# with both schema-first (SDL) and code-first approaches. The library integrates naturally with ASP.NET Core and supports dependency injection, middleware pipelines, and popular serialization frameworks.

What graphql-dotnet Does

• Implements the full GraphQL specification including queries, mutations, subscriptions, and introspection
• Supports both schema-first development using SDL strings and code-first using C# type classes
• Provides a middleware pipeline for field resolution, enabling cross-cutting concerns like authorization and caching
• Integrates with ASP.NET Core through a companion package for HTTP endpoint hosting
• Handles subscription operations over WebSocket with built-in transport support

Architecture Overview

graphql-dotnet is built around a document execution pipeline. Incoming query strings are parsed into a document AST, validated against the schema, and executed by resolving each field through registered field resolvers. The schema is constructed either from SDL with runtime wiring or from C# classes that inherit from ObjectGraphType. Field resolvers support async/await patterns natively. A middleware stack wraps field resolution, allowing behaviors like authorization checks, logging, and DataLoader integration to be applied declaratively. The serialization layer is pluggable, supporting System.Text.Json and Newtonsoft.Json.

Self-Hosting & Configuration

• Install via NuGet: dotnet add package GraphQL plus a serializer package
• Define schemas using SDL strings with Schema.For() or build them with C# classes extending ObjectGraphType
• Host as an ASP.NET Core endpoint using the GraphQL.Server.Transports.AspNetCore package
• Configure dependency injection to wire services into your field resolvers
• Enable subscriptions by adding the WebSocket transport middleware

Key Features

• Dual schema definition modes: SDL-first for rapid prototyping and code-first for full C# type safety
• Field middleware pipeline for authorization, validation, metrics, and custom cross-cutting logic
• Built-in complexity analysis to reject overly expensive queries before execution
• DataLoader integration for batching and caching data fetcher calls across the query tree
• Subscription support over WebSocket with configurable transport and serialization

Comparison with Similar Tools

• Hot Chocolate — a newer .NET GraphQL server with a different API surface and built-in filtering/sorting; graphql-dotnet has a longer track record and larger community
• graphql-java — the JVM equivalent; graphql-dotnet serves the same role for the .NET ecosystem
• graphql-js — the JavaScript reference implementation; graphql-dotnet follows similar patterns adapted for C# idioms
• Strawberry (Python) — a Python GraphQL library using dataclasses; graphql-dotnet uses C# classes and attributes
• Juniper (Rust) — Rust GraphQL with macro-driven types; graphql-dotnet uses runtime type registration and reflection

FAQ

Q: Should I use graphql-dotnet or Hot Chocolate? A: Both are production-ready. graphql-dotnet has been around longer and has a large community. Hot Chocolate offers a more modern API with built-in features like filtering and pagination. Choose based on API style preference and your team's familiarity.

Q: Does graphql-dotnet work with Entity Framework? A: Yes. Field resolvers can use any data access layer including Entity Framework Core. Use DataLoader to batch EF queries and avoid the N+1 problem.

Q: How do I add authentication and authorization? A: graphql-dotnet provides field middleware and authorization validation rules. You can use the GraphQL.Authorization package to apply policy-based authorization at the field level, integrating with ASP.NET Core's built-in auth system.

Q: Can I use it with minimal APIs in .NET? A: Yes. While the traditional setup uses middleware, you can configure graphql-dotnet with minimal API endpoints in .NET 6+ for a lighter hosting model.

Sources

• https://github.com/graphql-dotnet/graphql-dotnet
• https://graphql-dotnet.github.io/