ASP.NET MVC 5 with BDD ,Onion/Clean Architecture, Living documentation and a CI/CD pipeline from scratch
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.
- Demo App - https://finreconcile.azurewebsites.net
- Slide Deck for easy summary -https://finreconcile.azurewebsites.net/finreconcile.html
- Source code
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
I have also created documentation in the wiki for the RuleEngine.
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.
Before getting into BDD, let's recap Test Driven Development(TDD) .
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).
- Create a Simple Class Library project
- Add NUnit and Specflow
- 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
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
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
I also have a wiki created in github for this
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/
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 ?