Entity GraphQL

A GraphQL library for .NET Core

Jump into the https://entitygraphql.github.io/ for documentation and to get started.

Entity GraphQL is a .NET Core (netstandard 2.1) library that allows you to easily build a GraphQL API on top of your data with the extensibility to bring multiple data sources together in the single GraphQL schema.

It can also be used to execute simple LINQ-style expressions at runtime against a given object which provides powerful runtime configuration.

Please explore, give feedback or join the development.

If you're looking for a dotnet library to generate code to query an API from a GraphQL schema see https://github.com/lukemurray/DotNetGraphQLQueryGen

Installation

Via Nuget

Quick Start with Entity Framework

Note: There is no dependency on EF. Queries are compiled to IQueryable or IEnumberable linq expressions. EF is not a requirement - any ORM working with LinqProvider or an in-memory object will work - although EF well is tested.

1. Define your data context (in this example an EF context)

publicclassDemoContext:DbContext{publicDemoContext(DbContextOptionsoptions):base(options){}protectedoverridevoidOnModelCreating(ModelBuilderbuilder){// Set up your relations}publicDbSet<Property>Properties{get;set;}publicDbSet<PropertyType>PropertyTypes{get;set;}publicDbSet<Location>Locations{get;set;}}publicclassProperty{publicuintId{get;set;}publicstringName{get;set;}publicPropertyTypeType{get;set;}publicLocationLocation{get;set;}}publicclassPropertyType{publicuintId{get;set;}publicstringName{get;set;}publicdecimalPremium{get;set;}}publicclassLocation{publicuintId{get;set;}publicstringName{get;set;}}

2. Create a route

Here is an example for a ASP.NET. You will also need to install EntityGraphQL.AspNet to use MapGraphQL. You can also build you own endpoint, see docs.

publicclassStartup{publicvoidConfigureServices(IServiceCollectionservices){services.AddDbContext<DemoContext>(opt =>opt.UseInMemoryDatabase());// This registers a SchemaProvider<DemoContext>services.AddGraphQLSchema<DemoContext>();}publicvoidConfigure(IApplicationBuilderapp,DemoContextdb){app.UseRouting();app.UseEndpoints(endpoints =>{// default to /graphql endpointendpoints.MapGraphQL<DemoContext>();});}}

This sets up 1 end point:

• POST at /graphql where the body of the post is a GraphQL query
• You can authorize that route how you would any ASP.NET route. See Authorization below for details on having parts of the schema requiring Authorization/Claims

Note - As of version 1.1+ the EntityGraphQL.AspNet extension helper uses System.Text.Json. Previous versions used JSON.NET.

3. Build awesome applications

You can now make a request to your API. For example

 POST localhost:5000/graphql
{
properties { id name }
}

Will return the following result.

{
"data": {
"properties": [
{
"id": 11,
"name": "My Beach Pad"
},
{
"id": 12,
"name": "My Other Beach Pad"
}
]
}
}

Maybe you only want a specific property

 {
property(id: 11) {
id name
}
}

Will return the following result.

{
"data": {
"property": {
"id": 11,
"name": "My Beach Pad"
}
}
}

If you need a deeper graph or relations, just ask

 {
properties {
id
name
location {
name
}
type {
premium
}
}
}

Will return the following result.

{
"data": {
"properties": [
{
"id": 11,
"name": "My Beach Pad",
"location": {
"name": "Greece"
},
"type": {
"premium": 1.2
}
},
{
"id": 12,
"name": "My Other Beach Pad",
"location": {
"name": "Spain"
},
"type": {
"premium": 1.25
}
}
]
}
}

Visit documentation for more information.

Using expressions else where (EQL)

Lets say you have a screen in your application listing properties that can be configured per customer or user to only show exactly what they are interested in. Instead of having a bunch of checkboxes and complex radio buttons etc. you can allow a simple EQL statement to configure the results shown. Or use those UI components to build the query.

// This might be a configured EQL statement for filtering the results. It has a context of Property(type.id=2) or (type.id=3) and type.name="Farm"

This would compile to (Property p) => (p.Type.Id == 2 || p.Type.Id == 3) && p.Type.Name == "Farm";

This can then be used in various Linq functions either in memory or against an ORM.

// we create a schema provider to compile the statement against our Property typevarschemaProvider=SchemaBuilder.FromObject<Property>();varcompiledResult=EntityQueryCompiler.Compile(myConfigurationEqlStatement,schemaProvider);// you get your list of Properties from you DBvarthingsToShow=myProperties.Where(compiledResult.LambdaExpression);

Another example is you want a customised calculated field. You can execute a compiled result passing in an instance of the context type.

// You'd take this from some configurationvareql=@"if location.name = ""Mars"" then (cost + 5) * type.premium else (cost * type.premium) / 3"varcompiledResult=EntityQueryCompiler.Compile(eql,schemaProvider);vartheRealPrice=compiledResult.Execute<decimal>(myPropertyInstance);

Versioning

We do our best to follow Semantic Versioning:

Given a version number MAJOR.MINOR.PATCH, an increment in:

• MAJOR version is when we make incompatible API changes,
• MINOR version is when we add functionality in a backwards compatible manner, and
• PATCH version is when we make backwards compatible bug fixes.

Contribute & Join the Development

Please do. Pull requests are very welcome. See the open issues for bugs or features that would be useful.