Tutorial 01 02 Creating a Demo Service
This tutorial uses a very fast "create it, build it, run it" approach that results in you producing a fully-built Harmony Core service in a matter of minutes, but it does not walk you through the detailed process of doing so. If you want to get a service up and running fast then this is the tutorial for you, but if you prefer to be walked through the process of building up a service, step-by-step, then you should follow the Creating a Basic Solution tutorial instead.
Using the harmonydemo template is a quick way to create a fully configured and working Harmony Core development environment, and is a great way for a new Harmony Core developer to become familiar with how Harmony Core works. You can also use the resulting solution as the starting point for your own Harmony Core development, as it is easy to remove the code that is generated for the Harmony Core sample environment and start generating code for your own data structures and business logic instead.
In the following steps, we’ll create a solution from the harmonydemo template, which provides everything you need (projects, references, sample code, and data, etc.) to get a simple web service up and running in a few easy steps.
To create a new solution:
-
Make sure the template is installed on your machine, and that you have the latest version available:
dotnet new -i Harmony.Core.ProjectTemplates -
Open a Windows command prompt and move to the location where you would like the solution to be created.
In the next step, a subfolder will be created in this location, and files and folders for the new solution will be added to that subfolder.
The command line dotnet tool is used to create new projects and solutions from pre-installed templates, using a command similar to this:
dotnet new harmonydemo [-o <folderName>] [-n <solutionName>]
The -o <folderName> option allows you to create a new subfolder for the solution, otherwise the solution will be created in the current folder.
By default, the name of the new solution will be based on the name of the containing folder, but you can specify the -n <solutionName> option to provide a custom name for the solution.
-
Create a new solution, like this:
dotnet new harmonydemo -o MyApi
You should see various messages scroll by as the solution is created. Here is an example of the output when creating a new solution in a sub-folder named MyApi:
The template "Harmony Core Demo Solution" was created successfully.
Processing post-creation actions...
Running 'dotnet restore' on MyApi\MyApi.sln...
D:\MyApi\TraditionalBridge\TraditionalBridge.synproj : warning NU1503: Skipping restore for project 'D:\MyApi\TraditionalBridge\TraditionalBridge.synproj'. The project file may be invalid or missing targets required for restore. [D:\MyApi\MyApi.sln]
Restore completed in 487.16 ms for D:\MyApi\Services.Isolated\Services.Isolated.synproj.
Restore completed in 487.08 ms for D:\MyApi\Services\Services.synproj.
Restore completed in 487.08 ms for D:\MyApi\Services.Host\Services.Host.synproj.
Restore completed in 487.13 ms for D:\MyApi\Services.Controllers\Services.Controllers.synproj.
Restore completed in 487.08 ms for D:\MyApi\Services.Models\Services.Models.synproj.
Restore succeeded.
Running 'dotnet restore' on MyApi\Repository/Repository.synproj...
Nothing to do. None of the projects specified contain packages to restore.
Restore succeeded.
Running 'dotnet restore' on MyApi\Services/Services.synproj...
Restore completed in 33.58 ms for D:\MyApi\Services.Models\Services.Models.synproj.
Restore completed in 33.61 ms for D:\MyApi\Services.Isolated\Services.Isolated.synproj.
Restore completed in 33.58 ms for D:\MyApi\Services.Controllers\Services.Controllers.synproj.
Restore completed in 33.68 ms for D:\MyApi\Services\Services.synproj.
Restore succeeded.
Running 'dotnet restore' on MyApi\Services.Controllers/Services.Controllers.synproj...
Restore completed in 32.91 ms for D:\MyApi\Services.Controllers\Services.Controllers.synproj.
Restore completed in 32.91 ms for D:\MyApi\Services.Models\Services.Models.synproj.
Restore succeeded.
Running 'dotnet restore' on MyApi\Services.Host/Services.Host.synproj...
Restore completed in 27.57 ms for D:\MyApi\Services\Services.synproj.
Restore completed in 28.28 ms for D:\MyApi\Services.Isolated\Services.Isolated.synproj.
Restore completed in 28.29 ms for D:\MyApi\Services.Controllers\Services.Controllers.synproj.
Restore completed in 27.58 ms for D:\MyApi\Services.Models\Services.Models.synproj.
Restore completed in 30.45 ms for D:\MyApi\Services.Host\Services.Host.synproj.
Restore succeeded.
Running 'dotnet restore' on MyApi\Services.Isolated/Services.Isolated.synproj...
Restore completed in 28.43 ms for D:\MyApi\Services.Models\Services.Models.synproj.
Restore completed in 28.65 ms for D:\MyApi\Services.Isolated\Services.Isolated.synproj.
Restore completed in 28.65 ms for D:\MyApi\Services.Controllers\Services.Controllers.synproj.
Restore succeeded.
Running 'dotnet restore' on MyApi\Services.Models/Services.Models.synproj...
Restore completed in 26.78 ms for D:\MyApi\Services.Models\Services.Models.synproj.
Restore succeeded.
Running 'dotnet restore' on MyApi\TraditionalBridge/TraditionalBridge.synproj...
Restore succeeded.
D:\>
You may notice an NU1503 warning early in the output:
Running 'dotnet restore' on MyApi\MyApi.sln...
D:\MyApi\TraditionalBridge\TraditionalBridge.synproj : warning NU1503: Skipping restore for project 'D:\MyApi\TraditionalBridge\TraditionalBridge.synproj'. The project file may be invalid or missing targets required for restore. [D:\MyApi\MyApi.sln]
This warning is produced because the new solution includes a Traditional Synergy ELB project. When a .NET Core solution is created, Microsofts tooling performs a NuGet package restore on each project in the solution to download and required dependencies. But doing a NuGet restore on a Traditional Synergy project isn't valid, hence the warning message, which can be ignored.
Once you’ve created a solution from the harmonydemo template, you can use .NET Core command-line tools (included in the .NET Core SDK) to build the solution and run the resulting Harmony Core web service.
To build and run the simple web service, open a command prompt, make sure you are in the same folder as the new solution that was just created, then set the environment variable SolutionDir to point to that location, ensuring that the path specified ends with a trailing backslash character:
-
Enter the following commands to switch into the solution folder and set the SolutionDir environment variable:
cd MyApi set SolutionDir = %CD%\ -
Next, move into the Services.Host directory, which contains the project that defines the self-hosting program. From here you can build the solution, like this:
cd Services.Host dotnet build
As the project builds, you will see various messages, like this:
D:\MyApi\Services.Host> dotnet build
Microsoft (R) Build Engine version 16.5.0+d4cbfca49 for .NET Core
Copyright (C) Microsoft Corporation. All rights reserved.
Restore completed in 29.4 ms for D:\MyApi\Services.Models\Services.Models.synproj.
Restore completed in 29.36 ms for D:\MyApi\Services\Services.synproj.
Restore completed in 29.36 ms for D:\MyApi\Services.Isolated\Services.Isolated.synproj.
Restore completed in 29.34 ms for D:\MyApi\Services.Controllers\Services.Controllers.synproj.
Restore completed in 31.99 ms for D:\MyApi\Services.Host\Services.Host.synproj.
Restore completed in 28.51 ms for D:\MyApi\Services.Isolated\Services.Isolated.synproj.
Restore completed in 28.46 ms for D:\MyApi\Services.Controllers\Services.Controllers.synproj.
Restore completed in 28.46 ms for D:\MyApi\Services.Models\Services.Models.synproj.
Restore completed in 29.08 ms for D:\MyApi\Services.Host\Services.Host.synproj.
Restore completed in 28.49 ms for D:\MyApi\Services\Services.synproj.
Repository ->
Restore completed in 5.79 ms for D:\MyApi\Services.Controllers\Services.Controllers.synproj.
Restore completed in 5.79 ms for D:\MyApi\Services.Models\Services.Models.synproj.
Restore completed in 35.05 ms for D:\MyApi\Services\Services.synproj.
Restore completed in 34.68 ms for D:\MyApi\Services.Controllers\Services.Controllers.synproj.
Restore completed in 34.71 ms for D:\MyApi\Services.Models\Services.Models.synproj.
Restore completed in 35.94 ms for D:\MyApi\Services.Isolated\Services.Isolated.synproj.
Restore completed in 31.8 ms for D:\MyApi\Services.Models\Services.Models.synproj.
Restore completed in 31.15 ms for D:\MyApi\Services.Isolated\Services.Isolated.synproj.
Restore completed in 31.16 ms for D:\MyApi\Services.Models\Services.Models.synproj.
Restore completed in 31.15 ms for D:\MyApi\Services.Controllers\Services.Controllers.synproj.
Services.Models -> D:\MyApi\Services.Models\bin\Debug\netcoreapp3.1\Services.Models.dll
Services.Controllers -> D:\MyApi\Services.Controllers\bin\Debug\netcoreapp3.1\Services.Controllers.dll
Services.Isolated -> D:\MyApi\Services.Isolated\bin\Debug\netcoreapp3.1\Services.Isolated.dll
Services -> D:\MyApi\Services\bin\Debug\netcoreapp3.1\Services.dll
Services.Host -> D:\MyApi\Services.Host\bin\Debug\netcoreapp3.1\Services.Host.dll
Build succeeded.
0 Warning(s)
0 Error(s)
Time Elapsed 00:00:19.16
D:\MyApi\Services.Host>
If you see a “Build succeeded” message near to the end of the output, your Harmony Core application is ready to run.
-
Start the self-hosting program by entering the following command:
dotnet run
As the self-hosting program starts you should see output similar to this:
API documentation is available at https://localhost:8086/api-docs
Hosting environment: Development
Content root path: D:\MyApi\Services.Host\bin\Debug\netcoreapp3.1\
Now listening on: http://localhost:8085
Now listening on: https://localhost:8086
Application started. Press Ctrl+C to shut down.
If you read the output from the hosting program you will notice that part of the information is the URL that your web service is listening at. By default this will be:
https://localhost:8086
- Open a web browser and navigate to that URL
You should see the default home page for the Harmony Core demo service. This is simply a static HTML page that contains various links to various things exposed by the service:
-
Try out some of the links on the page. For example, if you click on the Single customer link you should see a response that looks something like this:
// 20191212142744 // https://localhost:8086/odata/v1/Customers(1) { "@odata.context": "https://localhost:8086/odata/v1/$metadata#Customers/$entity", "@odata.etag": "W/\"YmluYXJ5J0FDQUFBQUFBNHhsU3FRPT0n\"", "CustomerNumber": 1, "Name": "San Pablo Nursery", "Street": "1324 San Pablo Dam Road", "City": "San Pablo", "State": "CA", "ZipCode": 94806, "Contact": "Karen Graham", "Phone": "(555) 912-2341", "Fax": "(555) 912-2342", "FavoriteItem": 13, "PaymentTermsCode": "01", "TaxId": 559244251, "CreditLimit": 2000.00, "GlobalRFA": "ACAAAAAA4xlSqQ==" }
This confirms that the web service is working.
If the data looks more like this:
{"@odata.context":"https://localhost:8086/odata/v1/$metadata#Customers/$entity","@odata.etag":"W/\"YmluYXJ5J0
FDQUFBQUFBNHhsU3FRPT0n\"","CustomerNumber":1,"Name":"San Pablo Nursery","Street":"1324 San Pablo Dam Road","Cit
y":"San Pablo","State":"CA","ZipCode":94806,"Contact":"Karen Graham","Phone":"(555) 912-2341","Fax":"(555) 912-2342","FavoriteItem":13,"PaymentTermsCode":"01","TaxId":559244251,"CreditLimit":2000.00,"GlobalRFA":"ACAAAAAA4x
lSqQ=="}
Then you don't have a JSON-formatting browser plug-in installed. Not to worry, that's what the data actually looks like!
- When you are finished testing, close your browser and stop the server application by switching focus to the command prompt window and pressing Ctrl + C.
Next topic: Development Environment Tour