:toc:

= Environment Setup

toc::[]

== Overview

This guide will explain how to configure the full system environment to make the Devon4Net.Template.WebAPI operate in Visual Studio Code. 

== Required software
https://code.visualstudio.com/[Visual Studio Code]

https://dotnet.microsoft.com/en-us/download[.Net Core SDK]

https://marketplace.visualstudio.com/items?itemName=ms-vscode.csharp[C# Extension for VS Code]

== Setting up the environment

=== For Windows

==== Visual Studio Code
Download and install *Visual Studio Code*:

. Download the latest version https://code.visualstudio.com/[here]
+
.Download Page
image::images/environment-1.png[]


. Open the downloaded installer, accept the terms and conditions, and then click next:
+
.License Agreement
image::images/environment-2.png[]

. Select the location where Visual Studio Code will be installed. :
+
.Destination Folder
image::images/environment-3.png[]

. Check the option if you do not wish to create a Start Menu folder, then click next:
+
.Start Menu Setup
image::images/environment-4.png[]

. Check the boxes next to the options you wish to install for your environment, and then click next:
+
TIP: Select the "Open with Code" options; this is a really useful tool, and if you don't mark them, you won't be able to configure them again unless you reinstall the application. 
+
.Setup Additional Tasks
image::images/environment-5.png[]

. Select next to begin the installation:
+
.Final Setup
image::images/environment-6.png[]

. Select finish to end the installation and launch visual studio code:
+
.Completed Instalation
image::images/environment-7.png[]

==== .Net Core SDK

Download and install *.Net Core SDK*:

. Download https://dotnet.microsoft.com/en-us/download[.Net SDK x64 for .Net 6.0]
+
.Download Page .Net 6.0
image::images/environment-8.png[]

. Open the downloaded installer, and click on the install button:
+
.Microsoft .NET SDK Installer
image::images/environment-9.png[]

. Click in the close button to finish the installation:
+
.Microsoft .NET SDK Installer
image::images/environment-10.png[]

. To verify the installation, open a command prompt and enter the following command: 
+
[source, console]
----
dotnet --version
----
+
.CMD dotnet command
image::images/environment-11.png[]

==== OmniSharp extension
Download and install *C# extension (by OmniSharp)*:

. Open Visual Studio, go to the extensions section (1), search for C# extensions (2) and install the C# extension by OmniSharp:
+
.Extensions Site in Visual Code Studio
image::images/environment-12.png[]

=== For Linux Systems

This guide is intended for Ubuntu/Debian distributions; if you are using another Linux distribution, please refer to the https://code.visualstudio.com/docs/setup/linux[official Visual Code Studio documentation]

==== Visual Studio Code
Download and install *Visual Studio Code*:

. Download the latest version https://code.visualstudio.com/download[here]
+
.Download Page
image::images/environment-15.png[]

. To install, open a terminal within the Downloads folder (or the location where the binary was downloaded) and run the following command:
+
[source, bash]
----
sudo apt install ./<file>.deb

# If you're on an older Linux distribution, you will need to run this instead:
# sudo dpkg -i <file>.deb
# sudo apt-get install -f # Install dependencies
----
+
Where `<file>` is the name of the binary that was downloaded in step 1. 
+
.Terminal command example
image::images/environment-16.png[]

. Then update the package cache and install the package using:
+
[source, bash]
----
sudo apt install apt-transport-https
sudo apt update
sudo apt install code # or code-insiders
----

==== .Net Core SDK

Download and install *.Net Core SDK*:

. To install, open a terminal and run the following command:
+
[source, bash]
----
sudo apt-get update; \
sudo apt-get install -y apt-transport-https && \
sudo apt-get update && \
sudo apt-get install -y dotnet-sdk-6.0
----
+
WARNING: If you receive an error message similar to Unable to locate package dotnet-sdk-6.0, see the https://docs.microsoft.com/en-us/dotnet/core/install/linux-ubuntu#apt-troubleshooting[APT troubleshooting section] of the official documentation.

. To verify the installation, open a terminal and enter the following command: 
+
[source, console]
----
dotnet --version
----
+
.CMD dotnet command
image::images/environment-17.png[]

NOTE: This guide is intended for Ubuntu/Debian distributions; if you are using another Linux distribution, please refer to the https://docs.microsoft.com/en-us/dotnet/core/install/[Official Microsoft Documentation]

==== OmniSharp extension
Download and install *C# extension (by OmniSharp)*:

. Open Visual Studio, go to the extensions section (1), search for C# extensions (2) and install the C# extension by OmniSharp:
+
.Extensions Site in Visual Code Studio
image::images/environment-12.png[]

=== For MacOS

==== Visual Studio Code

Download and install *Visual Studio Code*:

. Download the latest version https://code.visualstudio.com/download[here]
+
.Download Page
image::images/environment-18.png[]

. Allow the download for this website by clicking the Allow button: 
+
.Download Page
image::images/environment-19.png[]

. Go to the Downloads folder and Drag `Visual Studio Code.app` to the Applications folder, making it available in the macOS Launchpad:
+
.MacOS Launchpad
image::images/environment-21.png[]

. Launch Visual Studio Code:
+
When you initially start Visual Studio Code, you must authorize the program to launch by clicking the open button. 
+
.Opening VSCode
image::images/environment-20.png[]
+
TIP: Add VS Code to your Dock by right-clicking on the icon, located in the Dock, to bring up the context menu and choosing Options, Keep in Dock

==== .Net Core SDK

. Download https://dotnet.microsoft.com/en-us/download[.Net 6.0 SDK] for your cpu architecture (x64 or Arm64).
+
.Download Page .Net 6.0
image::images/environment-22.png[]

. Allow the download clicking the allow button in the next window:
+
.Download Page .Net 6.0
image::images/environment-23.png[]

. Go to the downloads folder, open the downloaded installer, and click on the continue button:
+
.Microsoft .NET SDK Installer
image::images/environment-24.png[]

. Select the destination disk where you want to install the Microsoft .NET SDK, and click continue:
+
.Microsoft .NET SDK Installer
image::images/environment-25.png[]

. Click on the install button to perform a standard installation:
+
.Microsoft .NET SDK Installer
image::images/environment-26.png[]

. Type your credentials and click the Install Software button to begin the installation: 
+
.Microsoft .NET SDK Installer
image::images/environment-27.png[]

. To verify the installation, open a terminal and enter the following command: 
+
[source, console]
----
dotnet --version
----
+
.CMD terminal command
image::images/environment-28.png[]

==== OmniSharp extension

Download and install *C# extension (by OmniSharp)*:

. Open Visual Studio, go to the extensions section (1), search for C# extensions (2) and install the C# extension by OmniSharp:
+
.Extensions Site in Visual Code Studio
image::images/environment-12.png[]

== Devon4net.Web.Api.Template

=== For Windows

. Open a project:
*    Open Visual Studio Code.
*   Click on the Explorer icon on the left menu and then click **Open Folder**.

*   Select the folder you want your C# project to be in and click **Select Folder**. For our example, we'll create a folder for our project named `'ApiTest'`.

. Initialize a C# project:
*   Open the Integrated Terminal from Visual Studio Code by typing `Left CTRL + backtick`. Alternatively, you can select **View** > **Terminal** from the main menu.
* You must select Command Prompt instead of PowerShell:
+
.CMD in Visual Code Studio
image::images/environment-13.png[]

*   In the terminal window, type:
+
[source, console]
----
dotnet new -i Devon4Net.WebAPI.Template
----

*   This will install the Devon4Net.WebAPI.Template with the latest version, next to create your project you must run the following command.
+
[source, console]
----
dotnet new Devon4NetAPI
----

. Run the "ApiTest" program:
* Go to the path where the Program.cs file is found typing the following command:
+
[source, console]
----
cd Templates\WebAPI\Devon4Net.Application.WebAPI
----
+
And then type:
+
[source, console]
----
dotnet run
----

* You can now test the template by going to the swagger page at: https://localhost:8085/swagger/index.html. 

You may now start working with C# and the devon4net api template in the Visual Studio Code environment.

=== For Linux Systems

. Open a project:
*    Open Visual Studio Code.
*   Click on the Explorer icon on the left menu and then click **Open Folder**.

*   Select the folder you want your C# project to be in and click **Select Folder**. For our example, we'll create a folder for our project named `'ApiTest'`.

. Initialize a C# project:
*   Open the Integrated Terminal from Visual Studio Code by typing `Left CTRL + backtick`. Alternatively, you can select **View** > **Terminal** from the main menu.

*   In the terminal window, type:
+
[source, console]
----
dotnet new -i Devon4Net.WebAPI.Template
----

*   This will install the Devon4Net.WebAPI.Template with the latest version, next to create your project you must run the following command.
+
[source, console]
----
dotnet new Devon4NetAPI
----

. Run the "ApiTest" program:
* Go to the path where the Program.cs file is found typing the following command:
+
[source, console]
----
cd Templates/WebAPI/Devon4Net.Application.WebAPI
----
+
And then type:
+
[source, console]
----
dotnet run
----

* You can now test the template by going to the swagger page at: https://localhost:8085/swagger/index.html. 

You may now start working with C# and the devon4net api template in the Visual Studio Code environment.

=== For MacOS

. Open a project:
*    Open Visual Studio Code.
*   Click on the Explorer icon on the left menu and then click **Open Folder**.

*   Select the folder you want your C# project to be in and click **Select Folder**. For our example, we'll create a folder for our project named `'ApiTest'`.

. Initialize a C# project:
*   Open the Integrated Terminal from Visual Studio Code by typing `Left CTRL+ Left Shift + backtick`. Alternatively, you can select **View** > **Terminal** from the main menu.

*   In the terminal window, type:
+
[source, console]
----
dotnet new -i Devon4Net.WebAPI.Template
----

*   This will install the Devon4Net.WebAPI.Template with the latest version, next to create your project you must run the following command.
+
[source, console]
----
dotnet new Devon4NetAPI
----

. Run the "ApiTest" program:
* Go to the path where the Program.cs file is found typing the following command:
+
[source, console]
----
cd Templates/WebAPI/Devon4Net.Application.WebAPI
----
+
And then type:
+
[source, console]
----
dotnet run
----

* You can now test the template by going to the swagger page at: https://localhost:8085/swagger/index.html. 

You may now start working with C# and the devon4net api template in the Visual Studio Code environment.

==== Troubleshoot

It's possible that when you execute the program, you'll get the following error:

image::images/Exception-DevonWebAPI-MacEnvironment.png[]

That is why Kestrel does not support HTTP/2 with TLS in macOS.
To fix this, navigate to the `appsettings.json` file and disable the TLS protocol in the Kestrel server setup as follows:

[source, json]
----
{
  "devonfw": {
    "Kestrel": {
      "UseHttps": true,
      "HttpProtocol": "Http1AndHttp2", //Http1, Http2, Http1AndHttp2, none
      "ApplicationPort": 8085,
      "SslProtocol": "none", //Tls12, Tls13, none. For Https2 Tls12 is needed
    }
  }
}
----      

WARNING: HTTP/2 without TLS should only be used during app development. Production apps should always use transport security. 

== Debug

. Open for example Program.cs by clicking on it. The first time you open a C# file in Visual Studio Code, OmniSharp will load in the editor.

. To open the Debug view, click on the Debugging icon on the left side menu.

. Visual Studio Code will prompt you to add the missing assets to build and debug your app. Select Yes.

. Locate the green arrow at the top of the pane. Make sure the drop-down next to it has `.NET Core Launch (web)` selected.

. Add a breakpoint to your project by clicking on the **editor margin** (the space on the left of the line numbers in the editor).

. Select F5 or the green arrow to start debugging. The debugger stops execution of your program when it reaches the breakpoint you set in the previous step.

*   While debugging you can view your local variables in the top left pane or use the debug console.

. Select the green arrow at the top to continue debugging, or select the red square at the top to stop.

The following figure summarizes the most important points: 

.Debug mode in Visual Code Studio
image::images/environment-14.png[]

Where:

. Debug Section
. Launch button
. Break Point
. Debug Console
. Debug Navigation Buttons

[NOTE]
====
For more information and troubleshooting tips on .NET Core debugging with OmniSharp in Visual Studio Code, see https://github.com/OmniSharp/omnisharp-vscode/blob/master/debugger.md[Instructions for setting up the .NET Core debugger].
====

== External links

https://www.microsoft.com/net/core[.Net Core]

https://code.visualstudio.com/docs/other/dotnet[Using .NET Core in Visual Studio Code]

https://docs.microsoft.com/dotnet/core/tutorials/with-visual-studio-code[.Net Core in Visual Studio Code tutorial]