GraphQL 5.0.0

There is a newer version of this package available.
See the version list below for details.
dotnet add package GraphQL --version 5.0.0                
NuGet\Install-Package GraphQL -Version 5.0.0                
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="GraphQL" Version="5.0.0" />                
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add GraphQL --version 5.0.0                
#r "nuget: GraphQL, 5.0.0"                
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install GraphQL as a Cake Addin
#addin nuget:?package=GraphQL&version=5.0.0

// Install GraphQL as a Cake Tool
#tool nuget:?package=GraphQL&version=5.0.0                

GraphQL for .NET

Join the chat at https://gitter.im/graphql-dotnet/graphql-dotnet

Test code Build artifacts Publish code CodeQL analysis codecov

Backers on Open Collective Sponsors on Open Collective

Activity Activity Activity

Size

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

For caching of parsed GraphQL documents you'll need an IDocumentCache 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:

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 June2018 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. <a href="https://github.com/graphql-dotnet/graphql-dotnet/graphs/contributors"><img src="https://opencollective.com/graphql-net/contributors.svg?width=890&button=false" /></a>

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 4.x.x. If you have a PR with some breaking changes, then please target it to the develop branch.

Backers

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

<a href="https://opencollective.com/graphql-net#backers" target="_blank"><img src="https://opencollective.com/graphql-net/backers.svg?width=890"></a>

Sponsors

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

<a href="https://opencollective.com/graphql-net/sponsor/0/website" target="_blank"><img src="https://opencollective.com/graphql-net/sponsor/0/avatar.svg"></a> <a href="https://opencollective.com/graphql-net/sponsor/1/website" target="_blank"><img src="https://opencollective.com/graphql-net/sponsor/1/avatar.svg"></a> <a href="https://opencollective.com/graphql-net/sponsor/2/website" target="_blank"><img src="https://opencollective.com/graphql-net/sponsor/2/avatar.svg"></a> <a href="https://opencollective.com/graphql-net/sponsor/3/website" target="_blank"><img src="https://opencollective.com/graphql-net/sponsor/3/avatar.svg"></a> <a href="https://opencollective.com/graphql-net/sponsor/4/website" target="_blank"><img src="https://opencollective.com/graphql-net/sponsor/4/avatar.svg"></a> <a href="https://opencollective.com/graphql-net/sponsor/5/website" target="_blank"><img src="https://opencollective.com/graphql-net/sponsor/5/avatar.svg"></a> <a href="https://opencollective.com/graphql-net/sponsor/6/website" target="_blank"><img src="https://opencollective.com/graphql-net/sponsor/6/avatar.svg"></a> <a href="https://opencollective.com/graphql-net/sponsor/7/website" target="_blank"><img src="https://opencollective.com/graphql-net/sponsor/7/avatar.svg"></a> <a href="https://opencollective.com/graphql-net/sponsor/8/website" target="_blank"><img src="https://opencollective.com/graphql-net/sponsor/8/avatar.svg"></a> <a href="https://opencollective.com/graphql-net/sponsor/9/website" target="_blank"><img src="https://opencollective.com/graphql-net/sponsor/9/avatar.svg"></a>

Product Compatible and additional computed target framework versions.
.NET net5.0 was computed.  net5.0-windows was computed.  net6.0 is compatible.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 was computed.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 was computed.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed. 
.NET Core netcoreapp2.0 was computed.  netcoreapp2.1 was computed.  netcoreapp2.2 was computed.  netcoreapp3.0 was computed.  netcoreapp3.1 was computed. 
.NET Standard netstandard2.0 is compatible.  netstandard2.1 is compatible. 
.NET Framework net461 was computed.  net462 was computed.  net463 was computed.  net47 was computed.  net471 was computed.  net472 was computed.  net48 was computed.  net481 was computed. 
MonoAndroid monoandroid was computed. 
MonoMac monomac was computed. 
MonoTouch monotouch was computed. 
Tizen tizen40 was computed.  tizen60 was computed. 
Xamarin.iOS xamarinios was computed. 
Xamarin.Mac xamarinmac was computed. 
Xamarin.TVOS xamarintvos was computed. 
Xamarin.WatchOS xamarinwatchos was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (198)

Showing the top 5 NuGet packages that depend on GraphQL:

Package Downloads
WireMock.Net

Lightweight Http Mocking Server for .Net, inspired by WireMock from the Java landscape.

GraphQL.NewtonsoftJson

JSON.NET serializer for GraphQL.NET

GraphQL.SystemTextJson

System.Text.Json serializer for GraphQL.NET

GraphQL.DataLoader

GraphQL DataLoader implementation

GraphQL.MicrosoftDI

Microsoft DI extensions for GraphQL.NET

GitHub repositories (28)

Showing the top 5 popular GitHub repositories that depend on GraphQL:

Repository Stars
ThreeMammals/Ocelot
.NET API Gateway
OrchardCMS/OrchardCore
Orchard Core is an open-source modular and multi-tenant application framework built with ASP.NET Core, and a content management system (CMS) built on top of that framework.
Squidex/squidex
Headless CMS and Content Managment Hub
WireMock-Net/WireMock.Net
WireMock.Net is a flexible product for stubbing and mocking web HTTP responses using advanced request matching and response templating. Based on the functionality from http://WireMock.org, but extended with more functionality.
graphql-dotnet/graphql-client
A GraphQL Client for .NET Standard
Version Downloads Last updated
8.1.0 14,511 9/18/2024
8.0.2 29,240 8/26/2024
8.0.1 3,652 8/23/2024
8.0.0 8,447 8/20/2024
7.9.0 38,593 8/18/2024
7.8.0 743,601 2/6/2024
7.7.2 170,344 12/16/2023
7.7.1 10,774 12/13/2023
7.7.0 1,439 12/13/2023
7.6.1 391,334 8/11/2023
7.6.0 227,870 7/31/2023
7.5.0 5,496,320 6/17/2023
7.4.1 255,957 4/21/2023
7.4.0 121,955 4/14/2023
7.3.1 305,308 4/2/2023
7.3.0 257,046 2/27/2023
7.2.2 289,847 1/2/2023
7.2.1 95,287 12/8/2022
7.2.0 96,814 12/3/2022
7.1.1 517,790 9/19/2022
7.1.0 6,565 9/16/2022
7.0.2 306,853 8/23/2022
7.0.1 31,796 8/17/2022
7.0.0 142,266 8/16/2022
5.4.0 263,092 11/30/2022
5.3.3 849,424 7/19/2022
5.3.2 227,503 7/3/2022
5.3.1 20,985 6/26/2022
5.3.0 1,474,054 5/14/2022
5.2.0 324,476 5/6/2022
5.1.1 478,240 4/11/2022
5.1.0 6,439 4/8/2022
5.0.0 53,933 3/30/2022
4.8.0 1,943,197 3/30/2022
4.7.1 1,183,311 1/1/2022
4.7.0 107,661 12/27/2021
4.6.1 1,285,373 9/29/2021
4.6.0 680,378 8/18/2021
4.5.0 958,807 4/29/2021
4.4.0 36,556 4/22/2021
4.3.0 257,502 4/16/2021
4.2.0 547,609 3/30/2021
4.1.0 690,282 3/26/2021
4.0.2 141,980 3/19/2021
4.0.1 4,606 3/17/2021
4.0.0 3,846 3/17/2021
3.3.2 1,240,540 1/24/2021
3.3.1 134,471 1/14/2021
3.3.0 6,340 1/14/2021
3.2.0 984,869 12/7/2020
3.1.6 437,271 12/1/2020
3.1.5 83,182 11/20/2020
3.1.4 46,273 11/15/2020
3.1.3 754,876 10/30/2020
3.1.2 84,864 10/28/2020
3.1.1 4,496 10/27/2020
3.1.0 56,987 10/23/2020
3.0.0.2026 816,520 9/17/2020
3.0.0 340,483 9/2/2020
3.0.0-preview-1719 19,068 8/17/2020
3.0.0-preview-1648 119,401 5/5/2020
3.0.0-preview-1490 223,876 2/19/2020
3.0.0-preview-1354 1,714 2/19/2020
3.0.0-preview-1352 194,891 11/23/2019
3.0.0-preview-1271 36,985 10/4/2019
3.0.0-preview-1268 142,435 9/17/2019
3.0.0-preview-1264 1,207 9/16/2019
3.0.0-preview-1211 7,130 8/16/2019
3.0.0-preview-1194 13,025 8/2/2019
3.0.0-preview-1175 18,181 6/4/2019
3.0.0-preview-1141 8,957 3/18/2019
3.0.0-preview-1107 3,511 3/2/2019
2.4.0 6,852,304 11/15/2018
2.3.0 1,345,072 10/17/2018
2.2.0 8,234 10/17/2018
2.1.0 97,264 9/30/2018
2.0.0 480,734 8/11/2018
2.0.0-preview-997 2,665 8/10/2018
2.0.0-preview-1002 2,424 8/11/2018
2.0.0-alpha-978 11,460 8/1/2018
2.0.0-alpha-952 9,944 7/25/2018
2.0.0-alpha-951 5,040 7/24/2018
2.0.0-alpha-947 5,439 7/19/2018
2.0.0-alpha-938 23,219 7/1/2018
2.0.0-alpha-937 2,465 6/29/2018
2.0.0-alpha-931 3,660 6/25/2018
2.0.0-alpha-927 4,268 6/18/2018
2.0.0-alpha-923 6,509 6/13/2018
2.0.0-alpha-912 11,263 5/16/2018
2.0.0-alpha-899 5,618 5/2/2018
2.0.0-alpha-887 8,642 4/20/2018
2.0.0-alpha-870 22,194 3/27/2018
2.0.0-alpha-868 17,847 3/15/2018
2.0.0-alpha-863 4,355 3/3/2018
2.0.0-alpha-859 2,819 2/25/2018
2.0.0-alpha-851 4,021 2/12/2018
2.0.0-alpha-839 13,178 1/23/2018
2.0.0-alpha-820 16,122 12/15/2017
2.0.0-alpha-817 3,675 12/2/2017
2.0.0-alpha-811 3,203 11/18/2017
2.0.0-alpha-805 3,851 11/3/2017
2.0.0-alpha-802 19,421 9/27/2017
2.0.0-alpha-797 2,160 9/23/2017
2.0.0-alpha-793 2,106 9/22/2017
2.0.0-alpha-783 5,500 9/16/2017
0.17.3 196,350 9/5/2017
0.17.2 29,086 8/2/2017
0.17.1 12,523 7/13/2017
0.17.0 2,868 7/10/2017
0.16.1 2,995 7/7/2017
0.16.0 2,659 7/6/2017
0.16.0-alpha-697 2,773 4/29/2017
0.15.1.678 65,357 3/2/2017
0.15.0.671 3,038 2/25/2017
0.14.7.667 2,516 2/24/2017
0.14.6.657 24,087 1/26/2017
0.14.5.654 3,415 1/19/2017
0.14.4.649 3,142 1/13/2017
0.14.3.646 2,623 1/13/2017
0.14.1.638 3,191 12/23/2016
0.14.0.633 35,658 11/30/2016
0.13.1.601 6,289 11/16/2016
0.13.0.562 3,722 10/14/2016
0.12.3.556 2,913 10/7/2016
0.12.2-alpha-550 2,270 10/7/2016
0.12.1-alpha-545 2,272 10/6/2016
0.12.0-alpha-538 3,051 9/16/2016
0.12.0-alpha-536 2,946 9/16/2016
0.12.0-alpha-511 2,343 8/29/2016
0.11.0.493 3,952 8/27/2016
0.10.3.478 2,574 8/27/2016
0.10.2.436 2,934 8/20/2016
0.10.1.349 4,179 7/30/2016
0.10.0.325 2,710 7/22/2016
0.10.0.323 2,632 7/22/2016
0.9.3 2,705 6/23/2016
0.9.2 2,815 6/18/2016
0.9.1 2,964 6/13/2016
0.9.0 2,809 6/10/2016
0.8.2 2,737 6/10/2016
0.8.1 17,972 6/8/2016
0.8.0 8,721 6/7/2016
0.8.0-alpha 2,234 6/3/2016
0.7.1 6,913 6/4/2016
0.7.0 2,426 6/3/2016
0.6.6 2,573 5/12/2016
0.6.5 3,104 4/22/2016
0.6.4 2,511 4/19/2016
0.6.3 10,704 4/6/2016
0.6.2 2,548 3/23/2016
0.6.1 2,823 3/22/2016
0.6.0 2,698 3/22/2016
0.5.1 2,950 3/4/2016
0.5.0 2,485 3/2/2016
0.4.1 2,696 12/22/2015
0.4.0 6,242 12/12/2015
0.3.0 2,844 8/26/2015
0.2.0 4,710 7/16/2015
0.1.1 2,982 7/12/2015
0.1.0 7,522 7/8/2015