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. 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.
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. It's 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'll 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, 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. A subfolder will be created in this location in a subsequent step, and files and folders for the new solution will be added to that subfolder.
-
Use the following 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 -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 like 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 C:\hc\tutorial1e\MyApi\.gitignore...
C:\hc\tutorial1e\MyApi\.gitignore(1,1): error MSB4025: The project file could not be loaded. Data at the root level is
invalid. Line 1, position 1.
Restore failed.
Running 'dotnet restore' on C:\hc\tutorial1e\MyApi\MyApi.sln...
C:\hc\tutorial1e\MyApi\TraditionalBridge\TraditionalBridge.synproj : warning NU1503: Skipping restore for project 'C:\h
c\tutorial1e\MyApi\TraditionalBridge\TraditionalBridge.synproj'. The project file may be invalid or missing targets req
uired for restore. [C:\hc\tutorial1e\MyApi\MyApi.sln]
Determining projects to restore...
Restored C:\hc\tutorial1e\MyApi\Services.Controllers\Services.Controllers.synproj (in 1.7 sec).
Restored C:\hc\tutorial1e\MyApi\Services.Models\Services.Models.synproj (in 1.7 sec).
Restored C:\hc\tutorial1e\MyApi\Services\Services.synproj (in 1.7 sec).
Restored C:\hc\tutorial1e\MyApi\Services.Isolated\Services.Isolated.synproj (in 19 ms).
Restored C:\hc\tutorial1e\MyApi\Services.Host\Services.Host.synproj (in 1.8 sec).
Restore succeeded.
Running 'dotnet restore' on C:\hc\tutorial1e\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\tutorial1e\MyApi\Services\Services.synproj...
Determining projects to restore...
All projects are up-to-date for restore.
Restore succeeded.
Running 'dotnet restore' on C:\hc\tutorial1e\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\tutorial1e\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\tutorial1e\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\tutorial1e\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\tutorial1e\MyApi\TraditionalBridge\TraditionalBridge.synproj...
Restore succeeded.
Post action failed.
Manual instructions: Run 'dotnet restore'
You may notice a MSB4025 error and an NU1503 warning early in the output:
C:\hc\tutorial1e\MyApi\.gitignore(1,1): error MSB4025: The project file could not be loaded. Data at the root level is
invalid. Line 1, position 1.
Restore failed.
Running 'dotnet restore' on C:\hc\tutorial1e\MyApi\MyApi.sln...
C:\hc\tutorial1e\MyApi\TraditionalBridge\TraditionalBridge.synproj : warning NU1503: Skipping restore for project 'C:\h
c\tutorial1e\MyApi\TraditionalBridge\TraditionalBridge.synproj'. The project file may be invalid or missing targets req
uired for restore. [C:\hc\tutorial1e\MyApi\MyApi.sln]
The error (MSB4025) is a known issue, and 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.
Once you’ve created a solution from the harmonydemo template, you can use .NET Core command-line tools (included in the .NET 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:
cd Services.Host dotnet build
As the project builds, you will see various messages, including quite a few DBL-W-BIGIDEN warnings, which are 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.
C:\hc\tutorial1e\MyApi\Services.Host>dotnet build
MSBuild version 17.3.2+561848881 for .NET
Determining projects to restore...
All projects are up-to-date for restore.
Determining projects to restore...
All projects are up-to-date for restore.
Repository ->
C:\hc\tutorial1e\MyApi\Repository\rpsmain.ism;
C:\hc\tutorial1e\MyApi\Repository\rpsmain.is1;
C:\hc\tutorial1e\MyApi\Repository\rpstext.ism;
C:\hc\tutorial1e\MyApi\Repository\rpstext.is1
Determining projects to restore...
Determining projects to restore...
Determining projects to restore...
Determining projects to restore...
All projects are up-to-date for restore.
All projects are up-to-date for restore.
All projects are up-to-date for restore.
All projects are up-to-date for restore.
C:\Users\DevAdm\.nuget\packages\synergex.synergyde.build\22.8.1287\build\Synergex.SynergyDE.Core.targets(279,5): dblnet
warning DBL-W-BIGIDEN: %DBL-W-BIGIDEN, Identifier too long: @Func<CompileAsyncQuery`1458587996-TContext,CompileAsyncQ
uery`1458587996-TParam1,CompileAsyncQuery`1458587996-TParam2,CompileAsyncQuery`1458587996-TParam3,CompileAsyncQuery`145
8587996-TParam4,CompileAsyncQuery`1458587996-TParam5,CompileAsyncQuery`1458587996-TParam6,CompileAsyncQuery`1458587996-
TParam7,CompileAsyncQuery`1458587996-TParam8,CompileAsyncQuery`1458587996-TParam9,CompileAsyncQuery`1458587996-TParam10
,CompileAsyncQuery`1458587996-TParam11,CompileAsyncQuery`1458587996-TParam12,IAsyncEnumerable<TResult>> : [C:\hc\tutor
ial1e\MyApi\Services.Models\Services.Models.synproj]
...
Services.Controllers -> C:\hc\tutorial1e\MyApi\Services.Controllers\bin\Debug\net6.0\Services.Controllers.dll
Services.Isolated -> C:\hc\tutorial1e\MyApi\Services.Isolated\bin\Debug\net6.0\Services.Isolated.dll
Services -> C:\hc\tutorial1e\MyApi\Services\bin\Debug\net6.0\Services.dll
Services.Host -> C:\hc\tutorial1e\MyApi\Services.Host\bin\Debug\net6.0\Services.Host.dll
Build succeeded.
C:\Users\DevAdm\.nuget\packages\synergex.synergyde.build\22.8.1287\build\Synergex.SynergyDE.Core.targets(279,5): dblnet
warning DBL-W-BIGIDEN: %DBL-W-BIGIDEN, Identifier too long: @Func<CompileAsyncQuery`1458587996-TContext,CompileAsyncQ
uery`1458587996-TParam1,CompileAsyncQuery`1458587996-TParam2,CompileAsyncQuery`1458587996-TParam3,CompileAsyncQuery`145
8587996-TParam4,CompileAsyncQuery`1458587996-TParam5,CompileAsyncQuery`1458587996-TParam6,CompileAsyncQuery`1458587996-
TParam7,CompileAsyncQuery`1458587996-TParam8,CompileAsyncQuery`1458587996-TParam9,CompileAsyncQuery`1458587996-TParam10
,CompileAsyncQuery`1458587996-TParam11,CompileAsyncQuery`1458587996-TParam12,IAsyncEnumerable<TResult>> : [C:\hc\tutor
ial1e\MyApi\Services.Models\Services.Models.synproj]
...
22 Warning(s)
0 Error(s)
Time Elapsed 00:00:56.39
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.
-
Start the self-hosting program by entering the following command:
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.
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