|
|
## About this guide
|
|
|
|
|
|
In this guide, you will learn how to run the example Hello SiLA server in the repo. The application is a .NET Core server application. The application does not interact with any underlying physical instrument, but rather simulates. The goal of this tutorial is to solidify the concepts of SiLA 2 and understand what is required to implement a SiLA 2 server.
|
|
|
|
|
|
At the end of this guide, you should be capable of running the server and interact with its exposed features via the [SiLA 2 Browser](https://sila2.gitlab.io/sila_base/docs/sila-browser-quickstart#run-the-sila-2-browser).
|
|
|
|
|
|
There are currently two C# implementations of the SiLA 2 specification:
|
|
|
1. [sila_csharp](https://gitlab.com/SiLA2/sila_csharp): community developed a reference implementation
|
|
|
- Useful if you would like to be able to create features first, and then from features implement servers.
|
|
|
2. [sila_tecan](https://gitlab.com/SiLA2/vendors/sila_tecan): A fork of sila_csharp with a different developer philosophy proudly brought to you by [Tecan](https://www.tecan.com/)
|
|
|
- It gives you the possibility to build your instrument interfaces first and then automatically generate the class interfaces for your instrument/device.
|
|
|
|
|
|
## Pre-requisites
|
|
|
To follow the steps in this tutorial, you will need the following:
|
|
|
|
|
|
* Access to a terminal window and some familiarity with the command line it provides (e.g. cmd.exe, PowerShell, Bash, zsh)
|
|
|
* .NET Core SDK 2.0 or greater (Linux only supports .NET Core 2.0 or .NET Core 3.0 Preview)
|
|
|
* .NET Framework 4.7.2 SDK
|
|
|
* Git and Git LFS
|
|
|
|
|
|
### Windows Installation Instructions
|
|
|
|
|
|
**Warning**: Do not use .net Core v2.1 on Linux, there is a known problem with port reusability that cause problem with the mDNS discovery. Please use version 2.0. This problem will be fixed in version 3.0 on Linux.
|
|
|
|
|
|
The following set of installation instructions require [Chocolatey](https://chocolatey.org/) to be installed. As this will facilitate the installation process. If you cannot install using `choco` then please install the tools in the steps manually.
|
|
|
|
|
|
**Install .NET Core**
|
|
|
```cmd
|
|
|
choco install dotnetcore-sdk
|
|
|
```
|
|
|
|
|
|
**Install Git**
|
|
|
```cmd
|
|
|
choco install git
|
|
|
git lfs install
|
|
|
```
|
|
|
|
|
|
On Microsoft Windows the sample applications can also be built and run using Visual Studio. This requires Visual Studio 2017 (Version 15.3 or higher). There are also free editions of Visual Studio like Express or Community Edition.
|
|
|
|
|
|
### Verify your pre-requisites
|
|
|
|
|
|
1. Open a terminal window on your system
|
|
|
|
|
|
2. Verify that you have install dotnet core by executing `dotnet --version`
|
|
|
![image](uploads/507fc0298ef410858b48ddaac5a90880/image.png)
|
|
|
|
|
|
If dotnet core is installed then `dotnet --version` should return the version of dotnet core SDK installed.
|
|
|
|
|
|
4. Verify Git is installed by execution `git --version`
|
|
|
|
|
|
5. Verify Git LFS is installed
|
|
|
|
|
|
## Clone the sila_csharp repository
|
|
|
|
|
|
In this section, we will clone the SiLA C# code repository to your workstation.
|
|
|
|
|
|
1. In your browser (Chrome recommended), open [the sila_csharp code repository](https://gitlab.com/SiLA2/sila_csharp)
|
|
|
|
|
|
2. In your terminal **clone the repository** onto your system
|
|
|
|
|
|
```bash
|
|
|
git clone https://gitlab.com/SiLA2/sila_csharp.git
|
|
|
```
|
|
|
|
|
|
![image](uploads/6f30653a3ed2d17d78ec0e6e25ea22d7/image.png)
|
|
|
|
|
|
|
|
|
3. In your terminal change the directory into the top of the sila_csharp directory by entering:
|
|
|
|
|
|
```bash
|
|
|
cd sila_csharp
|
|
|
```
|
|
|
|
|
|
4. In your terminal **initialize the submodules** by entering:
|
|
|
|
|
|
```bash
|
|
|
git submodule update --init --recursive
|
|
|
```
|
|
|
|
|
|
![image](uploads/f229f4c49184f63b0cc536bcae01acbe/image.png)
|
|
|
|
|
|
5. Take a minute to review the files and subdirectories in the `sila_csharp` project
|
|
|
|
|
|
Use the `ls` command (or `dir` in cmd) to list the contents
|
|
|
|
|
|
| Name | Description |
|
|
|
| ------ | ------ |
|
|
|
| examples | Example SiLA 2 server implementations which showcase SiLA 2 features|
|
|
|
| servers | Actual SiLA 2 server implementations which interact with physical instruments |
|
|
|
| src | SiLA 2 C# library reference implementation |
|
|
|
| README.md | Contains a reference on how to get started with building, running and developing the SiLA library |
|
|
|
| sila_base | The base resources common between reference implementation derived from SiLA Part A |
|
|
|
| docs | Additional documentation on how to develop the |
|
|
|
| tools | Tools for developing SiLA2 servers |
|
|
|
|
|
|
|
|
|
## Build the project
|
|
|
|
|
|
Now that you have successfully cloned the `sila_csharp` repository. You can run some of the example servers. Before you can run the example servers you must build the solution with Dotnet CLI to install all the dependent packages.
|
|
|
|
|
|
1. Make sure you are in the root directory of the project
|
|
|
|
|
|
```bash
|
|
|
cd sila_csharp
|
|
|
```
|
|
|
|
|
|
2. In the terminal enter `dotnet build` to kick-off the build
|
|
|
|
|
|
If no errors pop up when you are all good to continue! Otherwise, contact a maintainer!
|
|
|
|
|
|
## Start the Hello SiLA Server
|
|
|
|
|
|
1. Start the Hello SiLA Server by entering:
|
|
|
|
|
|
```bash
|
|
|
cd examples/HelloSila/HelloSila.ServerApp/bin/Debug/netcoreapp2.0
|
|
|
dotnet HelloSila.ServerApp.dll -c config.json
|
|
|
```
|
|
|
|
|
|
Alternatively you can also start from the project root folder (with implicit build)
|
|
|
|
|
|
```
|
|
|
cd examples/HelloSila/HelloSila.ServerApp
|
|
|
dotnet run -- -c config.json
|
|
|
```
|
|
|
|
|
|
![image](uploads/eb314a6ffebf9142a2fe7923a6614308/image.png)
|
|
|
|
|
|
The `dotnet` program will start the application and run the server with *discovery disabled* with a warning as such:
|
|
|
|
|
|
```bash
|
|
|
...
|
|
|
11:30:10 | Warn | SiLA2Server..ctor | Server is running without Discovery!
|
|
|
...
|
|
|
```
|
|
|
|
|
|
2. Start the SiLA 2 Browser by following the [steps here](https://sila2.gitlab.io/sila_base/docs/sila-browser-quickstart#install-and-run-the-sila-2-browser)
|
|
|
|
|
|
3. Manually add the SiLA Server to the browser by following [this video](https://drive.google.com/open?id=17incBNB54ggdyjlpgYL7lT-jO45lr47b)
|
|
|
|
|
|
NOTE: SiLA 2 servers runs by default on port 50052.
|
|
|
|
|
|
4. Shut down the server
|
|
|
|
|
|
5. Re-enable the server with discovery enabled
|
|
|
|
|
|
|
|
|
## Start the Hello SiLA Sever with Discovery enabled
|
|
|
|
|
|
Now that you have been able to run the server and interact with it via the SiLA Browser by manually adding the server. It is now time to test out a very powerful feature of SiLA 2, SiLA Discovery.
|
|
|
|
|
|
1. [Identify the network interface](#finding-network-interface) to use. For example, let's assume the found network interface is called `wlp1s0`
|
|
|
|
|
|
2. Start the Hello SiLA Server specifying the network interface to connect to by entering:
|
|
|
|
|
|
```bash
|
|
|
cd examples/HelloSila/HelloSila.ServerApp/bin/Debug/netcoreapp2.0
|
|
|
dotnet HelloSila.ServerApp.dll -c config.json -n wlp1s0
|
|
|
```
|
|
|
|
|
|
or respectively:
|
|
|
|
|
|
```bash
|
|
|
cd examples/HelloSila.ServerApp
|
|
|
dotnet run -- -c config.json -n wlp1s0
|
|
|
```
|
|
|
|
|
|
![image](uploads/6545e2359b62102d57b5cc69511326a5/image.png)
|
|
|
|
|
|
3. Start the SiLA 2 Browser by following the [steps here](https://sila2.gitlab.io/sila_base/docs/sila-browser-quickstart#run-the-sila-2-browser)
|
|
|
|
|
|
4. you should be able to `Scan the network` and discover your Server on the browser
|
|
|
|
|
|
## Finding Network Interface on Windows-based OS's
|
|
|
|
|
|
Finding the network interface on a windows machine is not as simple as on *nix based systems. There is no off the shelf tool which lists the correct interface names. Therefore we will run the example servers such that they list the available interfaces.
|
|
|
|
|
|
1. Identify the IP range of the network (which your the machine is connected to) you would like to expose the SiLA 2 server.
|
|
|
|
|
|
2. Then list all the available network interfaces on your machine using the Test Server
|
|
|
|
|
|
```bash
|
|
|
dotnet HelloSila.ServerApp.dll -l
|
|
|
```
|
|
|
|
|
|
or respectively:
|
|
|
|
|
|
```bash
|
|
|
dotnet run -- -l
|
|
|
```
|
|
|
|
|
|
You should see some output that looks like:
|
|
|
|
|
|
```txt
|
|
|
Available Network Interfaces:
|
|
|
lo
|
|
|
lo
|
|
|
Loopback
|
|
|
000000000000
|
|
|
Unknown
|
|
|
127.0.0.1 , ::1 ,
|
|
|
enp2s0f1
|
|
|
enp2s0f1
|
|
|
Ethernet
|
|
|
80FA5B5216D9
|
|
|
Down
|
|
|
|
|
|
wlp1s0
|
|
|
wlp1s0
|
|
|
Ethernet
|
|
|
CC2F71AEB267
|
|
|
Up
|
|
|
10.6.16.181 , fe80::d259:1a4f:37ad:4140%3 ,
|
|
|
docker0
|
|
|
docker0
|
|
|
Ethernet
|
|
|
0242A5906EFB
|
|
|
Down
|
|
|
172.17.0.1 ,
|
|
|
|
|
|
```
|
|
|
|
|
|
4. Select the interface name which has an IP assigned within the desired range.
|
|
|
|
|
|
For the example above, it is `wlp1s0` which is the network interface of interest. |
|
|
## Prerequisites
|
|
|
* Linux / macOS
|
|
|
* You´ll need the .NET 6 SDK >> https://dotnet.microsoft.com/download/dotnet/6.0
|
|
|
* It´s not necessary to build applications with a GUI but if you do so an IDE like Visual Studio Code ( >> https://code.visualstudio.com/ ) would be convenient
|
|
|
* Windows
|
|
|
* Download free IDE Visual Studio 2022 Community ( >> https://visualstudio.microsoft.com/de/vs/community/ ), use commercial Visual Studio 2022 Version or Visual Studio Code as well
|
|
|
* .NET 6 SDK is included in Visual Studio 2022...if you want to use Visual Studio Code or other IDEs you´ll have to download it on your own (see link above)
|
|
|
|
|
|
## Getting Started
|
|
|
* Clone Repo
|
|
|
* Please be sure fetching sila_base submodule by
|
|
|
* checking out the Repository with git-submodules recursively
|
|
|
* git clone --recurse-submodules https://gitlab.com/SiLA2/sila_csharp.git
|
|
|
* or check out the Repository and run following commands
|
|
|
* git submodule init
|
|
|
* git submodule update
|
|
|
* Run gRPC-Server
|
|
|
* SiLA2.gRPC.Temperature.Server.Basic.App
|
|
|
or
|
|
|
* SiLA2.gRPC.Temperature.Server.App (containing optional WebFrontend- and DatabaseModule)
|
|
|
* After having started the SilaServer process you can also follow Link https://<server-hostname-or-server-ip>:13742 (in Debug-Mode https://localhost:5001) to open a SilaServer-WebFrontend
|
|
|
* In the SilaServer-WebFrontend you´ll find NavigationLink "User Management"-View to use SilaServer-Database. There´s also an example of how Server-Push-Feature can be used...just click on NavigationLink "Temperature" and hit button "Change Temperature"...
|
|
|
* Run SiLA2.Temperature.Service.Client.App connecting automatically to SilaServer
|
|
|
|
|
|
## Build your own Project based on official Nuget-Packages
|
|
|
* Created ASP.NET Core Application as SiLA2.Server Project
|
|
|
* Search for & reference SiLA2.* packages found at Nuget.org in Visual Studio or https://www.nuget.org/ ...use at least SiLA2.Core...
|
|
|
* Create *.sila.xml-Feature-File and include it like it was done in Example Project SiLA2.Referencing.Nuget.Features.csproj
|
|
|
* Implement the features you´ve defined in your *.sila.xml-Feature-File in your Feature-Assembly
|
|
|
* Reference your Feature-Assenbly in your SiLA2.Server Project
|
|
|
* Add MSBuild Targets ProtoPreparation & ProtoGeneration in your FeatureAssembly.csproj (like it is done in any of the ExampleFeature.csproj files)
|
|
|
* Create SilA2-Clients communicating with the SiLA2.Server...in this case you might want to use Nuget-Package SiLA2.Client... |