Swagger and Swashbuckle with ASP.NET Core API

This post is going to walk through adding Swagger to an existing ASP.NET Core API application using Swashbuckle. The starting point for the code can be found here.

What is Swagger?

Swagger is a specification on documentation an API. As I am sure we all know API documentation tends to get out of date fast and a lot of times is a low priority.  Swagger aims to help solve that problem using a format that is both human and machine readable which can be maintained in either JSON or YAML and can be auto generated using a tool like Swashbuckle. Check out this post by the Swagger team for the full introduction.

What is Swashbuckle?

Swashbuckle provides auto generation of Swagger 2.0, swagger-ui integration, etc. The project takes all the pain out of getting going with Swagger as well as providing tools and hooks for using and customizing Swagger related items. The full description can be found here.

Adding Swashbuckle to the project

There are lots of ways to get a new package into an ASP.NET Core application and the following covers the NuGet UI, Package Manager Console and Project.json. Pick one of them to use.

NuGet UI

Right click on the project Swashbuckle is going to be added to, Contacts in the case of the sample code, and select Manage NuGet Packages.

swashbuckleprojectmenu

Select the Browse tab, check the Include prerelease checkbox and search for Swashbuckle. Prerelease is need to get the version that works with ASP.NET Core.

swashbucklenuget

Finally click the Install button and work though any confirmation dialog screens that might show.

Package manager console

From the package manager console run  Install-Package Swashbuckle -Pre.

Project.json

Open porject.json and in the  dependencies section add  "Swashbuckle": "6.0.0-beta902".

Add and configure Swashbuckle

In the  ConfigureServices function of the  Startup class add the following. I added it as the end, but placement shouldn’t matter.

Next in the  Configure function after  app.UseMvc add the following.

The first line enable serving of the Swagger JSON endpoint and the second enables the swagger-ui.

Test it out

Running the application will now provide two new routes one or each of the items added to the  Configure function above.

The first is  http://localhost:13322/swagger/v1/swagger.json (your base URL may differ if not using the sample procject) and it exposes the Swagger compliant JSON.

The second URL is  http://localhost:13322/swagger/ui and it provides a very readable view of the documented API along with examples and options to try the API out. The following as an example of what the current version outputs.

swaggeruiexample

Wrapping up

Swashbuckle make it easy to add Swagger to a project. I feel that it also provides a huge value for anyone trying to consume an API. It is of course not a magic bullet and communication with your API consumers about API changes will still be critical.

Microsoft’s docs has a great walk through which can be found here. It does more in-depth on customizing your setup and as far as modifying the look of the UI.

The code for this post in it’s finished state can be found here.

Angular 2 with an ASP.NET Core API

This week’s post is going to take the Angular 2 application from a couple of weeks ago and add the same functionality currently present in the Aurelia application found the ASP.NET Core Basic repo. This release is the starting point for the solution used in this post.

Starting point overview

When you download a copy of the repo you will find an ASP.NET Core solution that contains three projects. The Angular project is where this post will be focused.

The Contacts project has a set of razor views and a controller to go with them that support standard CRUD operations, which at the moment is the best way to get contact information in the database. It also contains the ContactsApiController which will be the controller used to feed contacts to the Angular 2 and Aurelia applications.

Multiple startup projects in Visual Studio

In order to properly test the functionality that will be covered here both the Contacts project and the Angular project will need to be running at the same time. Visual Studio provides a way to handle this. The Multiple startup projects in Visual Studio section of this post walks through the steps of setting up multiple startup project. The walk through is for the Aurelia project, but the same steps can be applied to the Angular project.

Model

Create a contacts directory inside of  ClientApp/app/components/ of the Angular project. Next create a  contact.ts file to the  contacts directory. This file will be the model of a contact in the system. If you read the Aurelia version of this post you will noticed that this model is more fully defined since this project is using TypeScript the more fully defiled model provides more type safety. The following is the contests file.

Service

To isolate HTTP access the application will use a service to encapsulate access to the ASP.NET Core API. For the service create a  contact.service.ts file in the  contacts directory of the Angular project. The following is the code for the service.

This class uses Angular’s HTTP client to access the API and download a list of contacts. Angular’s HTTP client uses reactive extensions and returns an observable. In this case we don’t need an observable so for this service the observable is being converted to a promise. Then from there the response from the API is being converted an array of type  contact.

Also make note of the  Injectable decorator which tells Angular 2 the class should be available for dependency injection.

View Model

The next step is to create a view model to support the view that will be used to display the contacts download from the API. Add a file named contactlist.component.ts to the contacts directory of the Angular project. The following is the full contents of the view model file. This will be followed by a breakdown of the file in order to highlight some parts of the file.

The import statements are pulling in a couple parts of the Angular 2 framework in addition to the contact model and contact service created above.

Next is a component decorator which marks the class as an Angular component and provides a method to set metadata about the class.

The selector property sets the identifier for the class to be used in templates. The  template property sets the view that should be used with the view model. In this case it is requiring in another file, but it could also contain the actual template that should be used to render the component. An alternate is to use templateUrl to point to an external file containing a template. The final property used in this example is the  providers  property which is a list of providers that the framework needs to be made available to the component, in this case the  ContractService. For more information on the component decorator check out the Angular docs.

The next thing of note on this class is that it implements  OnInit.

OnInit is one of Angular’s lifecycle hooks, see the docs for the rest of the available hooks.  OnInit is called once after component creation and runs the  ngOnInit function which in the case of this class is being used to get a list of contacts from the  ContactService.

View

For the view create a  contactlist.component.html in the  contacts directory of the Angular project. This is the file that the veiw model created above is bound with to display the contact data retrieved from the API. The following is the complete contents of the view file.

The second line repeats the li tag for each contact in the contacts array of the view model class.  {{expression}} is Angular’s syntax for one way data binding.  {{contact.name}} does a one way binding to the  name property of the current contact in the  *ngFor loop. For more details on the different options available for data binding see the docs.

Add menu

The final piece is to add an item to the menu from with the contact list can be accessed. Open  app.module.ts in the  ClientApp/app/components/ directory. Add an imports for the  ContactListComponent.

Next add a new path to the  RouterModule. The third from the bottom is the line that was added for the contact list.

Finally open the navmenu.component.html file in the ClientApp/app/components/navmenu/  directory. Add a new  li for the contact list matching the following.

Wrapping up

That is all it takes to consume some data from an ASP.NET Core API and use it in an Angular 2 application. I can’t stress enough how easy working with in the structure provided by JavaScriptServices helped in getting this project up and going quickly.

The completed code that goes along with this post can be found here. Also note that the Aurelia project has be redone as well also based on JavaScriptServices and TypeScript so that the applications will be easier to compare.

Aurelia with JavaScriptServices: Call to Node module failed

This is going to be a quick post on how to solve an error I go on a new Aurelia project created using JavaScriptServices. For a walk though of creating a project using JavaScripServices check out this post.

The problem

The project got created and would build with no issues, but when I tried to run it I got the following error.

Call to Node module failed with error: Error: Cannot find module ‘./wwwroot/dist/vendor-manifest.json’

The fix

After a little bit of searching I came across this issue on the JavaScriptServices repo with the same error. One of the comments on the issue suggested running the following command from a command prompt in the same directory as your project.

After running that command everything worked like a charm! It is worth noting that the command above can be found in project.json in the scripts prepublish section. From the little bit of reading I did it looks like this command should be rerun anytime a new vendor dependency is added.

JavaScriptServices

I can’t get over how awesome JavaScriptServies is. Steve Sanderson (and team) have done an amazing job. Even with this little hiccup I got this new project up and running 10 times faster than I would have otherwise. It is also going to give me a push to look into webpack.

Angular 2 with ASP.NET Core using JavaScriptServices

This was going to be the fist in a series of posts covering getting started using the RTM versions of ASP.NET Core and Angular 2 together which was going to follow a similar path as the series on Aurelia and ASP.NET Core the first entry of which can be found here.

In the process of writing this post I was reminded of JavaScripServices (they recently added Aurelia support!) and will be using it to get this project up and running instead of doing the work manually.

The code found here can be used as a starting point. The repo contains a solutions with an ASP.NET Core API (Contacts) project and a MCV 6 (Aurelia) project. This post will be add a new MVC 6 project for Angular 2.

JavaScriptServices introduction

JavaScriptServices is an open source project by Microsoft for ASP.NET Core developers to quickly get up and running with one of many JavaScript front ends. The following is their own description.

JavaScriptServices is a set of technologies for ASP.NET Core developers. It provides infrastructure that you’ll find useful if you use Angular 2 / React / Knockout / etc. on the client, or if you build your client-side resources using Webpack, or otherwise want to execute JavaScript on the server at runtime.

The great thing about using the generator that JavaScriptServcies provides is they handle the integration between all the different tools which can be challenging to get right on your own without a lot of time and research.

Project creation

First step is to install the Yeomen generator via npm using the following command from a command prompt.

When installation is complete create a new directory call Angular for the project. In the context of the repo linked above this new directory would be in Contact/src at the same level as the Aurelia and Contacts folders.

Open a command prompt and navigate to the newly created directory and run the following command to kick off the generation process.

This will present you will a list of frameworks to choose from. We are going with Angular 2, but Aurelia, Knockout, React and React with Redux are also available.

yoangular2

Hit enter and it will ask for a project name which gets defaulted to the directory name so just hit enter again unless you want to use a different name. This kicks off the project creation which will take a couple of minutes to complete.

Add new project to existing solution

To include the new Angular project in an existing solution right click on the src folder in the Solution Explorer and select Add > Existing Project.

addexisitingproject

This shows the open file dialog. Navigate to the directory for the new Angular project and select the Angular project file.

addexisitingprojectangular

Wrapping up

Set the Angular project as the start up project and hit run and you will find yourself in a fully functional Angular 2 application. It is amazing how simple JavaScriptServices makes getting started with a new project.

The tool setup seems to be one of the biggest pain points with any SPA type JavaScript framework. Aurelia is a little friendlier to ASP.NET Core out of the box than Angular 2, but it still isn’t the simplest process ever. JavaScriptServices is one of those thing I wish I had tried out sooner.

In the near future I am going to redo the Aurelia project in this solution using JavaScriptServices. From there I will come back to the Angular project created in this post and integrate it with the Contact API used in the existing Aurelia application.

Completed code for this post can be found here.

Upgrading to npm 3 or 4

As part of writing a post on getting Angular 2 working with ASP.NET Core I needed to upgrade to npm verson 3. All went well on my main machine, but when I tried it on my laptop things didn’t go so well. No matter how many times I ran  npm install -g npm the version returned via  npm -v always returned 1.4.9.

After a bit of googling I came across this post on Stack Overflow. The post also points to npm’s github wiki on the upgrade process which can be found here. I am going to go over the option that I used to get my laptop upgraded.

Open an administrator command prompt and navigate to the install directory for nodejs. This should be either  C:\Program Files (x86)\nodejs or  C:\Program Files\nodejs and then run  npm install npm@latest.

Now if you run  npm -v you should see a 3.x version of npm.

npm 4

Since writing this npm 4 has come out. The above should still apply if you find that npm is stuck as a previous version. Check out the npm release notes page for details.

Migration from ASP.NET Core 1.0.x to 1.1

On November 16th .NET Core 1.1 was released including ASP.NET Core 1.1 and Entity Framework 1.1. Each of the links contain the details of what was including in the 1.1 release. Unlike some of the previous migrations this is pretty simple.

I will be using my normal ASP.NET Basics solution for this upgrade. The examples will be out of the Contacts project. This post is coming out of order so the repo that goes with this post will contain some items not covered in posts yet. The starting point of the repo can be found here.

Installation

Make sure you already have Visual Studio 2015 Update 3 installed with .NET Core 1.0.1 tools Preview 2 installed. If not use the previous links to install the needed versions. Next head over to the download page for .NET Core and under All downloads and select Current and SDK and select the download for your OS.

downloaddotnet

Another option is to install Visual Studio 2017 RC which can be found here.

Project.json

Project.json is the file that contains all the versions of assembles used by the application. A couple of items need to edited by hand and the rest can be updated using NuGet UI or you can change them all by hand if you like.

First the by hand items. The platform version needs to be updated to 1.1.

The second by hand item is the net core app version in the frameworks section.

Here is the resulting dependencies and tools sections.

Make note that using the NuGet UI will update the dependencies but not the tools section. For some reason the tools section doesn’t seem to have intellisense so I ended up searching the NuGet site to find the new versions. If you do end up changing the tooling version I recommend doing a  dotnet restore in the project directory from the command prompt to ensure the proper versions get downloaded.

Wrapping up

As I said this was a really pain less migration. Make sure you check out the release pages ( .NET Core 1.1ASP.NET Core 1.1 and Entity Framework 1.1) for the details on what has changed. For example ASP.NET Core has gotten significant performance increases with this release as well as URL Rewriting Middleware and Response Caching Middleware.

It has been less than six months since the initial release of ASP.NET Core until the 1.1 release which a huge increase in the pace of releases compared regular ASP.NET. From what I have see this is a pace the team will continue. Check out the roadmap for a preview of things coming in 1.2.

The code in its final state can be found here.

Cross-Origin Resource Sharing (CORS) in ASP.NET Core

Cross-Origin Resource Sharing (CORS) deals with sharing of restricted resources requested from outside the domain which made the request. Check out this Wikipedia article for a good over view of the subject.  If you read the post on Aurelia with an ASP.NET Core API then you might recall that cross-origin requests had to be enabled to allow the front end project to communicate with the API project.

When working on the post mentioned above I only spent enough time on the CORS options in ASP.NET Core to get the sample up and running. This post is going to expand on the path I used to get my sample working and explore some of the options ASP.NET Core offers. The official ASP.NET docs were very helpful in this exploration.

Starting point

In the API project the following was added in the Configure function of Startup in to allow any request regardless of headers, method or origin.

Limiting CORS

The above leaves the site wide open for cross-origin requests. Unless you have a need to allow any request it seems like a good idea to limit CORS. Keep in mind I am pretty new to the subject and my sure there are many nuances that will need to play into a live CORS strategy. For example the following limits CORS request to the two domains listed and only allows GET and POST.

Note that origins are identified by scheme, host and port all being the same. For example all of the following would be considered different origins.

URLs with different origins
http://google.com
https://google.com
http://www.google.com
https://www.google.com
http://google.com:5000
https://google.com:5000
http://google.com:6000
https://google.com:6000
http://bing.com

Set CORS on a Controller or Action

MVC doesn’t force the whole site to use the same CORS settings. Just like with authorization CORS can be set by Controller or Action. To use this style of CORS  ConfigureServices function of the  Startup class needs to add CORS as a service and setup one or more policies. The name of the policy will be used with  EnableCores attribute to specify where the policy is applied.

In  ConfigureServices add  app.AddCors which will allow additions of policies and make the available to controllers and actions. The following example adds an “AllowGoogle” CORS policy that allows http://google.com with any header and any method.

Then to apply this policy to a controller or an action add the  EnableCors attribute. The following example is applying “AllowGoogle” policy to the whole  HomeController.

Now if you want to exempt the  Index from the “AllowGoogle” CORS policy use the  DisableCors attribute.

Wrapping up

I am sure the CORS subject goes much deeper than what I covered today, but I wanted to share what I have learned so far as it applies to ASP.NET Core. If you have more resources or have something to add please leave a comment.

Visual Studio 2015 Team Explorer Fails to Undo Changes Using Git

At times I will make some quick changes to a project in Visual Studio to try something out knowing that I will undo the changes when done. Most of the time this works great with no problems, but a few times I am unable to get Visual Studio to undo the changes. Fist I am going to review the steps I normally use to undo and then I will cover the steps I use when files refuse to be undone. Just to be clear I am using Git base source control.

Normal undo changes

Normally when I am ready to undo a set of changes I open the Team Explorer window and select Changes from the drop down at the top of the window. Next I right click on the file, files, or directory I want to undo changes on and click Undo Changes.

undochanges

This show a message box asking for confirmation before undoing the changes. Click Yes to undo the changes.

undochangesyesnomessagebox

If all goes well the select files and/or directory will have reverted and no longer have any changes.

Undo failed now what?

If you undo didn’t clear the changes as expected now what? Well the best answer I have found is to open a command prompt and navigating to the directory that contains the file that needs to be undone and then run the following command. In this example the changes to gulpfile.babel.js  will be undone. This will work for both added and changed files.

If you want to undo all the changes in a branch it takes a couple of commands. This first command will remove all changes to tracked files including staged files.

Next if you have any files that were added (or not already tracked by Git) the following command will remove them.

Your repo will be back to its starting state as if it had just been cloned.

Caution

When using the above commands be careful as any changes will be gone and Git will have no record of them. For added files the file will be removed and again Git will have no record of the file. This mean these operations are permanent and should be used with a great deal of caution.

Aurelia with ASP.NET Core: Host Aurelia from a Controller

This is the forth entry in a series using Aurelia and ASP.NET Core together. Each post builds on the previous and all the code is available on Github.

Part 1 – Add Aurelia to an ASP.NET Core Project
Part 2 – Aurelia with an ASP.NET Core API
Part 3 – Aurelia with an ASP.NET Core API: Modeling and Displaying Data in Aurelia
Part 4 – Aurelia with ASP.NET Core: Host Aurelia from a Controller (this post)
Github repo with the code for all of the parts with a release to go with each post

The goal

So far the Aurelia application in this series has existed outside of the the ASP.NET Core application. This post is going move the Aurelia application to be hosted by a MVC controller and a razor view. This would allow an existing application to slowly be ported to Aurelia or allow portions of an application to be replaced by Aurelia as it made sense, etc.

The controller

The controller isn’t going to be doing much other than returning a view that contains the entry point for the Aurelia application. This example will be using a new Aurelia  action on the  HomeController.

The view

Next create a view in the Views/Home folder named  Aurelia.cshtml to match the name of the action added to the  HomeController above. Right click on the Home folder and select Add > New Item.

addnewitem

This will show the Add New Item dialog. Using the search in the upper right corner serach for MVC and select MVC View Page. Enter Aurelia.cshtml as the name and click Add.

Enter the following in the newly created file.

This code defines a div that will host an Aurelia application named main.

Add a link to the Aurelia application

Inside of the Views/Shared folder open _Layout.cshtml which is where the MVC application’s navigation bar is defined. Locate the navigation bar code and add a list item and link that points to the  HomeController  Aurelia action defined above. The following is the full navigation bar for the MVC application including the new link for Aurelia.

Adjust Aurelia’s baseUrl

Finally inside the aurelia_project folder open  aurelia.json and adjust the  baseUrl property inside the  targets section to look for the scripts folder to be up one directory. This is required now with the Aurelia application being hosted inside the  HomeController which will cause the Aurelia application to look for its scripts in the Home/Scripts folder instead of the site’s main scripts folder. If you are going to have multiple Aurelia applications per MVC application then you may need to take a different path on this section.

Wrap up

Run the application and click the Aurelia link in the navigation bar and the Aurelia application from last week will run, but now it will still have the navigation bar from the MVC application showing. The  index.html file located in the wwwroot folder that was previously used to host the Aurelia application can be deleted.

The code associated with this post can be found here.