GraphQL 8.2.1

GraphQL for .NET

License codecov Nuget Nuget GitHub Release Date GitHub commits since latest release (by date) Size

GitHub contributors Activity Activity Activity

:heart: Become a backer! :heart: Backers on Open Collective Sponsors on Open Collective
:heavy_dollar_sign: Get paid for contributing! :heavy_dollar_sign: GitHub issues by-label GitHub closed issues by-label

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.MicrosoftDI Nuget Nuget

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

Documentation

  1. http://graphql-dotnet.github.io - documentation site that is built from the docs folder in the master branch.
  2. https://graphql.org/learn - learn about GraphQL, how it works, and how to use it.

Debugging

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.

Installation

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 IGraphQLSerializer 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 GraphQL.NewtonsoftJson with .NET Core 3+, just be aware it lacks async writing capabilities so writing to an ASP.NET Core 3.0 HttpResponse.Body will require you to set AllowSynchronousIO to true as per this announcement; which isn't recommended.

3. Document Caching

The recommended way to setup caching layer (for caching of parsed GraphQL documents) is to inherit from IConfigureExecution interface and register your class as its implementation. We provide in-memory implementation on top of Microsoft.Extensions.Caching.Memory package.

> 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

DocumentExecuter can handle subscriptions as well as queries and mutations. For more information see Subscriptions.

6. Advanced Dependency Injection

Also we provide some extra classes for advanced dependency injection usage on top of Microsoft.Extensions.DependencyInjection.Abstractions package.

> dotnet add package GraphQL.MicrosoftDI

For more information see Thread safety with scoped services.

Examples

https://github.com/graphql-dotnet/examples

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:

Ahead-of-time compilation

GraphQL.NET supports ahead-of-time (AOT) compilation for execution of code-first schemas with .NET 7. This allows for use within iOS and Android apps, as well as other environments where such features as JIT compilation or dynamic code generation are not available. It may be necessary to explicitly instruct the AOT compiler to include the .NET types necessary for your schema to operate correctly. Of particular note, your query, mutation and subscription types' constructors may be trimmed; register them in your DI engine to prevent this. Also, Field(x => x.MyField) for enumeration values will require manually adding a mapping reference via RegisterTypeMapping<MyEnum, EnumerationGraphType<MyEnum>>(). Please see the GraphQL.AotCompilationSample for a simple demonstration of AOT compilation. Schema-first and type-first schemas have additional limtations and configuration requirements. AOT compilation has not been tested with frameworks other than .NET 7 on Windows and Linux (e.g. Xamarin).

Training

Upgrade Guides

You can see the changes in public APIs using fuget.org.

Basic Usage

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

Fully-featured examples can be found here.

Hello World

using System;
using System.Threading.Tasks;
using GraphQL;
using GraphQL.Types;
using GraphQL.SystemTextJson; // First add PackageReference to GraphQL.SystemTextJson

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

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

Console.WriteLine(json);

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<Query>();
});

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

Parameters

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

public class Query
{
  private List<Droid> _droids = new List<Droid>
  {
    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<Query>();
});

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

Roadmap

Grammar / AST

Operation Execution

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

Validation

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

Schema Introspection

GraphQL.NET supports introspection schema from October 2021 spec with some additional experimental introspection extensions.

Publishing NuGet packages

The package publishing process is automated with GitHub Actions.

After your PR is merged into master or develop, preview packages are published to GitHub Packages.

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

Contributors

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 master. It is designed for non-breaking changes, that is to publish versions 7.x.x. If you have a PR with some breaking changes, then please target it to the develop branch that tracks changes for v8.0.0.

Backers

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

Contributions are very much appreciated and are used to support the project primarily via bounties paid directly to contributors to the project. Please help us to express gratitude to those individuals who devote time and energy to contributing to this project by supporting their efforts in a tangible means. A list of the outstanding issues to which we are sponsoring via bounties can be found here.

Sponsors

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

Showing the top 20 packages that depend on GraphQL.

Packages Downloads
GraphQL.SystemReactive
GraphQL subscriptions implementation on top of System.Reactive
23
GraphQL.MicrosoftDI
Microsoft DI extensions for GraphQL.NET
22
GraphQL.SystemReactive
GraphQL subscriptions implementation on top of System.Reactive
22
GraphQL.MicrosoftDI
Microsoft DI extensions for GraphQL.NET
21
GraphQL.MicrosoftDI
Microsoft DI extensions for GraphQL.NET
20
GraphQL.MemoryCache
GraphQL memory cache implementation on top of Microsoft.Extensions.Caching.Memory
20
GraphQL.MemoryCache
GraphQL memory cache implementation on top of Microsoft.Extensions.Caching.Memory
19
GraphQL.MicrosoftDI
Microsoft DI extensions for GraphQL.NET
19
GraphQL.SystemReactive
GraphQL subscriptions implementation on top of System.Reactive
19

See https://github.com/graphql-dotnet/graphql-dotnet/releases and https://graphql-dotnet.github.io/docs/migrations/migration7

Version Downloads Last updated
8.2.1 1 10/25/2024
8.2.0 3 10/21/2024
8.1.0 6 09/27/2024
8.0.2 4 08/27/2024
8.0.1 5 08/24/2024
8.0.0 4 08/21/2024
7.9.0 5 08/19/2024
7.8.0 14 02/10/2024
7.7.2 9 12/29/2023
7.7.1 15 02/01/2024
7.7.0 11 01/29/2024
7.6.1 12 10/12/2023
7.6.0 11 10/11/2023
7.5.0 11 09/22/2023
7.4.1 12 08/28/2023
7.4.0 11 09/09/2023
7.3.1 11 10/08/2023
7.3.0 10 10/08/2023
7.2.2 9 08/27/2023
7.2.1 12 11/10/2023
7.2.0 9 10/07/2023
7.1.1 8 10/08/2023
7.1.0 13 08/27/2023
7.0.2 14 08/27/2023
7.0.1 10 09/22/2023
7.0.0 10 10/08/2023
5.4.0 14 10/08/2023
5.3.3 10 12/28/2023
5.3.2 13 09/09/2023
5.3.1 14 10/07/2023
5.3.0 12 08/27/2023
5.2.0 12 10/08/2023
5.1.1 10 08/28/2023
5.1.0 12 09/10/2023
5.0.0 11 10/08/2023
4.8.0 8 09/22/2023
4.7.1 14 10/08/2023
4.7.0 11 08/27/2023
4.6.1 14 10/08/2023
4.6.0 9 10/08/2023
4.5.0 9 10/07/2023
4.4.0 9 10/08/2023
4.3.0 13 09/23/2023
4.2.0 10 09/10/2023
4.1.0 15 09/09/2023
4.0.2 10 10/07/2023
4.0.1 11 10/08/2023
4.0.0 8 08/28/2023
3.3.2 12 10/08/2023
3.3.1 10 08/27/2023
3.3.0 10 09/09/2023
3.2.0 13 10/08/2023
3.1.6 12 10/08/2023
3.1.5 8 10/08/2023
3.1.4 12 10/07/2023
3.1.3 10 10/08/2023
3.1.2 8 01/02/2024
3.1.1 8 10/07/2023
3.1.0 11 10/07/2023
3.0.0.2026 8 10/04/2023
3.0.0 8 12/13/2023
3.0.0-preview-1719 10 10/13/2023
3.0.0-preview-1648 11 01/11/2024
3.0.0-preview-1490 10 10/13/2023
3.0.0-preview-1354 12 10/13/2023
3.0.0-preview-1352 10 10/12/2023
3.0.0-preview-1271 12 10/12/2023
3.0.0-preview-1268 12 10/13/2023
3.0.0-preview-1264 10 10/13/2023
3.0.0-preview-1211 7 03/08/2024
3.0.0-preview-1194 10 10/13/2023
3.0.0-preview-1175 10 10/13/2023
3.0.0-preview-1141 10 10/13/2023
3.0.0-preview-1107 11 10/13/2023
2.4.0 10 10/08/2023
2.3.0 8 10/08/2023
2.2.0 10 10/08/2023
2.1.0 10 10/08/2023
2.0.0 9 10/08/2023
2.0.0-preview-997 12 10/23/2023
2.0.0-preview-1002 11 01/23/2024
2.0.0-alpha-978 9 10/21/2023
2.0.0-alpha-952 10 10/20/2023
2.0.0-alpha-951 7 10/20/2023
2.0.0-alpha-947 7 10/21/2023
2.0.0-alpha-938 9 10/20/2023
2.0.0-alpha-937 8 10/21/2023
2.0.0-alpha-931 10 10/20/2023
2.0.0-alpha-927 8 10/21/2023
2.0.0-alpha-923 8 10/21/2023
2.0.0-alpha-912 8 10/20/2023
2.0.0-alpha-899 8 10/20/2023
2.0.0-alpha-887 7 10/20/2023
2.0.0-alpha-870 7 10/20/2023
2.0.0-alpha-868 8 10/21/2023
2.0.0-alpha-863 8 10/20/2023
2.0.0-alpha-859 7 10/20/2023
2.0.0-alpha-851 8 10/20/2023
2.0.0-alpha-839 8 10/20/2023
2.0.0-alpha-820 9 10/21/2023
2.0.0-alpha-817 8 10/21/2023
2.0.0-alpha-811 8 10/20/2023
2.0.0-alpha-805 8 10/21/2023
2.0.0-alpha-802 6 10/20/2023
2.0.0-alpha-797 10 10/21/2023
2.0.0-alpha-793 8 10/21/2023
2.0.0-alpha-783 8 10/21/2023
0.17.3 9 10/09/2023
0.17.2 9 10/09/2023
0.17.1 8 10/09/2023
0.17.0 9 10/09/2023
0.16.1 9 10/09/2023
0.16.0 7 10/09/2023
0.16.0-alpha-697 10 10/22/2023
0.15.1.678 9 10/07/2023
0.15.0.671 10 10/07/2023
0.14.7.667 11 10/07/2023
0.14.6.657 8 10/06/2023
0.14.5.654 10 10/07/2023
0.14.4.649 13 10/06/2023
0.14.3.646 11 10/06/2023
0.14.1.638 10 10/06/2023
0.14.0.633 10 10/07/2023
0.13.1.601 11 10/07/2023
0.13.0.562 8 10/06/2023
0.12.3.556 10 10/07/2023
0.12.2-alpha-550 9 10/22/2023
0.12.1-alpha-545 12 10/22/2023
0.12.0-alpha-538 10 10/21/2023
0.12.0-alpha-536 8 10/22/2023
0.12.0-alpha-511 8 10/22/2023
0.11.0.493 9 10/07/2023
0.10.3.478 9 10/07/2023
0.10.2.436 12 10/07/2023
0.10.1.349 10 10/07/2023
0.10.0.325 11 10/07/2023
0.10.0.323 10 10/07/2023
0.9.3 10 10/08/2023
0.9.2 8 10/08/2023
0.9.1 8 10/07/2023
0.9.0 11 10/08/2023
0.8.2 10 10/08/2023
0.8.1 9 10/08/2023
0.8.0 7 10/08/2023
0.8.0-alpha 9 10/28/2023
0.7.1 10 10/08/2023
0.7.0 10 10/08/2023
0.6.6 7 10/08/2023
0.6.5 7 10/07/2023
0.6.4 10 10/08/2023
0.6.3 8 10/08/2023
0.6.2 10 10/07/2023
0.6.1 10 10/08/2023
0.6.0 9 10/08/2023
0.5.1 8 10/07/2023
0.5.0 8 10/08/2023
0.4.1 8 10/08/2023
0.4.0 11 10/08/2023
0.3.0 10 10/07/2023
0.2.0 6 10/07/2023
0.1.1 7 10/07/2023
0.1.0 8 01/05/2024