Repository files navigation

❤️Become a backer! ❤️

💲Get paid for contributing! 💲

This is an implementation of GraphQL, a query language and execution engine originally createdby Facebook in 2012, in .NET.

TheGraphQL specification is now being developed andmaintained by theGraphQL Foundation, established in 2019 tosupport the GraphQL ecosystem. You can also find the specification's source and discussionson GitHub atgraphql/graphql-spec.

This project uses alexer/parser originally writtenbyMarek Magdziak and released with a MIT license. Thank you Marek!

Provides the following packages:

Package	Downloads	NuGet Latest
GraphQL
GraphQL.SystemTextJson
GraphQL.NewtonsoftJson
GraphQL.MemoryCache
GraphQL.DataLoader
GraphQL.MicrosoftDI

You can get all preview versions fromGitHub Packages.Note that GitHub requires authentication to consume the feed. Seehere.

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

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

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

> dotnet add package GraphQL

For serialized results, you'll need anIGraphQLSerializer implementation.We provide several serializers (or you can bring your own).

> dotnet add package GraphQL.SystemTextJson> dotnet add package GraphQL.NewtonsoftJson

Note: You can useGraphQL.NewtonsoftJson with .NET Core 3+, just be aware it lacks async writingcapabilities so writing to an ASP.NET Core 3.0HttpResponse.Body will require you to setAllowSynchronousIO totrue as perthis announcement;which isn't recommended.

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

> dotnet add package GraphQL.MemoryCache

For more information seeDocument Caching.

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

> dotnet add package GraphQL.DataLoader

For more information seeDataLoader.

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

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

To easily configure GraphQL.NET with the Microsoft dependency injection provider,you can use theGraphQL.MicrosoftDI package. This package provides aAddGraphQLextension method to register the necessary services. This package can also be used withother dependency injection providers that support theMicrosoft.Extensions.DependencyInjectionabstraction such as Autofac, Castle Windsor, and StructureMap.

> dotnet add package GraphQL.MicrosoftDI

You can then configure GraphQL.NET in yourStartup.cs file like this:

publicvoidConfigureServices(IServiceCollectionservices){services.AddGraphQL(b=>b.AddSchema<MySchema>().AddSystemTextJson().AddDataLoader());}

For more information seeDependency Injection.

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

GraphQL.NET supports ahead-of-time (AOT) compilation for execution of code-first schemas with .NET 7+. This allowsfor use within iOS and Android apps, as well as other environments where such features as JIT compilation ordynamic code generation are not available. It may be necessary to explicitly instruct the AOT compilerto 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 viaRegisterTypeMapping<MyEnum, EnumerationGraphType<MyEnum>>(). Please see theGraphQL.AotCompilationSample for a simpledemonstration 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).

• API Development in .NET with GraphQL -Glenn Block demonstrates how to use the GraphQL.NET framework to build a fully functional GraphQL endpoint.
• Building GraphQL APIs with ASP.NET Core byRoland Guijt

You can see the changes in public APIs usingfuget.org.

• 7.x to 8.x
• 5.x to 7.x
• 4.x to 5.x
• 3.x to 4.x
• 2.4.x to 3.x
• 0.17.x to 2.x
• 0.11.0
• 0.8.0

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

Fully-featured examples can be foundhere.

usingSystem;usingSystem.Threading.Tasks;usingGraphQL;usingGraphQL.Types;usingGraphQL.SystemTextJson;// First add PackageReference to GraphQL.SystemTextJsonvarschema=Schema.For(@"  type Query {    hello: String  }");varroot=new{Hello="Hello World!"};varjson=awaitschema.ExecuteAsync(_=>{_.Query="{ hello }";_.Root=root;});Console.WriteLine(json);

This example uses theGraphQL schema language.See thedocumentation formore examples and information.

publicclassDroid{publicstringId{get;set;}publicstringName{get;set;}}publicclassQuery{[GraphQLMetadata("droid")]publicDroidGetDroid(){returnnewDroid{Id="123",Name="R2-D2"};}}varschema=Schema.For(@"  type Droid {    id: ID    name: String  }  type Query {    droid: Droid  }", _=>{_.Types.Include<Query>();});varjson=awaitschema.ExecuteAsync(_=>{_.Query="{ droid { id name } }";});

publicclassDroid{publicstringId{get;set;}publicstringName{get;set;}}publicclassQuery{privateList<Droid>_droids=newList<Droid>{newDroid{Id="123",Name="R2-D2"}};[GraphQLMetadata("droid")]publicDroidGetDroid(stringid){return_droids.FirstOrDefault(x=>x.Id==id);}}varschema=Schema.For(@"  type Droid {    id: ID    name: String  }  type Query {    droid(id: ID): Droid  }", _=>{_.Types.Include<Query>();});varjson=awaitschema.ExecuteAsync(_=>{_.Query=$"{{ droid(id:\"123\") {{ id name }} }}";});

• Grammar and AST for the GraphQL language should be compatible with theOctober 2021 specification.

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

• 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

GraphQL.NET supports introspection schema fromOctober 2021 specwith some additional experimental introspectionextensions.

The package publishing process is automated withGitHub Actions.

After your PR is merged intomaster ordevelop, preview packages are published toGitHub Packages.

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

This project exists thanks to all the people who contribute.

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

The default branch ismaster. 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 thedevelop branch that tracks changes for v8.0.0.

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

Contributions are very much appreciated and are used to support the project primarily viabounties 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 foundhere.

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