hotchocolate: A C# repository from nigel-sampson

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

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

var executor = schema.MakeExecutable();

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 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 also have a ASP.Net Framework middleware available.

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

Features and Roadmap

We have moved the roadmap into the ROADMAP.md

GraphQL Compatibility Acceptance Tests

We are now investing to implement the GraphQL Compatibility Acceptance Tests for Hot Chocolate. We should have the first test running with Version 0.8.0 and should have this finished until Version 0.11.0.

More about GraphQL compatibility acceptance tests can be read here.

Documentation

For more examples and detailed documentation, click here.