Core Fluent

Getting started with Firestorm Fluent API, ASP.NET Core and Entity Framework Core

This tutorial sets up the most basic Firestorm REST API.

In just a few minutes, we'll have created a new relational database and a fully-featured REST API.

Start new ASP.NET Core Web Application

Open Visual Studio and create a new ASP.NET Core C# web application. In our example, we'll call it Hollywood.

1. Go to File > New > Project
2. From the left pane, select Installed > Visual C# > Web
3. Select ASP.NET Core Web Application
4. Enter Hollywood and click OK.

5. On the next window, select Empty
6. Make sure Authentication is set to No Authentication.
7. Click OK.

Create your models

1. Create a new folder called Models in your project root.

2. Create a new C# class file in the Models folder called Film.cs and replace it's contents with the following code.

using System;
using System.Collections.Generic;

namespace Hollywood.Models
{
    public class Film
    {
        public int Id { get; set; }

        public string Name { get; set; }

        public DateTime ReleaseDate { get; set; }

        public float Rating { get; set; }

        public ICollection<Character> Characters { get; set; }
    }
}

4. Create a new C# class file in the Models folder called Character.cs with the following code.

namespace Hollywood.Models
{
    public class Character
    {
        public int Id { get; set; }

        public string Name { get; set; }

        public Film Film { get; set; }

        public Actor Actor { get; set; }
    }
}

5. And finally, create the Actor.cs model with the following code.

using System;
using System.Collections.Generic;

namespace Hollywood.Models
{
    public class Actor
    {
        public int Id { get; set; }

        public string Name { get; set; }

        public ICollection<Character> Characters { get; set; }
    }
}

Setup Entity Framework Core Context

Once your models are created, you can setup your DbContext.

If you are not already familiar with Entity Framework Core, it may be helpful to read this tutorial.

This tutorial uses SQL Server, and the Microsoft.EntityFrameworkCore.SqlServer NuGet package. This package is included in Microsoft.AspNetCore.All so you don't have to install it.

1. Create a new folder called Contexts in your project root.

2. Create a new C# file named HollywoodDbContext.cs and replace the contents with the following code:

using Hollywood.Models;
using Microsoft.EntityFrameworkCore;

namespace Hollywood.Contexts
{
    public class HollywoodDbContext : DbContext
    {
        public HollywoodDbContext(DbContextOptions<HollywoodDbContext> options) : base(options)
        {
        }

        public DbSet<Film> Films { get; set; }
        public DbSet<Character> Characters { get; set; }
        public DbSet<Actor> Actors { get; set; }
    }
}

Setup Firestorm Fluent API Context

1. Install the Firestorm Fluent NuGet package.

PM> Install-Package Firestorm.Fluent

Very similarly to EF Core, the Firestorm Fluent API is driven by single context class.

2. In your Contexts folder, create a new C# file named HollywoodApiContext.cs and replace the contents with the following code:

using Firestorm.Fluent;
using Hollywood.Models;

namespace Hollywood.Contexts
{
    public class HollywoodApiContext : ApiContext
    {
        public HollywoodApiContext()
        {
            Options.RootConfiguration.AllowWrite = true;
        }

        public ApiRoot<Film> Films { get; set; }
        public ApiRoot<Character> Characters { get; set; }
        public ApiRoot<Actor> Actors { get; set; }
    }
}

The AllowWrite option allows PUT and POST requests to make changes to the data. In this example there is no authorisation, but a real application must ensure the user has permissions to do this.

Configure both in your Startup.cs

Entity Framework Core and the Firestorm Fluent API both need configuring in your Startup.cs.

1. Install the Firestorm packages required for ASP.NET Core and Entity Framework Core.

PM> Install-Package Firestorm.Endpoints
PM> Install-Package Firestorm.AspNetCore2
PM> Install-Package Firestorm.EntityFrameworkCore2

Now you need to configure the Fluent and EntityFramework services in your Startup.

2. Replace your Startup.cs file with the following code.

using Firestorm.AspNetCore2;
using Firestorm.Endpoints;
using Firestorm.EntityFrameworkCore2;
using Hollywood.Contexts;
using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Hosting;
using Microsoft.EntityFrameworkCore;
using Microsoft.Extensions.DependencyInjection;

namespace Hollywood
{
    public class Startup
    {
        public void ConfigureServices(IServiceCollection services)
        {
            services.AddDbContext<HollywoodDbContext>(
                o => o.UseSqlServer("Server=(localdb)\\mssqllocaldb;Database=Hollywood;Trusted_Connection=True;MultipleActiveResultSets=true"));

            services.AddFirestorm()
                .AddEndpoints()
                .AddFluent<HollywoodApiContext>()
                .AddEntityFramework<HollywoodDbContext>(o => o.EnsureCreatedOnRequest = true);
        }

        public void Configure(IApplicationBuilder app, IHostingEnvironment env)
        {
            if (env.IsDevelopment())
                app.UseDeveloperExceptionPage();

            app.UseFirestorm();
        }
    }
}

Here we have hardcoded a localdb connection string into the Startup.cs file. In a real application, you would get the connection string from appsettings.json using the ASP.NET Core configuration system.

We've also used EnsureCreatedOnRequest for this example, which creates the local database if it does not already exist. This wouldn't be used in production.

Use your REST API

And that's it! You now have a REST API you can start sending requests to.

1. Add your first item.

POST /Films HTTP/1.1

{
    "Name": "The best film",
    "ReleaseDate": "2018-02-06",
    "Rating": 10
}


HTTP/1.1 201 Created

2. Retrieve that item

GET /Films HTTP/1.1

HTTP/1.1 200 OK

[
    {
        "Id": 1,
        "Name": "The best film",
        "ReleaseDate": "2018-02-06T00:00:00",
        "Rating": 10,
        "Characters": []
    }
]