Tutorial 01 02 Creating a Demo Service

Creating a Demo Solution

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. It does not walk you through the detailed process of creating the service from scratch, but if you want to get a service up and running fast, this is the tutorial for you. If you prefer to go through the process of building up a service step-by-step, you should follow the Building a Service From Scratch tutorial instead.

In this tutorial, we'll use the harmonydemo template, which is a quick way to create a fully configured and working Harmony Core development environment. This is a great way to become familiar with how Harmony Core works, and you can use the resulting solution as the starting point for your own Harmony Core development. To do this, you would 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.

Creating the New Solution

In the following steps, you’ll create a solution from the harmonydemo template, which provides everything you need (projects, references, sample code, 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.
Use the following dotnet command to make sure the Harmony Core templates (including harmonydemo) are installed on your machine and that you have the latest version of these templates:
```
dotnet new install 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 the dotnet new command:
```
dotnet new harmonydemo [-o <folderName>] [-n <solutionName>]
```
The -o <folderName> option enables 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 C:\hc\tut1\MyApi\MyApi.sln...
C:\hc\tut1\MyApi\TraditionalBridge\TraditionalBridge.synproj : warning NU1503: Skipping restore for project 'C:\hc\tut1
\MyApi\TraditionalBridge\TraditionalBridge.synproj'. The project file may be invalid or missing targets required for re
store. [C:\hc\tut1\MyApi\MyApi.sln]
  Determining projects to restore...
  Restored C:\hc\tut1\MyApi\Services.Isolated\Services.Isolated.synproj (in 735 ms).
  Restored C:\hc\tut1\MyApi\Services.Host\Services.Host.synproj (in 735 ms).
  Restored C:\hc\tut1\MyApi\Services.Controllers\Services.Controllers.synproj (in 735 ms).
  Restored C:\hc\tut1\MyApi\Services\Services.synproj (in 97 ms).
  Restored C:\hc\tut1\MyApi\Services.Models\Services.Models.synproj (in 10 ms).
Restore succeeded.
Running 'dotnet restore' on C:\hc\tut1\MyApi\Repository\Repository.synproj...
  Determining projects to restore...
  Nothing to do. None of the projects specified contain packages to restore.
Restore succeeded.
Running 'dotnet restore' on C:\hc\tut1\MyApi\Services\Services.synproj...
  Determining projects to restore...
  All projects are up-to-date for restore.
Restore succeeded.
Running 'dotnet restore' on C:\hc\tut1\MyApi\Services.Controllers\Services.Controllers.synproj...
  Determining projects to restore...
  All projects are up-to-date for restore.
Restore succeeded.
Running 'dotnet restore' on C:\hc\tut1\MyApi\Services.Host\Services.Host.synproj...
  Determining projects to restore...
  All projects are up-to-date for restore.
Restore succeeded.
Running 'dotnet restore' on C:\hc\tut1\MyApi\Services.Isolated\Services.Isolated.synproj...
  Determining projects to restore...
  All projects are up-to-date for restore.
Restore succeeded.
Running 'dotnet restore' on C:\hc\tut1\MyApi\Services.Models\Services.Models.synproj...
  Determining projects to restore...
  All projects are up-to-date for restore.
Restore succeeded.
Running 'dotnet restore' on C:\hc\tut1\MyApi\TraditionalBridge\TraditionalBridge.synproj...
Restore succeeded.

You may notice an NU1503 warning early in the output:

C:\hc\tut1\MyApi\TraditionalBridge\TraditionalBridge.synproj : warning NU1503: Skipping restore for project 'C:\hc\tut1
\MyApi\TraditionalBridge\TraditionalBridge.synproj'. The project file may be invalid or missing targets required for re
store. [C:\hc\tut1\MyApi\MyApi.sln]

The warning (NU1503) is produced because the new solution includes a Traditional Synergy ELB project. When a .NET Core solution is created, Microsoft's 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.

Building and Running the Web Service

Once you’ve created a solution from the harmonydemo template, you can use command-line tools to build the solution and run the resulting Harmony Core web service.

Open your new Harmony Core solution in Visual Studio 2022. For example, open Visual Studio, select File > Open > Project/Solution from the menu, and then in the Open Project/Solution window, select the .sln file for the new solution, and then click OK.
In Visual Studio, select Tools > Command Prompt (x64) to open a developer command prompt.
In the developer command prompt window, move to the solution folder (the folder with the .sln file) and set the SolutionDir environment variable to point to that location, ensuring that the specified path ends with a trailing backslash character:
```
cd ..
set SolutionDir=%CD%\
```
Now use msbuild to build the solution:
```
msbuild myapi.sln
```
As the project builds, you will see various messages, including some warnings, such as DBL-W-BIGIDEN warnings (due to a known issue). You can ignore these. The following sample output shows a couple of these warnings, but most have been removed and replaced by ellipses. However, somewhere near the center of the output, you should see a “Build succeeded” message, which indicates that your Harmony Core application is ready to run.

Next, move to the Services.Host directory, which contains the project that defines the self-hosting program for the Harmony Core service. From there, start the self-hosting program by using the dotnet run command:

cd Services.Host
dotnet run

As the self-hosting program starts, you should see output like 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.

Testing the Web Service

If you read the output from the hosting program, you will notice that it includes 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:

// 20221116154219
// https://localhost:8086/odata/v1/Customers(CustomerNumber=1)

{
  "@odata.context": "https://localhost:8086/odata/v1/$metadata#Customers/$entity",
  "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=="}

Stopping the Web Service Program

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

Provide feedback

Saved searches