Hot Chocolate is a GraphQL server for .NET Core and .NET Classic

Hot Chocolate is a GraphQL server and parser implementation based on the current GraphQL June 2018 specification defined by Facebook.

We are currently in the process of closing some gaps and hope to finalise Version 1 by September. We have listed the implemented specification parts at the bottom of this readme.

If you are just getting started with GraphQL a good way to learn is visiting GraphQL.org. We have implemented the Star Wars example with the Hot Chocolate API and you can use our example implementation to follow along.

To generate the example project, head over to your console and fire up the following commands:

mkdir starwars
cd starwars
dotnet new -i HotChocolate.Templates.StarWars
dotnet new starwars

The GraphQL specification and more is available on the Facebook GraphQL repository.

The easiest way to get a feel for the API is to walk through our README example. If you need additional information, you can also have a look at our documentation.

Hot Chocolate can build a GraphQL schema, serve queries against that schema and host that schema for web requests.

For our examples we use .net core and the dotnet CLI which you can download here.

Let’s get started by setting up a new console application that we will use to showcase how to set up a GraphQL schema and execute queries against it.

mkdir graphql-demo
cd graphql-demo
dotnet new console -n graphql-console

Now add the query engine package to your project with the following command.

dotnet add package HotChocolate

The GraphQL schema describes the capabilities of a GraphQL API. Hot Chocolate allows you to do that code-first by defining .net classes describing that schema or schema-first by defining the schema in the GraphQL syntax and binding resolvers to it. Our README walkthrough shows you the code-first approach.

The following example shows the code-first approach.

public class Program
{
    public static void Main(string[] args)
    {
        var schema = Schema.Create(c => c.RegisterQueryType<Query>());
    }
}

public class Query
{
    public string Hello() => "world";
}

The code above defines a simple schema with one type Query and one field hello that returns a string.

If you would write that schema down in the GraphQL syntax it would look as follows:

type Query {
  hello: String
}

Moreover, we bound a resolver to the field that returns a fixed value world. A resolver is basically a function that resolves the data for the specified field.

Now that the schema is setup we can serve up a query against it.

{
  hello
}

// Prints
// {
//   data: { hello: "world" }
// }
Console.WriteLine(schema.Execute("{ hello }"));

This runs a query fetching the one field defined. The graphql function will first ensure the query is syntactically and semantically valid before executing it, reporting errors otherwise.

// {
//   "errors": [
//     {
//       "FieldName": "foo",
//       "Locations": [
//         {
//           "Line": 1,
//           "Column": 3
//         }
//       ],
//       "Message": "Could not resolve the specified field."
//     }
//   ]
// }
Console.WriteLine(schema.Execute("{ foo }"));

In order to set up a GraphQL HTTP endpoint, Hot Chocolate comes with an ASP.net core middleware.

Create a new project with the web template that comes with your dotnet CLI.

dotnet new web -n graphql-web

Now add our middleware package to the project with the following command.

dotnet add package HotChocolate.AspNetCore

Open the Startup.cs and add the following code.

protected override void ConfigureServices(IServiceCollection services)
{
    services.AddGraphQL(c => c.RegisterQueryType<ObjectType<Query>>());
}

The above example adds the GraphQL schema and the execution engine to the dependency injection.

protected override void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
    }
    app.UseGraphQL();
}

This will set up all the necessary endpoints to query the GraphQL schema via HTTP GET or HTTP POST. In order to run a query against your schema, start your web host and get GraphiQL.

By default, the middleware will be configured to listen on the service root for GraphQL requests. If you want to use a different endpoint route you can pass the desired route into the UseGraphQL instruction.

protected override void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
    }
    app.UseGraphQL("Foo/Bar");
}

We are also currently working on a middleware for ASP.net classic which is planned for Version 0.6.0.

Apart from the Star Wars template, we also have a GraphQL server template that generates a project with everything hooked up so that you can start building your API quickly.

To install the GraphQL server template, run the following command:

dotnet new -i HotChocolate.Templates.Server

Now that you have implemented this you can generate a new server project by running the following commands.

mkdir myserver
cd myserver
dotnet new graphql-server

We currently support the following parts of the current draft spec of GraphQL.

• Object Type
• Interface Type
• Union Type
• Enum Type
• Input Object Type

• Int
• Float
• String
• Boolean
• ID

• Skip
• Continue
• Depricated

• Validation

  For a detailed view of which validation rule is currently implemented, have a look at our issues.

• Query
• Mutation
• Subscription

• Fields

  • __typename
  • __type
  • __schema

• __Schema

  • types
  • queryType
  • mutationType
  • subscriptionType
  • directives

• __Type

  • kind
  • name
  • fields
  • interfaces
  • possibleTypes
  • enumValues
  • inputFields
  • ofType

Moreover, we are working on the following parts that are not defined in the spec.

• DateTime
• Date
• Time
• URL
• Decimal
• Short (Int16)
• Long (Int64)
• Custom Scalars

• Export
• Defer
• Stream
• Custom Schema Directives
• Custom Execution Directives

### Execution Engine

• Custom Context Objects
• Data Loader Integration / Batched Operations

• Schema-First approach
• Code-First approach

• ASP.NET Classic

  • Get
  • Post

• ASP.NET Core

  • Get
  • Post

For more examples and detailed documentation, click here.