Development

If you are a member of the Suite Team, a member of a Team developing Suite Services, or a contributor, just passing by and wanting to throw a PR, you must read this entire section.

Anyone can contribute to the Suite. If you find something broken and went down the rabbit hole and have a possible fix, don't hesitate to throw a PR and let's discuss it!

Important

In this section we will cover many of the common questions asked when starting to develop in the Suite Monorepo. Please do read, and use the search feature.

Setup Development Environment

First things first, let's make sure your workstation is ready to build the Suite.

Requirements

Make sure your system fulfils the following requirements, which should be installed on new machines provided by the Infrastructure Department.

1. Docker with WSL2. The previous VirtualBox/Docker Toolbox will not work. You can check this by opening the Docker Desktop app and in settings look for the WSL2 checkbox. If you don't have the app, please contact Infrastructure or the Suite Team on MS Teams. Download links
2. Git
3. Any Unix Shell
   1. On Windows: Git Bash
   2. On Linux/MacOS: The Built-in terminal

Note for Windows users

It is super important that you use a UNIX Shell, like Git Bash. If you want to use WSL instead, you will not be able to open Visual Studio and will need to develop on VSCode. That's why we re commend Git Bash.

When working on the Suite, make sure you run all commands in a UNIX Shell, like Git Bash on Windows. We use Bash scripts in order to be able to work cross-platform. We do this since our CI system is on Linux, and some developers are on Linux as well. This is great since we want to deploy on Linux eventually, hence we always target cross-platform.

Feel free to download Windows Terminal and use that to open Git Bash in order to have a nicer appearance.

Authenticating against Azure DevOps

The ITsynch Suite's repository is hosted on Azure DevOps.

To login using the web page, you will use your Microsoft Account (the one for Office 365).

However, when using git, you need to use SSH Keys.There are other ways to connect, like generating a random username/password, but we want to use SSH keys instead since other methods expire and require regenerating credentials. SSH keys are an industry standard used everywhere to authenticate against git repositories.

Generating an SSH Key

If you don't have an SSH key, you'll need to generate one. This is a public and private key pairs. The private key must be kept private (duh..) and the public one is intended to be shared.

Check to see if you already have an SSH Key

You can check to see if you already have an SSH key at the standard path by running:

cat ~/.ssh/id_rsa.pub

If it returns empty, you need to generate an SSH key using ssh-keygen.

ssh-keygen

The below command can be used to generate a new SSH key. We recommend you do not set a passphrase (just press enter), since you'll need to type it regularly. That being said, feel free to set a passphrase if you want to.

ssh-keygen -t rsa -C "<your-itsynch--email>@itsynch.com"

You'll get an output similar to this:

Generating public/private rsa key pair.
Enter file in which to save the key (/c/Users/rrivera/.ssh/id_rsa):
Created directory '/c/Users/rrivera/.ssh'.
Enter passphrase (empty for no passphrase):
Enter same passphrase again:
Your identification has been saved in /c/Users/rrivera/.ssh/id_rsa
Your public key has been saved in /c/Users/rrivera/.ssh/id_rsa.pub
The key fingerprint is:
SHA256:******************************************* rrivera@itsynch.com
The key's randomart image is:
+---[RSA 3072]----+
|         .++*+o. |
|         .+=+.   |
|         oB*=+   |
|         =BOo.. .|
|        S++=.  *.|
|        . = . B .|
|    +    o   =   |
|   o o ...    .  |
|      ooE.       |
+----[SHA256]-----+

Add SSH Public Key

Then, we need to add the newly created SSH key public portion to Azure DevOps.

1. Go to the SSH Public Keys page in Azure DevOps
2. Click on Add Key, type in a name like "Local Dev SSH Keys". (any name will do)
3. You then need to paste the Public Key portion into the form. You can get the public key by running cat ~/.ssh/id_rsa.pub. You'll get something that starts with ssh-rsa and ends with your ITsynch email. Paste that into the form.

If you face any trouble during setup, please read the official Azure Devops SSH Keys docs and ensure your problem is not listed there. In case that doesn't help, you know where to reach us ;)

Cloning the Repo

Next, you can proceed to clone the git repo. You can do so with the following command.

Tip

If you are on Windows, clone the repo at C:/ITsynch/Development. On UNIX, we should be using a path inside your $HOME directory. It's not a requirement, just best practice.

git clone git@ssh.dev.azure.com:v3/itsynch/ITsynch.Suite/ITsynch.Suite

Make sure Git is configured correctly

Before continuing, it's important to make sure that Git has configured the user.name and user.email correctly.

We can do this by executing the following commands:

Tip

You can check your current values (and perhaps have a laugh at them?) by running the commands without values. i.e git config --global user.name.

git config --global user.name <your name as shown on MS Teams>
git config --global user.email <your company email address, @itsynch.com>

These commands will configure the name and email that is associated with every Git Commit. This makes it so that Azure DevOps displays the commit information correctly.

Opening VSCode

This should download the entire repository at ITsynch.Suite directory including all projects belonging to the new Suite.

For editing the files we use VisualStudio for C# files only, and everything else with VSCode.

You can quickly open up VSCode on the root of the repo (always open it at the root!) by running:

code ./ITsynch.Suite

The first time you open VSCode it will prompt you to install required extensions, please install everything that is recommended. You can read more about extensions at the VSCode section

Note

Until you build, VSCode or VisualStudio may show warnings or errors until you build the projects generating the required files. Don't worry about them just yet. Once you get up and running, we do have a 0 warning policy.

Running Setup Scripts

We have developed some scripts to help setting up the environment, we wanna get you coding as quickly as possible!

The script will install the required .NET SDKs and validate that Docker is installed, and also install the Suite Templates and Tools.

Note

The setupEnvironment script will download and install the required SDKs on a subdirectory of the repository (/dotnet/.dotnet). You do not need to manually install the .NET SDK. Also if you already have a .NET SDK installed globally on your machine, it will be ignored.

From the root of the repo, run the below command. Remember to use the correct UNIX shell.

Tip

Inside VSCode, you can CTRL + J to open a shell, or Right Click a directory > Open in Integrated Terminal

./scripts/setup-environment.sh

This script can take several minutes to finish as it needs to download the .NET SDK from the web. Hopefully no errors are displayed, and if they are displayed hopefully they are easy to fix. Do let us know if you find any issues!

Activating the Development Environment

After running the Setup Script your environment should be ready to be used, but first you have to activate it, to do so you need to run the following command:

cd dotnet
source activate.sh

You will receive a message informing you that the .NET environment was enabled. This will allow you to use the dotnet command from the SDK installed locally on the repo directory.

After activating the environment, you should be able to create new projects using Templates and execute Tools

Warning

When running dotnet commands you must always use an activated environment. Pay attention to the prompt, it will clearly tell you if the environment is activated.

Tip

You can run the activation command multiple times on the same shell without causing any problems, so when in doubt just run it again.

Opening Visual Studio

To open Visual Studio, we first need to Generate the Solution file of the Bounded Context we are interested in seeing.

This is done due to the nature of the monorepo, which includes hundreds of .NET projects which is not desired to load all at once, since we are not working on all of them.

To generate a solution, we can run the below command replacing DataSync with the Bounded Context you want to open. For other opening options please make sure you have read the complete documentation on solution files

./slngen.sh DataSync

Tip

If you just want to open Visual Studio right away, you do not need to activate the environment, the slngen.sh script will do it for you, the Visual Studio instance will automatically use the correct environment.

Tip

Optionally you can run the slngen.sh script using the source command e.g. source slngen.sh DataSync, this will keep the environment activated on the shell after opening Visual Studio.