GraphQL for .NET
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!
Installation
WARNING: The latest stable version 2.4.0 has many known issues that have been fixed in 3.0.0-preview-XXXX versions.
If errors occur, it is recommended that you first check the behavior on the latest available preview version before
reporting a issue. Latest 3.0.0-preview-XXXX versions are backwards incompatible with latest stable 2.4.0 version.
You can see the changes in public APIs using fuget.org.
You can install the latest stable version via NuGet.
> dotnet add package GraphQL
For serialized results, you'll need an IDocumentWriter implementation.
We support GraphQL.SystemTextJson for .NET Core 3+,
GraphQL.NewtonsoftJson
(formerly included in GraphQL), or you can bring your own.
> dotnet add package GraphQL.SystemTextJson
> dotnet add package GraphQL.NewtonsoftJson
Note: You can use
GraphQL.NewtonsoftJsonwith .NET Core 3+, just be aware it lacks async writing
capabilities so writing to an ASP.NET Core 3.0HttpResponse.Bodywill require you to set
AllowSynchronousIOtotrueas per this announcement;
which isn't recommended.
You can get the latest pre-release packages from the MyGet feed,
where you may want to explicitly pull a certain version using -v.
> dotnet add package GraphQL.SystemTextJson -v 3.0.0-preview-1448
Documentation
http://graphql-dotnet.github.io
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 - GraphQL Playground, GraphiQL and Altair.
Training
- 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 by Roland Guijt
Upgrade Guides
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;
});
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
- Grammar and AST for the GraphQL language should be compatible with the June 2018 specification.
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
- __typename
- __type
- name
- kind
- description
- fields
- interfaces
- possibleTypes
- enumValues
- inputFields
- ofType
- __schema
- types
- queryType
- mutationType
- subscriptionType
- directives
Publishing Nugets
yarn run setVersion 2.0.0
git commit/push
download nuget from AppVeyor
upload nuget package to github
publish nuget from MyGet
Running on OSX with mono
To run this project on OSX with mono you will need to add some configuration.
Make sure mono is installed and add the following to your bash configuration:
export FrameworkPathOverride=/Library/Frameworks/Mono.framework/Versions/4.6.2/lib/mono/4.5/
See the following for more details: