Need help with graphql-dotnet?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

4.9K Stars 811 Forks MIT License 1.6K Commits 140 Opened issues


GraphQL for .NET

Services available


Need anything else?

Contributors list

GraphQL for .NET

Join the chat at

Test code Build artifacts Publish code CodeQL analysis

codecov Total alerts Language grade: C#

Backers on Open Collective Sponsors on Open Collective

Activity Activity Activity


This is an implementation of Facebook's GraphQL in .NET.

Now the specification is being developed by the GraphQL Foundation.

This project uses a lexer/parser originally written by Marek Magdziak and released with a MIT license. Thank you Marek!

Provides the following packages:

| Package | Downloads | NuGet Latest | |------------------------|---------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------| | GraphQL | Nuget | Nuget | | GraphQL.SystemTextJson | Nuget | Nuget | | GraphQL.NewtonsoftJson | Nuget | Nuget | | GraphQL.MemoryCache | Nuget | Nuget | | GraphQL.DataLoader | Nuget | Nuget | | GraphQL.SystemReactive | Nuget | Nuget | | GraphQL.MicrosoftDI | Nuget | Nuget |

You can get all preview versions from GitHub Packages. Note that GitHub requires authentication to consume the feed. See here.


  1. - documentation site that is built from the docs folder in the
  2. - learn about GraphQL, how it works, and how to use it.


All packages generated from this repository come with embedded pdb and support Source Link. If you are having difficulty understanding how the code works or have encountered an error, then it is just enough to enable Source Link in your IDE settings. Then you can debug GraphQL.NET source code as if it were part of your project.


1. GraphQL.NET engine

This is the main package, the heart of the repository in which you can find all the necessary classes for GraphQL request processing.

> dotnet add package GraphQL

2. Serialization

For serialized results, you'll need an

implementation. We provide several serializers (or you can bring your own).
> dotnet add package GraphQL.SystemTextJson
> dotnet add package GraphQL.NewtonsoftJson

Note: You can use

with .NET Core 3+, just be aware it lacks async writing capabilities so writing to an ASP.NET Core 3.0
will require you to set
as per this announcement; which isn't recommended.

3. Document Caching

For caching of parsed GraphQL documents you'll need an

implementation. We provide in-memory implementation on top of
> dotnet add package GraphQL.MemoryCache

For more information see Document Caching.

4. DataLoader

DataLoader is a generic utility to be used as part of your application's data fetching layer to provide a simplified and consistent API over various remote data sources such as databases or web services via batching and caching.

> dotnet add package GraphQL.DataLoader

For more information see DataLoader.

Note: Prior to version 4, the contents of this package was part of the main GraphQL.NET package.

5. Subscriptions

For handling subscriptions you'll need an instance of

that supports this GraphQL operation type.
class from the main GraphQL.NET package supports only queries and mutations. We provide
implementation on top of
> dotnet add package GraphQL.SystemReactive

For more information see Subscriptions.

6. Advanced Dependency Injection

Also we provide some extra classes for advanced dependency injection usage on top of

> dotnet add package GraphQL.MicrosoftDI

For more information see Thread safety with scoped services.


You can also try an example of GraphQL demo server inside this repo - GraphQL.Harness. It supports the popular IDEs for managing GraphQL requests and exploring GraphQL schema: - Altair - Firecamp - GraphiQL - GraphQL Playground - Voyager


Upgrade Guides

You can see the changes in public APIs using

Basic Usage

Define your schema with a top level query object then execute that query.

Fully-featured examples can be found here.

Hello World

var schema = Schema.For(@"
  type Query {
    hello: String

var root = new { Hello = "Hello World!" }; var json = await schema.ExecuteAsync(_ => { _.Query = "{ hello }"; _.Root = root; });


Schema First Approach

This example uses the GraphQL schema language. See the documentation for more examples and information.

public class Droid
  public string Id { get; set; }
  public string Name { get; set; }

public class Query { [GraphQLMetadata("droid")] public Droid GetDroid() { return new Droid { Id = "123", Name = "R2-D2" }; } }

var schema = Schema.For(@" type Droid { id: ID name: String }

type Query { droid: Droid } ", _ => { _.Types.Include(); });

var json = await schema.ExecuteAsync(_ => { _.Query = "{ droid { id name } }"; });


public class Droid
  public string Id { get; set; }
  public string Name { get; set; }

public class Query { private List _droids = new List { new Droid { Id = "123", Name = "R2-D2" } };

[GraphQLMetadata("droid")] public Droid GetDroid(string id) { return _droids.FirstOrDefault(x => x.Id == id); } }

var schema = Schema.For(@" type Droid { id: ID name: String }

type Query { droid(id: ID): Droid } ", _ => { _.Types.Include(); });

var json = await schema.ExecuteAsync(_ => { _.Query = $"{{ droid(id: "123") {{ id name }} }}"; });


Grammar / AST

Operation Execution

  • [x] Scalars
  • [x] Objects
  • [x] Lists of objects/interfaces
  • [x] Interfaces
  • [x] Unions
  • [x] Arguments
  • [x] Variables
  • [x] Fragments
  • [x] Directives
    • [x] Include
    • [x] Skip
    • [x] Custom
  • [x] Enumerations
  • [x] Input Objects
  • [x] Mutations
  • [x] Subscriptions
  • [x] Async execution


  • [x] Arguments of correct type
  • [x] Default values of correct type
  • [x] Fields on correct type
  • [x] Fragments on composite types
  • [x] Known argument names
  • [x] Known directives
  • [x] Known fragment names
  • [x] Known type names
  • [x] Lone anonymous operations
  • [x] No fragment cycles
  • [x] No undefined variables
  • [x] No unused fragments
  • [x] No unused variables
  • [x] Overlapping fields can be merged
  • [x] Possible fragment spreads
  • [x] Provide non-null arguments
  • [x] Scalar leafs
  • [x] Unique argument names
  • [x] Unique directives per location
  • [x] Unique fragment names
  • [x] Unique input field names
  • [x] Unique operation names
  • [x] Unique variable names
  • [x] Variables are input types
  • [x] Variables in allowed position
  • [x] Single root field

Schema Introspection

  • [x] __typename
  • [x] __type
    • [x] name
    • [x] kind
    • [x] description
    • [x] fields
    • [x] interfaces
    • [x] possibleTypes
    • [x] enumValues
    • [x] inputFields
    • [x] ofType
  • [x] __schema
    • [x] types
    • [x] queryType
    • [x] mutationType
    • [x] subscriptionType
    • [x] directives

Publishing NuGet packages

The package publishing process is automated with GitHub Actions.

After your PR is merged into

, preview packages are published to GitHub Packages.

Stable versions of packages are published to NuGet when a release is created.


This project exists thanks to all the people who contribute.

PRs are welcome! Looking for something to work on? The list of open issues is a great place to start. You can help the project simply respond to some of the asked questions.

The default branch is

. It is designed for non-breaking changes, that is to publish versions 4.x.x. If you have a PR with some breaking changes, then please target it to the


Thank you to all our backers! 🙏 Become a backer.


Support this project by becoming a sponsor. Your logo will show up here with a link to your website. Become a sponsor.

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.