Tutorial

A step by step tutorial that will teach you the fundamentals of building and maintaining a project with Wrapt.

What are We Building?

Let's say that we want to create an application to manage recipes. We're going to call it CarbonKitchen and it should start out by storing recipes and their associated ingredients.

Creating a Template File

To get things started, we we are going to build a bare bones yaml or json file to lay out what we want our project to look like. This file is going to describe what our particular domain looks like and then we can add additional features and logic afterward.

Don't feel pressured to get this exactly correct from the get go. This file is NOT meant to be a concrete implementation of your API, just a starting point that you can build on over time.

So what's this file look like? Let's go over an example. For a full list of the configuration option details, you can go to the domain-template page.

Basic Domain and Bounded Context Setup

We're going to start out by creating a new yaml file and adding a domain name of CarbonKitchen.

DomainName: CarbonKitchen

Next, we need to lay out each of the logical contextual boundaries within our domain (a.k.a. bounded contexts). In this domain, three come to mind: 1) Recipes to store our recipes 2) Planning to store our meal plans and 3) Shopping to store our shopping lists. Let's start out with the RecipeManagement bounded context and name it with a property called ProjectName.

DomainName: CarbonKitchen
BoundedContexts:
  - ProjectName: RecipeManagement

Then, we'll describe our database set up for each bounded context using the DbContext property. I'm also going to set port to run on locally, but this is optional.

DomainName: CarbonKitchen
BoundedContexts:
  - ProjectName: RecipeManagement
    Port: 5005
    DbContext:
      ContextName: RecipesDbContext
      DatabaseName: RecipeManagement
      Provider: postgres

Entity Setup

Then let's add in our Recipe Entity with a variety of properties based on our requirements. Be sure to check the entity properties page to see what's required and what defaults are used. We're also going to add the features that we want for this particular entity.

DomainName: CarbonKitchen
BoundedContexts:
  - ProjectName: RecipeManagement
    Port: 5005
    DbContext:
      ContextName: RecipesDbContext
      DatabaseName: RecipeManagement
      Provider: postgres
    Entities:
      - Name: Recipe
        Features:
          - Type: AddRecord
          - Type: GetRecord
          - Type: GetList
          - Type: UpdateRecord
          - Type: DeleteRecord
        Properties:
          - Name: Title
            Type: string
          - Name: Directions
            Type: string
          - Name: RecipeSourceLink
            Type: string
          - Name: Description
            Type: string
          - Name: ImageLink
            Type: string

Note that Entities is a list, so we can add more than one if we want:

DomainName: CarbonKitchen
BoundedContexts:
  - ProjectName: RecipeManagement
    Port: 5005
    DbContext:
      ContextName: RecipesDbContext
      DatabaseName: RecipeManagement
      Provider: postgres
    Entities:
      - Name: Recipe
        Features:
          - Type: AddRecord
          - Type: GetRecord
          - Type: GetList
          - Type: UpdateRecord
          - Type: DeleteRecord
        Properties:
          - Name: Title
            Type: string
          - Name: Directions
            Type: string
          - Name: RecipeSourceLink
            Type: string
          - Name: Description
            Type: string
          - Name: ImageLink
            Type: string
          - Name: Ingredients
            Relationship: 1tomany
            ForeignEntityName: Ingredient
            ForeignEntityPlural: Ingredients
      - Name: Ingredient
        Features:
          - Type: AddRecord
          - Type: GetRecord
          - Type: GetList
          - Type: UpdateRecord
          - Type: DeleteRecord
        Properties:
          - Name: Name
            Type: string
          - Name: Unit
            Type: string
          - Name: Amount
            Type: double?

Creating a New Domain Solution

Now that we've put together our domain layout, let's actually build our solution. To start, make sure you've followed the install instructions. Then, open Command Prompt, Powershell, Terminal, etc. and cd to whatever directory you want to create your project repository in. Finally, we just need to run one command:

craftsman new domain C:\Users\Paul\Documents\WraptTemplates\NewCarbonKitchen.yaml

Note that the filepath here should match wherever you saved your yaml file. A relative path should also work.

Once that's done, Craftsman will have added an entire API for you in whatever directory you ran this in. Check out the project architecture and organization page for more details.

Using Your API

Now you can cd into your bounded context directory and run dotnet run --project {ProjectName} and your API is up and all the boilerplate taken care of 🥳

Adding a New Entity

So, we have this existing project, but what if we wanted to add a new entity to capture shopping list items so that we can add ingredients we need for our grocery outing? All we need to do is create another yaml or json file (based on the add entity template) that describes this new entity. Something like this:

Entities:
  - Name: ShoppingListItem
    Features:
      - Type: AddRecord
      - Type: GetRecord
      - Type: GetList
      - Type: UpdateRecord
      - Type: DeleteRecord
    Properties:
      - Name: Amount
        Type: double?
      - Name: Name
        Type: string
      - Name: Category
        Type: string
      - Name: Unit
        Type: string

Let's cd to the project that we want to add the entity to (for example):

cd C:\repos\CarbonKitchen\RecipeManagement

Then, we can add that entity to our project using the add entity command:

craftsman add entity C:\Users\Paul\Documents\WraptTemplates\ShoppingListEntity.yaml

Adding a New Bounded Context

So we built out the bounded context for our Recipes, but what if we wanted to add the Shopping bounded context? Let's make a new file (using a bounded-contexts template to capture those details:

BoundedContexts:
  - ProjectName: ShoppingManagement
    Port: 5010
    DbContext:
      ContextName: ShoppingDbContext
      DatabaseName: ShoppingManagement
      Provider: Postgres
    Entities:
      - Name: ShoppingList
        Features:
          - Type: AddRecord
          - Type: GetRecord
          - Type: GetList
          - Type: UpdateRecord
          - Type: DeleteRecord
        Properties:
          - Name: Store
            Type: string

Then we can go to our domain directory -- for example:

cd C:\repos\CarbonKitchen

Then we can use the add bc command to add the new context:

craftsman add bc C:\fullpath\my-new-bc.yaml

Customization

Great! Now we have a new project, but we want to add some custom business logic. Maybe we want to do some special validation when we're adding a new recipe or add another endpoint to manage ingredients in batch. This is all completely doable! For details, see the page on customizing Wrapt projects.

← InstallationProject Organization →