Creating your first ASP.NET Core 1.0 Web API with Swashbuckle

Using ASP.Net Core 1.0 Visual Studio 2015 I will walk through how to create a Web API. We will add some basic documentation and hook it up with Swashbuckle and Swagger. The end result is gonna be AWESOME!

Setup the Project

  1. Open up Visual Studio and create a new .Net Core.
    1.PNG
  2. Select the “Web API” template.2.PNG
  3. After the project has been created we need to tell it to export an XML document when it builds. This will allow us to generate a XML doc that will hold our swagger info and comments.
    Right Click the Project > Select “Properties” > Select “Build” > check XML documentation file > Save3.PNG

Setup Project.json and Startup.cs

  1. Open up your project.json file. This will be new to you if you haven’t played with previous releases of vNext.

    What is project.json?

    Introduced in the first versions of ASP.Net vNext (which is now called ASP.NET Core), the project.json file defines your package metadata, your project dependencies and which frameworks you want to build for. (relatively similar to ASP.NET 4x’s package.config). You can remove or add a dependencies from this file. When you do, youre solution will automatically be updated to reflect those changes. You can also set what frameworks you want your app to compile across here! Note that Microsoft has stated that project.json may go away around the time Visual Studio 15 is released. The idea with that move is that settings will move back to the .csproj file to enable better integration with MSBuild in that time frame.

  2. Since we selected the Web API template, the core API dependencies and tools were automatically added to both these files when this project was created. So all we need to do is add the Swashbuckle dependency to the project.json file.- “Swashbuckle”: “6.0.0-beta902”

    Your dependencies property should now look like this:

      "dependencies": {
        "Microsoft.NETCore.App": {
          "version": "1.0.0",
          "type": "platform"
        },
        "Microsoft.AspNetCore.Mvc": "1.0.0",
        "Microsoft.AspNetCore.Server.IISIntegration": "1.0.0",
        "Microsoft.AspNetCore.Server.Kestrel": "1.0.0",
        "Microsoft.Extensions.Configuration.EnvironmentVariables": "1.0.0",
        "Microsoft.Extensions.Configuration.FileExtensions": "1.0.0",
        "Microsoft.Extensions.Configuration.Json": "1.0.0",
        "Microsoft.Extensions.Logging": "1.0.0",
        "Microsoft.Extensions.Logging.Console": "1.0.0",
        "Microsoft.Extensions.Logging.Debug": "1.0.0",
        "Microsoft.Extensions.Options.ConfigurationExtensions": "1.0.0",
        "Swashbuckle": "6.0.0-beta902"
      }
    
  3. Next, open up Startup.cs.  In the ConfigureServices method you will need to know the path to your xml comments file which will be automatically generated for you. This path will come from GetSwaggerXMLPath().  Make sure to add the correct xml file name, it will be named [project name].xml.  You also will need to add the swagger service and configure a few properties as shown below:
     private string GetSwaggerXMLPath()
     {
     var app = PlatformServices.Default.Application;
     return System.IO.Path.Combine(app.ApplicationBasePath, [Your Project Name].xml);
     }
    public void ConfigureServices(IServiceCollection services)
    {
                // Add framework services.
                services.AddMvc();
    
                // Swagger services.
                services.AddSwaggerGen();
                services.ConfigureSwaggerGen(options =>
                {
                    options.SingleApiVersion(new Info
                    {
                        Version = "v1",
                        Title = "Test API",
                        Description = "Jesse's Test API",
                        TermsOfService = "None",
                        Contact = new Contact() { Name = "JESSE.NET", Email = "info@test.com", Url = "www.JesseDotNet.com" }
                    });
                    options.IncludeXmlComments(GetSwaggerXMLPath());
                    options.DescribeAllEnumsAsStrings();
                });
    }
    

    You should see the new XML file in your bin folder after you Build. Build your project and check for that now. It will be named [project name].xml

  4. Lastly, add the swagger middle-ware to the Configure method like below:
    public void Configure(IApplicationBuilder app, IHostingEnvironment env, ILoggerFactory loggerFactory)
    {
       app.UseMvc();
    
       app.UseSwagger();
       app.UseSwaggerUi();
    }
    

You should now be able to see your Swagger page. Run the project and navigate to http://localhost:XXXXX/swagger/ui/index.html

4.PNG

Add Swag Documentation to your API controllers!

First lets quickly go over what Swagger and Swashbuckle are:

Swagger is a simple yet powerful representation of your RESTful API. With the largest ecosystem of API tooling on the planet, thousands of developers are supporting Swagger in almost every modern programming language and deployment environment. With a Swagger-enabled API, you get interactive documentation, client SDK generation and discoverability.

-swagger.io

Swashbuckle is basically, a implementation of Swagger for ASP.NET

In addition to its Swagger generator, Swashbuckle also contains an embedded version of swagger-ui which it will automatically serve up once Swashbuckle is installed. This means you can complement your API with a slick discovery UI to assist consumers with their integration efforts. Best of all, it requires minimal coding and maintenance, allowing you to focus on building an awesome API!

-Swashbucket git repo

Now, to get our shiny new Swagger UI to show documentation of our API lets open up ValuesController.cs and add a new method to play with its comments and attributes.

/// <summary>
/// New example api endpoint that returns a int.
/// </summary>
/// <remarks>Pass in a int and this method will add 10 to it and then return it.</remarks>
/// <param name="valueA"></param>
/// <returns></returns>
[HttpGet("ExampleGet/{valueA:int}")]    //inline constraints - route matching does NOT happen if valueA is not a int with this ':int' setting.
[Produces(typeof(int))]                 //adds model and schema to swagger very helpful for passing around objects. 
[Consumes("application/json")]          //Tell this action to only accecpt json objects. Without it, it will accept anything<img width="16" height="16" class="wp-smiley emoji" draggable="false" alt=":)" src="https://s1.wp.com/wp-content/mu-plugins/wpcom-smileys/simple-smile.svg" style="height: 1em; max-height: 1em;">
public IActionResult ExampleGet(int valueA)
{
    try
    {
        valueA = valueA + 10;
        return this.Ok(valueA);
    }
    catch (Exception)
    {
        return this.BadRequest("Fail!");
    }
}

After adding the above method our page will look like this:
5.PNG

and if we try to pass it a non integer into this new endpoint we will get this:
6.PNG

Finished! Congrats!

There is still much to learn, I’d recommend checking out the dotNetConf videos for more .Net Core info.  Also is should be noted that our project above just used the default response formatting which is JSON. The response  data can be configured to things like XML by setting formatters in Startup.cs

Advertisements

Entity Framework Core 1.0 : Reverse Engineering the Model (Database First Development)

This article uses Entity Framework Core 1.0.0

Database First Microsoft docs here

and here are the steps to build out your model from an existing database (aka. reverse engineer).

Create a new ASP.NET Web Application

c1.PNG

 

Open up your Package Manager Console

  1. Open Tools > NuGet Package Manager > Package Manager Console

    After we type in a command, the packages will automatically install in the background.  While the install is in progress you will see “(Restoring…)” next to the projects References folder.

  2. Type these 3 commands in the Package Manager Console: Install-Package Microsoft.EntityFrameworkCore.SqlServer –Pre
    Install-Package Microsoft.EntityFrameworkCore.Tools –Pre
    Install-Package Microsoft.EntityFrameworkCore.SqlServer.Design –Pre

Your Package Manager Console should look something like this:

pmc.PNG

Open up your project.json file

  1. Add “Microsoft.EntityFramworkCore.Tools” to the “tools” section. It should end up looking something like this:
"tools": {
  "Microsoft.EntityFrameworkCore.Tools": {
    "version": "1.0.0-preview1-final",
    "imports": [
      "portable-net45+win8+dnxcore50",
      "portable-net45+win8"
    ]
  },
  "Microsoft.AspNetCore.Server.IISIntegration.Tools": {
    "version": "1.0.0-preview1-final",
    "imports": "portable-net45+win8+dnxcore50"
  }
},

Run Auto Scaffold Command in Package Manager Console  (First Option)

  1. First, create a folder in your project named “Models”
  2. Second,  run this command in the Package Manager Console with your server and db info (note: single quotes around connection string, very unusual)
Scaffold-DbContext "'Server=SERVERNAME;Database=DATABASENAME;Trusted_Connection=True;'" Microsoft.EntityFrameworkCore.SqlServer -OutputDir Models

if connecting to a secure db, use something like this (note: no single quotes needed here! effin crazy!)

Scaffold-DbContext "Server=SERVERNAME;Database=DATABASENAME;user id=USERNAME;password=USERPASSWORD;" Microsoft.EntityFrameworkCore.SqlServer -OutputDir Models

After successfully running the above command, your project should now look something like this:

models.PNG

Run Auto Scaffold Command in Command Prompt  (Second Option)

Another way to run these commands is through the Command Prompt.  To run the scaffold command, open up your command prompt and navigate to the projects root folder.  Then run a command that looks like this:

dotnet ef dbcontext scaffold "Server=SERVERNAME;Database=DATABASENAME;user id=USERNAME;password=USERPASSWORD;" Microsoft.EntityFrameworkCore.&lt;wbr /&gt;SqlServer -o Models  --context MyDBDataContext --verbose

Thats it! This is suppose to become easier with the new version of Visual Studio.  Also, if your wondering how to get your SQL Server Views into your data context, check out this post.

 

Create your first ASP.NET Core 1.0 App From Scratch

A quick walk through of ASP.NET Core 1.0 on how to set up a MVC application from a “Blank” project.  Part 2, will demonstrate how to add Angular to your Core 1.0 App.

Create your web app!

Open up Visual Studio and select File > New > Project.  If you have ASP.NET Core 1.0 or higher installed (here is the .Net Core Installation guide) you should see and exciting new category under Templates > Visual C#  called .Net Core!
c1.PNG

  1. Select “ASP.NET Core Web Application”, give it a name, and click “OK”.
  2. Select the “Empty” template if asked.

Setup Project.json

Open up your project.json file. This will be new to you if you haven’t played with previous releases of vNext.

What is project.json?

Introduced in the first versions of ASP.Net vNext (which is now called ASP.NET Core), the project.json file defines your package metadata, your project dependencies and which frameworks you want to build for. (relatively similar to ASP.NET 4.x’s package.config). You can remove or add a dependency from this file. When you do, you’re solution will automatically be updated to reflect those changes. You can also set what frameworks you want your app to compile across here! Note that Microsoft has stated that project.json may go away around the time the next version of Visual Studio is released. The idea is that settings will move back to the .csproj file to enable better integration with MSBuild in that time frame.

To create a basic MVC app you will need to add the following dependencies to project.json:

  • “Microsoft.AspNetCore.Mvc”: “1.1.0”
  • “Microsoft.AspNetCore.StaticFiles”: “1.1.0”
  • “Microsoft.Extensions.Configuration.FileExtensions”: “1.1.0”
  • “Microsoft.Extensions.Configuration.Json”: “1.1.0”

And you will need to make sure “buildOptions: preserveCompilationContext” is set to true. After making these changes, your project.json should now look like this:

{
  "dependencies": {
    "Microsoft.NETCore.App": {
      "version": "1.0.1",
      "type": "platform"
    },
    "Microsoft.AspNetCore.Diagnostics": "1.0.0",
    "Microsoft.AspNetCore.Server.IISIntegration": "1.0.0",
    "Microsoft.AspNetCore.Server.Kestrel": "1.0.1",
    "Microsoft.Extensions.Logging.Console": "1.0.0",
    "Microsoft.AspNetCore.Mvc": "1.1.0",
    "Microsoft.AspNetCore.StaticFiles": "1.1.0",
    "Microsoft.Extensions.Configuration.FileExtensions": "1.1.0",
    "Microsoft.Extensions.Configuration.Json": "1.1.0"
 
  },
 
  "tools": {
    "Microsoft.AspNetCore.Server.IISIntegration.Tools": "1.0.0-preview2-final"
  },
 
  "frameworks": {
    "netcoreapp1.0": {
      "imports": [
        "dotnet5.6",
        "portable-net45+win8"
      ]
    }
  },
 
  "buildOptions": {
    "emitEntryPoint": true,
    "preserveCompilationContext": true
  },
 
  "runtimeOptions": {
    "configProperties": {
      "System.GC.Server": true
    }
  },
 
  "publishOptions": {
    "include": [
      "wwwroot",
      "web.config"
    ]
  },
 
  "scripts": {
    "postpublish": [ "dotnet publish-iis --publish-folder %publish:OutputPath% --framework %publish:FullTargetFramework%" ]
  }
}

Save and compile the project.json file and you should see that these packages have been added to your project’s references.

c2.PNG

Add the  ASP.NET Cofiguration file

Right-click your project > Add New… > Select new ASP.NET Configuration File and name it appsettings.json

c4.PNG

What is appsettings.json?

This is used to do some of what the web.config previously did.  It is hooked up to the applications Startup.cs file and can be used to set up things like database connections and logging preferences.

Setup Startup.cs

The Startup.cs file will look the same as it did in RC1.  The 3 main things we will change for our basic example application are the following:

  • Add a Startup() constructor method and link it to appsettings.js
  • Add the MVC service to ConfigureServices()
  • Configure the MVC the default routes (this replaces the old route config file) and tell the app to use static files in Configure()

After the above changes have been made, your Startup.cs should now look like this:

using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Hosting;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Logging;
using Microsoft.Extensions.Configuration;

namespace NewProject
{
    public class Startup
    {
        public Startup(IHostingEnvironment env)
        {
            var builder = new ConfigurationBuilder()
                .SetBasePath(env.ContentRootPath)
                .AddJsonFile("appsettings.json", optional: true, reloadOnChange: true)
                .AddJsonFile($"appsettings.{env.EnvironmentName}.json", optional: true)
                .AddEnvironmentVariables();

            Configuration = builder.Build();
        }

        public IConfigurationRoot Configuration { get; }

        // This method gets called by the runtime. Use this method to add services to the container.
        // For more information on how to configure your application, visit http://go.microsoft.com/fwlink/?LinkID=398940
        public void ConfigureServices(IServiceCollection services)
        {
            services.AddMvc();
        }

        // This method gets called by the runtime. Use this method to configure the HTTP request pipeline.
        public void Configure(IApplicationBuilder app, IHostingEnvironment env, ILoggerFactory loggerFactory)
        {
            loggerFactory.AddConsole();

            app.UseStaticFiles();

            app.UseMvc(routes =>
            {
                routes.MapRoute(
                    name: "default",
                    template: "{controller=Home}/{action=Index}/{id?}");
            });
        }
    }
}

Lastly, add your Controllers and Views

Right-Click your project and add 3 new folders.

  • Controllers folder
  • Views folder
  • Home folder, inside of the Views folder

Next, right-click the Home folder and add a new MVC View Page. Name it “Index.cs” and add some “Hello World” text to it.

After adding these folders and file, your project will now look like this:

c3.PNG

Finished!!!!

Check out the final project on GitHub
Build and run your application.  Congrats on keeping up with the cutting edge of .Net

Entity Framework Core: Modeling and Connecting to SQL Views

This post is based on EF Core 1.0 and it will be strictly about adding SQL Views to your Model and Data Context.  If you are interested on how to connect your EF Core 1.0 project to a SQL Server DB then check out this other post about how to reverse engineer and scaffold your SQL Server DB.

The state of EF Core 1.0 and VS2015
Unfortunately, that nice UI you were used too that allowed you to connect and select the tables and views to be mapped out, does not yet exist.  After setting up your project and project.json file you will run a script in the Command Prompt or in the Nuget Package Manager to connect and build out you EF model.  Will look a lil something like this:

Command Prompt Scaffle Command

dotnet ef dbcontext scaffold "Server=SERVERNAME;Database=DATABASENAME;user id=USERNAME;password=USERPASSWORD;" Microsoft.EntityFrameworkCore.<wbr />SqlServer -o Models  --context MyDBDataContext --verbose

Nuget Package Manager Scaffle Command

Scaffold-DbContext "'Server=SERVERNAME;Database=DATABASENAME;Trusted_Connection=True;'" Microsoft.EntityFrameworkCore.SqlServer -OutputDir Models

The above commands hook you up to your DB and creates a Model folder that contains all your newly generated classes and DataContext.cs.  But what about my views!?!?  Well, since your DataContext.cs is connected to your DB, you do technically have access to everything in that DB, including SPROCs and Views.  These Views just dont get created for you and there is no real way to access them except through inline SQL or manually adding them.  So lets manually add them together!

Create a new Class for your View

  1. Your project should have a Models folder (if you did everything here). Right click that Models folder and select Add > New Item.. > Class
  2. Name the Class “Team_View” and add this code to it.
    public class Team_View
    {
    public int Team_ID { get; set; }
    public int? Players_Count { get; set; }
    public double? Total_Wins { get; set; }
    public double? Total_Losses { get; set; }
    }
    
    

Add your new View’s Class to DataContext.cs

  1. In the Models folder, open up xxxxDataContext.cs. This file was automatically generated for you.
  2. In this class add this class object:
    public virtual DbSet<Team_View> Team_View { get; set; }
    
  3. In  OnModelCreating(ModelBuilder modelBuilder) add:
    modelBuilder.Entity<Team_View>(entity => { entity.HasKey(e => e.Team_ID); });
    
  4. Your DataContext should now look something like this
    public virtual DbSet<Team_View> Team_View { get; set; }
    
    protected override void OnModelCreating(ModelBuilder modelBuilder)
    {
    modelBuilder.Entity<Team_View>(entity => { entity.HasKey(e => e.Team_ID); });
    
    .......
    }
    

Also, note that the DataContext is a “Shared” class.  So if you don’t want to re-write this code every time you run the update scaffold command, putting code like this Team_View code in a separate shared DataContext.cs file may be the way to go.

Thats It!
You now have access you your View! AND you now have a Class for that view! You can now call it from any lambda/LINQ  query that your want.