Tutorial 01 02 Creating a Demo Service
This tutorial uses a very fast "create it, build it, run it" approach that results in a fully-built Harmony Core service in a matter of minutes, but it does not walk you through the detailed process of creating the service from scratch. If you want to get a service up and running fast, this is the tutorial for you. But if you prefer to be walked through the process of building up a service, step-by-step, you should follow the Building a Service From Scratch tutorial instead.
Using the harmonydemo template is a quick way to create a fully configured and working Harmony Core development environment, and it's a great way 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. It is easy to remove the code that is generated for the Harmony Core sample environment and then 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,
-
Open a Windows command prompt and move to the location where you would like the solution to be created. In a subsequent step, a subfolder will be created in this location, and files and folders for the new solution will be added to that subfolder.
-
Make sure the template is installed on your machine, and that you have the latest version available:
dotnet new -i Harmony.Core.ProjectTemplates
If the Harmony Core project templates are not already installed on your machine, you should see a series of messages starting with Restore completed in....
The command line dotnet tool can also be used to create new projects and solutions from pre-installed templates by 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. Without it, 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 use 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 required dependencies. But NuGet restore isn't valid for a Traditional Synergy project, hence the warning message, which you can ignore.
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, 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 for the Harmony Core service. From there you can build the solution, like this:
cd Services.Host dotnet build
As the project builds, you will see various messages, like these:
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
Near to the end of the output, you should see a “Build succeeded” message, which indicates 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 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 the following, you don't have a JSON-formatting browser plug-in installed. Not to worry, that's what the data actually looks like!
{"@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=="}
- 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