ASP.NET MVC 5 with BDD ,Onion/Clean Architecture, Living documentation and a CI/CD pipeline from scratch

  • Article

To give you a little background, I was toying with an idea for a startup and wrote a quick application in ASP.NET as a POC for exploring a product idea (Reconcilation ) .Although I left the idea for the product   and the startup ,there are many things I thought would be good idea  to share with you.

Following are the ideas explored in this blog post

  • Write a RuleEngine in C# which is extensible and configurable
  • Follow a Behavior-driven development (BDD) approach to develop .In this case the full asp.net MVC app ,RuleEngine etc are developed using BDD.
  • Generate Living documentation from BDD specs .
  • Implement a CI/CD pipeline and deploy to Azure App Service
    • Visual Studio Team Services is configured to have CI/CD pipeline and automatic deployment  to Azure
    • As an alternate approach,implement similar CI/CD pipeline in another platform like AppVeyor
  • Get a basic understanding of Clean/Onion architecture

Writing a simple RuleEngine in C#

Writing a Rule Engine in C# is made easy with System.Linq.Expressions , since we followed BDD approach you can find a live documentaion generated from the test spec in the below link

https://finreconcile.azurewebsites.net/docs/Index.html?feature=Rules.feature

I have also created documentation in the wiki for the  RuleEngine.

https://github.com/rohithkrajan/FinReconcile/wiki/Rule-Engine

I will be writing another blog post covering how the ruleengine works  and what are the design choices but it is outside the scope of this post.

BDD approach

Before getting into BDD, let's recap Test Driven Development(TDD) .

Test-driven development  (TDD) refers to a style of programming in which you do  coding, unit testing and code refactoring . Here's a graphical representation of Test Driven Development

(By Xarawn - Own work, CC BY-SA 4.0, Link)

This is already a very good approach and is used universally across all technologies and frameworks.Then why BDD ??

 Imagine the test cases you generate is the documentation of how your application works,reflecting the user stories or scenarios.So BDD is TDD but with different way of writing the test cases. I would like to call it as  next step of  Test Driven Development(TDD).

We will be using a library called specflow for doing BDD. How to start with specflow can be found here  .

 

  • Create a Simple Class Library project
  • Add NUnit and Specflow
 Install-Package SpecFlow.NUnit
  • Install the Specflow extension for Visual studio
  • Get an understanding on Gherkin Format and how to write a simple spec
  • To Run the tests in Visual Studio,install NUnit Test Adapter
  • Once you have installed Specflow VS extension, Add a new Feature file and start writing tests.

More details can be found here 

Clean/Onion Architecture - create a asp.net mvc/webapi  project with clean/Onion architecture

Clean/Onion architecture is simple and extensible architectural approach you can easily approach to any project you start. At the center of it is your dependency injection and then everything revolves around it.So you may have a bunch of projects like this imagine your project name is Contoso

  • Contoso.Core
  • Contoso.Infra
  • Contoso.Web

You can also have additional cs projects ,there's been lot of talk on clean or onion architecture and you will find slight variations in different approaches but the core idea remains the same, please refer any of this link below

https://8thlight.com/blog/uncle-bob/2012/08/13/the-clean-architecture.html https://medium.com/\@stephanhoekstra/clean-architecture-in-net-8eed6c224c50

Implement a CI/CD pipeline

I have two implementation one on Azure Team Services and Another on Appveyor. The reason why appveyor is to easily give a public link like this

https://ci.appveyor.com/project/rohithkrajan/finreconcile/build/tests

I also have a wiki created in github for this

https://github.com/rohithkrajan/FinReconcile/wiki/CI-CD-Pipeline

An end to end build ,test and deploy pipeline is setup using VSTS and Azure app Services platform .In our case,I have not implemented automatic deployment from Appveyor because it is already done in Team Services .But you can see build and test in Appveyor.

Generate Living documentation from BDD specs

To generate docs , We will be utilizing a library called PicklesDoc

We can also integrate this with our CI/CD pipeline step using the package https://www.nuget.org/packages/Pickles.MSBuild/

 Install-Package Pickles.MSBuild

This package includes the MSBuild task and a build target that is automatically added to your .csproj.After installing this package,you can add following task to your csproj file

 <PropertyGroup> 
<Pickles_Generate>True</Pickles_Generate>
 <Pickles_DocumentationFormat>dhtml</Pickles_DocumentationFormat>
 <Pickles_OutputDirectory>C:\Temp\MyDocumentation</Pickles_OutputDirectory>
 </PropertyGroup>

The docs will be generated on the folder you specify Output directory. 

So living documentation helps when your project grows in complexity and size.The advantages are

  • Anyone can refer the documentations of your project for features Business users or Quality Analysts
  • Documentations will not go out of sync as it is generated from the code itself
  • Helps easily gives a mental picture of any complex piece of component in a step by step way

Going through the document generated is easier  when any new developer joins the project and may be he will become productive on day one :)

Hope this helps  with your next project especially if you are given an opportunity to start from scratch :) .But nothing stops you from improving a part of your complex project to BDD ,add a little documentation  or follow little bit of refactoring to implement a good clean or Onion architecture,isn't it ?