DEPRECATED: This template is no longer maintained, in favour of the new Kubernetes enabled one

BLiP.API.Template

This template aims to kickstart the development of an API to be used alongside BLiP's Builder feature

Update Notice: From version 4.0 on, the template will use .NET Core 3.0

Installation

If you already have dotnet installed, you can install this template with the command

dotnet new -i Blip.Api.Template

If you don't have dotnet installed, follow these instructions from Microsoft to install it on GNU/Linux, Mac or Windows, and then use the command above.

Usage

To create a new project using this template, after installing, type in the following command

dotnet new blip-api

Your new project should be created in the open folder.

Renaming the Services project

By default, when you create a new solution using the template, all .csproj files will use the name of the folder you're in (along with any mentions of Blip.Api.Template. You can give the Services project a different name should you like it using the CLI param --Services.

For example, if you run the command

dotnet new blip-api --Services DifferentName.Services

inside a folder named Blip.Bot.Project, it will create a .sln with two projects: Blip.Bot.Project.csproj and DifferentName.Services.csproj, instead of a Blip.Bot.Project.Services.csproj.

File Structure

 📁Blip.Bot.Project // assuming your folder is called Blip.Bot.Project. Whatever name you choose will replace all occurrences of that string in the sln
 |__📁src
    |__📁Blip.Bot.Project // The Web API project Folder
    |   |__📁Controllers // This will not be created anymore as no default Controllers are provided.
    |   |   |__📃{YourControllers.cs} // You should definitelly create the folder yourself
    |   |   |__📃{...}
    |   |__📁Middleware
    |   |   |__📃{ErrorHandlingMiddleware.cs}
    |   |   |__📃{AuthenticationMiddleware.cs}
    |   |   |__📃{YourMiddlewares.cs}
    |   |   |__📃{...}
    |   |__📃MySettings.cs
    |   |__📃Startup.cs
    |   |__📃Program.cs
    |   |__📃appsettings.json
    |__📁Blip.Bot.Project.Facades // Project to use for any logic to be handled
    |   |__📁Extensions // Recommended architecture
    |   |   |__📃{ServiceCollectionExtensions.cs}
    |   |   |__📃{YourExtensionFiles}
    |   |__📁Interfaces // Recommended architecture
    |   |   |__📃{IAuthorizationFacade.cs}
    |   |   |__📃{YourInterfaceFiles}
    |   |__📃{AuthorizationFacade.cs}
    |   |__📃{YourServiceFiles}
    |__📁Blip.Bot.Project.Services // (If needed) The project to use for 3rd party APIs to be consumed
    |   |__📁Interfaces // Recommended architecture
    |   |   |__📃{YourInterfaceFiles}
    |   |__📃{YourServiceFiles}
    |__📁Blip.Bot.Project.Models // Models to be used by the Solution
    |   |__📁UI // Models directly used by the API project
    |   |   |__📃{ApiSettings.cs}
    |   |   |__📃{BlipBotSettings.cs}
    |   |   |__📃{YourUIModels}
    |   |__📃{Constants.cs}
    |   |__📃{YourSharedModels}
    |__📁Blip.Api.Template.Tests // It is strongly suggested that you try to cover most parts of your code
    |   |__{YourTestsFiles.cs}
    |__⚙️.editorconfig

Uninstallation

To uninstall the template from your local machine, use the command

dotnet new -u Blip.Api.Template

Your current projects that already use the template will not be affected.

Recommended Packages

This template comes bundled with a few highly recommended packages, such as Blip.HttpClient, RestEase, Serilog and Swashbuckle.AspNetCore. Those packages' repositories do a great job at explaining what they do, and it is strongly recommended that you familiarize yourself with them.

Furthermore, I will list some other interesting packages:

• For testing:
  • Shouldly: Assert library that makes it easy to read and understand tests assertions. For example:

  bex.Reason.Description.ShouldBe("The requested resource was not found");
  getResource.ShouldNotBeNull();
  exceptionThrown.ShouldBeTrue();

  • XUnit: Widely used Testing Framework for .NET
  • NSubstitute: Library that allows the mocking of 3rd party (or 1st party) services that act like black boxes, meaning that you can't access their source code and therefore it is not up to you (or not interesting for you) to test it, but you still need to verify if the required methods are at least being called. Note that, as it is a substitute, the actual method will not be called, meaning that it will not access any external sources. For example:

  Serilog.ILogger _logger = Substitute.For<ILogger>();
  // <...>
  // Substitute call that will not, in fact, log anything anywhere
  _logger.Received(1).Information(Arg.Any<string>(), Arg.Any<string>()); 
  // Checks if the Serilog.ILogger.Information method was called EXACTLY one time with two params, where both of them are strings

• For logging:
  • RestingLogger: easy-to-use RestEase-powered library that logs every request sent and response received from external APIs. Optimized and tested using Serilog while logging on SEQ. Note: might not work on other architectures.

Feature Roadmap

• Basic controller for external link tracking