HotChocolate

---

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

Hot Chocolate is a GraphQL server implementation based on the current GraphQL June 2018 specification.

Getting Started

If you are just getting started with GraphQL a good way to learn is visiting GraphQL.org. We have implemented the Star Wars example used on GraphQL.org 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.

If you want to get in touch with us you can do so by joining our slack group.

This readme only provides a simple quickstart, in order to learn more about advanced features like schema stitching head over to our documentation.

Using Hot Chocolate

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 describe schemas in three variants.

• SDL-First: Describe your schema with the GraphQL schema definition language and bind .NET types to it.
• Code-First: Define GraphQL types with C#. This gives you compile safety.
• Pure Code-First: Just describe the schema with clean .NET types without any GraphQL types and the Hot Chocolate will infer the schema types for you.

The following example shows the pure code-first approach.

Make sure to add the following usings to your code in order to get access to the extension methods used in the examples: using HotChocolate; using HotChocolate.Execution;

public class Program
{
    public static void Main(string[] args)
    {
        var schema = SchemaBuilder.New()
          .AddQueryType<Query>()
          .Create();
    }
}

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 SDL 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 method that resolves the data for the specified field.

In order to serve up queries against our schema lets make it executable:

var executor = schema.MakeExecutable();

MakeExecutable will create a IQueryExecutor instance that can execute queries against our schema.

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

{
  hello
}

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

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(executor.Execute("{ foo }").ToJson());

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(sp => SchemaBuilder.New()
      .AddQueryType<Query>()
      .AddServices(sp)
      .Create());
}

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 Banana Cake Pop.

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");
}

Templates

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

Documentation

For more examples and detailed documentation, click here.

Components

Component	Description
Core	Core consists of the execution engine, the query validation and the type system.
Language	Language consists of the UTF-8 high-performance GraphQL parser, the abstract syntax tree and the syntax visitor API.
Filters	Filters contains the basic filter rewriter, the filter middleware for IQueryable and other database related logic.
Persisted Queries	Persisted queries contains the persisted queries storage implementations for the file system, redis cache and others.
Stitching	Stitching represents the stitching layer version 1.
Utilities	Utilities contains helpers like the 2-phase introspection that are used by multiple components.
AspNetCore	AspNetCore contains the server implementation for AspNetCore servers.
AzureFunctions	AzureFunctions contains the server implementation for AzureFunctions.