Hot Chocolate is a GraphQL server for .net core and .net classic
Clone or download

README.md

HotChocolate

GitHub release NuGet Package License AppVeyor Travis Tests Coverage Status Quality BCH compliance


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 December. We have listed our progress toward version one at the bottom of this readme.

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 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.

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 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.

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-server

Features and Roadmap

We currently support the following parts of the current June 2018 specification of GraphQL.

Types

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

Scalar Types

  • Int
  • Float
  • String
  • Boolean
  • ID

Directives

  • Skip
  • Continue
  • Deprecated

Validation

Execution

  • Query
  • Mutation
  • Subscription

Introspection

  • 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.

Draft Features

We are currently working on the following features that are proposed for the next GraphQL specification.

Additional Scalar Types

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

Additional Directives

  • Schema Stitching (in development - 0.8.0)
  • HTTP Directives (in development - 0.8.0)
  • Custom Schema Directives
  • Custom Query Directives

Execution Engine

  • Custom Context Objects
  • Data Loader Integration / Batched Operations

Schema Creation

  • Schema-First approach
  • Code-First approach

Supported Frameworks

  • ASP.NET Classic

    • Get (in development - 0.7.0)
    • Post (in development - 0.7.0)
    • WebSockets (in development - 0.8.0)
    • Schema Builder (in development - 1.0.0)
  • ASP.NET Core

    • Get
    • Post
    • WebSockets
    • Schema Builder (in development - 0.11.0)

Documentation

For more examples and detailed documentation, click here.

For documentation about our DataLoader implementation click here.