imolorhe / server

ASP.NET Core Server + WebSockets Transport

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

GraphQL for .NET - Subscription Transport WebSockets

Join the chat at https://gitter.im/graphql-dotnet/graphql-dotnet

Build status Build status

Activity Activity Activity

Size

GraphQL ASP.NET Core server on top of GraphQL.NET.

Provides the following packages:

Package Downloads NuGet Latest
GraphQL.Server.Core Nuget Nuget
GraphQL.Server.Transports.AspNetCore Nuget Nuget
GraphQL.Server.Transports.AspNetCore.NewtonsoftJson Nuget Nuget
GraphQL.Server.Transports.AspNetCore.SystemTextJson Nuget Nuget
GraphQL.Server.Transports.Subscriptions.Abstractions Nuget Nuget
GraphQL.Server.Transports.WebSockets Nuget Nuget
GraphQL.Server.Ui.Altair Nuget Nuget
GraphQL.Server.Ui.Playground Nuget Nuget
GraphQL.Server.Ui.GraphiQL Nuget Nuget
GraphQL.Server.Ui.Voyager Nuget Nuget
GraphQL.Server.Authorization.AspNetCore Nuget Nuget

Transport compatible with Apollo subscription protocol.

Getting started

You can install the latest stable versions via NuGet. Also you can get all preview versions from GitHub Packages. Note that GitHub requires authentication to consume the feed. See more information here.

For just the HTTP middleware:

> dotnet add package GraphQL.Server.Transports.AspNetCore

The HTTP middleware needs an IGraphQLRequestDeserializer implementation.

.NET Core 3+:

> dotnet add package GraphQL.Server.Transports.AspNetCore.SystemTextJson

Legacy (prior to .NET Core 3):

> dotnet add package GraphQL.Server.Transports.AspNetCore.NewtonsoftJson

Or you can use your own IGraphQLRequestDeserializer implementation.

For more information on how to migrate from Newtonsoft.Json to System.Text.Json see this article.

For the WebSocket subscription protocol (depends on above) middleware:

> dotnet add package GraphQL.Server.Transports.WebSockets

For the UI middleware/s:

> dotnet add package GraphQL.Server.Ui.Altair
> dotnet add package GraphQL.Server.Ui.GraphiQL
> dotnet add package GraphQL.Server.Ui.Playground
> dotnet add package GraphQL.Server.Ui.Voyager

Configure

See the sample project's Startup.cs for full details.

public void ConfigureServices(IServiceCollection services)
{
    // Add GraphQL services and configure options
    services
        .AddSingleton<IChat, Chat>()
        .AddSingleton<ChatSchema>()
        .AddGraphQL((options, provider) =>
        {
            options.EnableMetrics = Environment.IsDevelopment();
            var logger = provider.GetRequiredService<ILogger<Startup>>();
            options.UnhandledExceptionDelegate = ctx => logger.LogError("{Error} occurred", ctx.OriginalException.Message);
        })
        // Add required services for GraphQL request/response de/serialization
        .AddSystemTextJson() // For .NET Core 3+
        .AddNewtonsoftJson() // For everything else
        .AddErrorInfoProvider(opt => opt.ExposeExceptionStackTrace = Environment.IsDevelopment())
        .AddWebSockets() // Add required services for web socket support
        .AddDataLoader() // Add required services for DataLoader support
        .AddGraphTypes(typeof(ChatSchema)) // Add all IGraphType implementors in assembly which ChatSchema exists 
}

public void Configure(IApplicationBuilder app)
{
    // this is required for websockets support
    app.UseWebSockets();

    // use websocket middleware for ChatSchema at default path /graphql
    app.UseGraphQLWebSockets<ChatSchema>();

    // use HTTP middleware for ChatSchema at default path /graphql
    app.UseGraphQL<ChatSchema>();

    // use graphiQL middleware at default path /ui/graphiql
    app.UseGraphiQLServer();

    // use graphql-playground middleware at default path /ui/playground
    app.UseGraphQLPlayground();

    // use altair middleware at default path /ui/altair
    app.UseGraphQLAltair();
    
    // use voyager middleware at default path /ui/voyager
    app.UseGraphQLVoyager();
}

UserContext and resolvers

UserContext of your resolver will be type of MessageHandlingContext. You can access the properties including your actual UserContext by using the Get<YourContextType>("UserContext") method. This will read the context from the properties of MessageHandlingContext. You can add any other properties as to the context in IOperationMessageListeners. See the sample for example of injecting ClaimsPrincipal.

Sample

Samples.Server shows a simple Chat example demonstrating the subscription transport. It supports various GraphQL client IDEs (by default opening GraphQL Playground).

Here are some example queries to get started. Use three browser tabs or better yet windows to view the changes.

Subscription 1

Query:

subscription MessageAddedByUser($id:String!) {
  messageAddedByUser(id: $id) {
    from { id displayName }
    content
  }
}

Variables:

{
  "id": "1"
}

Subscription 2

subscription MessageAdded {
  messageAdded {
    from { id displayName }
    content
  }
}

Mutation

Query:

mutation AddMessage($message: MessageInputType!) {
  addMessage(message: $message) {
    from {
      id
      displayName
    }
    content
  }
}

Variables:

{
  "message": {
    "content": "Message",
    "fromId": "1"
  }
}

API changes

You can see the changes in public APIs using fuget.org.

About

ASP.NET Core Server + WebSockets Transport

License:MIT License


Languages

Language:C# 95.4%Language:HTML 4.6%