Getting Started 🚀

Let's get started with the .NET WebApi Boilerplate!

Firstly, make sure that you have already setup your development environment that runs the prerequisite tools and SDKs. Refer Development Environment for details.

This guide will take you right from strating up your own .NET Web API Project using fullstackhero .NET WebAPI Boilerplate package / repository to testing the API using the provided Postman Collection!

To get started with this Boilerplate, here are the avaiable options.

  • Forking the Repository. Use this if you want to always keep your version of the Boilerplate up-to date with the latest changes.
  • Install using dotnet new . Use this for release versions of the Boilerplate only. It might be very hard to update to the latest version of the Boilerplate using this option.

Forking the Repository & Creating your New Solution!

You would probably need to take this approach if you want to keep your source code upto date with the latest changes. To get started based on this repository, you need to get a copy locally.

  • Make a fork of fullstackhero’s dotnet-webapi-boilerplate repository in your Github account.
  • Next, since you need to start your private personal project, create your new dotnet-webapi-boilerplate personal project by cloning the forked repository on your personal github. This could be done as simple as running git clone https://github.com/{yourgithubuseraccount}/dotnet-webapi-boilerplate.git locally on your development machine.
  • Setup an upstream remote on your personal project pointing to your forked repository using command git remote add upstream https://github.com/{yourgithubuseraccount}/dotnet-webapi-boilerplate and git remote set-url --push upstream DISABLE

Now, whenever there is a new update on fullstackhero’s dotnet-webapi-boilerplate repository, you could simply pull in the latest change on your private fork of the fullstackhero’s dotnet-webapi-boilerplate repository and later merge these changes with you personal projects.

For step by step instructions, follow this and this.

Installing NuGet Package

This is by far the easiest and the most streamlined way of getting the latest available Release version of fullstackhero .NET WebApi Boilerplate.

Open up your Command Prompt / Powershell and run the following command to install the solution template.

dotnet new -i FullStackHero.WebAPI.Boilerplate

or, if you want to use a specific version of the boilerplate, use

dotnet new -i FullStackHero.WebAPI.Boilerplate::0.0.6-rc

This would install the fullstackhero .NET WebAPI Boilerplate template globally on your machine. Do note that, at the time of writing this documentation, the latest available version is 0.0.6-rc which is also one of the first stable pre-release version of the package. It is highly likely that there is already a newer version available when you are reading this.

To get the latest version of the package, visit nuget.org

FullStackHero.WebAPI.Boilerplate is now in pre-release state. You can find the latest version on NuGet.org

Creating your First Solution

Note that this is not valid only if you have installed the NuGet package of this Boilerplate.

Now that you have installed the template locally on your machine, let’s see how you can start generating complete .NET WebAPI Solutions seamlessly.

Simply navigate to a new directory (wherever you want to place your new solution at), and open up Command Prompt at the opened directory.

Run the following command. Note that, in this demonstration I am naming my new solution as FSH.Starter.

dotnet new fsh-api -o FSH.Starter

Once that is done, your new solution is created for you. As simple as that!

Here are the folders and files created for you.

Alternatively..

Note that this is valid only if you have installed the NuGet package of this Boilerplate.

When you installed the NuGet package, there is also an entry that has been created into your Visual Studio Template for fullstackhero’s .NET WebAPI Boilerplate. If you find it easier to work with Visual Studio rather than CLI Commands to generate new solutions, you are free to do so.

Simply open up Visual Studio 2022 and Click on Create New Project.

Important - Make sure to check the ‘Place solution and project in same directory’ option. Else the solution and projects will be created on different folders and there will be build errors stating that few files are not found.

Another issue I noticed with creating solutions via Visual Studio is that the Solution structure might be lost. This is a very minor bug, that maybe someone can figure out and fix in our template configuration. Microsoft doesn’t seem to have very detailed guide about this.

However, it’s always recommended to create new solutions via the Console.

Running the Application

Next, open up command prompt on this directory and run the following.

code .

This opens up the solution via Visual Code. Make sure that you have the prerequisite tools and SDKs setup.

Setting up the Connection String

Next, let’s set up some valid connection strings. Navigate to src/Host/Configurations and open up database.json. Here you would have to provide a valid connection string under the DatabaseSettings to either MSSQL, MySQL or PostgreSQL instance. Below are some sample settings for each of the DB Providers.

Details on the usage of other Settings will be explained in the upcoming documentations.

MySQL

"DatabaseSettings": {
    "ConnectionString": "server=localhost;uid=root;pwd=root;database=defaultRootDb;Allow User Variables=True",
    "DBProvider": "mysql"
  }

MSSQL

"DatabaseSettings": {
    "DBProvider": "mssql",
    "ConnectionString": "Data Source=(localdb)\\mssqllocaldb;Initial Catalog=rootTenantDb;Integrated Security=True;MultipleActiveResultSets=True"
  }

PostgreSQL

"DatabaseSettings": {
    "ConnectionString": "Host=localhost;Database=rootTenantDb;Username=postgres;Password=root;Include Error Detail=true",
    "DBProvider": "postgresql"
  }

Oracle

{
  "DatabaseSettings": {
    "DBProvider": "oracle",
    "ConnectionString": "Data Source=(DESCRIPTION=(ADDRESS=(PROTOCOL=TCP)(HOST=127.0.0.1)(PORT=49154))(CONNECT_DATA =(SERVER=DEDICATED)(SERVICE_NAME=ORCLPDB1.localdomain)));User Id=fullstack;Password=password123"
  }
}

Now you need to navigate to the Host (API) Project directory via CMD or VSCode’s native terminal and run the basic build and run command to get the API up and running. Run the following.

 cd src/Host
 dotnet build
 dotnet run

As you can see from the logs, a couple of operations happen as soon as you launch the application. Let me give a brief idea on what happens when you run the application for the very first time.

  • The Migrations that already come out-of-the-box with the application gets applied. Note that you do not have to manually update the database using code.
  • Being a Multitenant solution, the Application is programmed to seed a default Tenant named root, that is basically the super-admin of the entire application and has permissions to manage tenants.
  • Once Tenant record is seeded, the tenant admin , roles and permissions are also seeded. Note that the default credentials for the root tenant admin are as follows.
{
    "email":"admin@root.com",
    "password":"123Pa$$word!"
}
  • The Connection String that you provided in the appSettings will be taken as the root Tenant’s Connection. Note that all the tenant data will be stored on to this connection under the Tenants table.

Like fullstackhero? ❤️

Here is what you can do to show your support!

Buy me a Coffee ☕ Sponsor 😍