Tutorial 01 03 Development Environment Tour
In the previous module of this tutorial, you used the harmonydemo solution template to create a new yet fully configured Harmony Core development solution, and you then compiled, executed, and tested the web services exposed by that solution.
In this module, you will explore the solution that was created in order to get an overall understanding of how a Harmony Core development environment is structured.
-
Start Visual Studio and open the solution that you created in the previous module. IF you followed the instructions closely, you are looking for a solution named
MyApi\MyApi.sln. -
If you can't already see the
Solution Explorerwindow, selectView > Solution Explorerfrom the menu.
In the Solution Explorer, you will find the following items. The items are discussed here in a logical order, not in the order that they appear within the IDE.
This is a Synergy repository project. You will find that the project contains the repository schema for the Harmony Core sample repository. When the project is built, the schema file is loaded into the repository ISAM files. Several of the other projects in the solution have a reference to the repository project, providing access to the underlying repository data.
The Services.Models project contains various classes that define and describe the entity (data) types that are exposed by your Harmony Core services.
Most of the code in the project is made up of model and metadata classes that represent the data entities being exposed, or provide additional internal information about those entities that is used by Harmony Core and the Synergy Entity Framework provider. Model classes primarily expose the fields of records as properties of a class, and instances of model classes are referred to as data objects.
You will also see a file named DbContext.dbl which contains a class that is an Entity Framework type that represents the overall "database" being used; it exposes members through which the underlying data can be accessed and manipulated.
The DbContext is declared as a “service” in the ASP.NET Web API environment, and instances of it are provided (via dependency injection) to the controller classes that make comprise the RESTful Web Services environment. This is all configured in the startup class, which you will see very soon.
If you examine the code in any of the web service controller classes, you will notice the DbContext being used to access the actual data at runtime.
The Services.Controllers project hosts the web service controller classes that in turn expose the individual endpoints of your web service. The controller classes are named after the entity types that they represent.
If you have ever worked in an ASP.NET MVC or ASP.NET Web API environment, you will already be familiar with the concept of controller classes, which are the place where the individual operations (the URL’s or “endpoints”) of a web application or service are implemented. The same is true here.
Each of the controller classes has a constructor that receives an instance of the DbContext object via dependency injection and stores the reference in a local instance variable for subsequent use by the various methods in the controller.
The endpoints that are exposed by methods in these controller classes are directly determined by various options that you can select in the regen.bat file before generating code.
The Services project contains the main configuiration and startup code for your Harmony Core service.
EdmBuilder.dbl
This is an “Enterprise Data Model Builder” class, an Entity Framework class that is responsible for describing the structure of the data being used within the Entity Framework environment. The code declares all of the entity types that are available within the environment.
Startup.dbl
This class is responsible for configuring the whole ASP.NET Core MVC, Web API and OData environments, as well as various other optional components. Amongst other things, the code in this file:
- Configures and loads various Harmony Core services
- Configures and loads OData services
- Configures and loads ASP.NET MVC
- Configures the use of HTTPS and redirects all HTTP traffic to an HTTPS endpoints
- Enables the use of the “developer mode” error pages
- Enables dependency injection
- Configures the default route for the service to be “/odata”
The term self-hosting refers to the fact that in .NET Core environments, web applications are typically hosted within a custom application that you also write. In most cases, this will be a simple console application. Even if you ultimately plan to host your services in a web server such as Internet Information Server (IIS), you will still need to generate a self-hosting application, and that application will in-turn be hosted and managed by IIS.
Of course, you are not expected to implement the functionality of a web server yourself. That functionality is provided by the ASP.NET Core environment in the form of a web server called Kestrel. You simply write an application that uses Kestrel to host an instance of your web site and/or services.
The Services.Host project contains such generated self-hosting code.
Harmony Core provides several mechanisms for isolating code if necessary, and the Services.Isolated project comes into play if some types of code isolation is required. It is not used by the current solution.
The TraditionalBridge project is a traditional Synergy console application project what is used to expose the traditional Synergy side of a Traditional Bridge implementation. The content of this project will be described in detail in the Implementing Traditional Bridge tutorial.
Remember that Harmony Core is a .NET Core application, and much of the functionality comes from various NuGet packages that are referenced by the various projects in the solution.
At the time of writing (Oct 2022) these are the NuGet packages that are used to build a Harmony Core service:
Harmony.Core
Harmony.Core.AspNetCore
Harmony.Core.EF
Harmony.Core.OData
IdentityModel
IdentityServer4.AccessTokenValidation
Microsoft.AspNetCore.Cors
Microsoft.AspNetCore.Http.Abstractions
Microsoft.AspNetCore.HttpsPolicy
Microsoft.AspNetCore.JsonPatch
Microsoft.AspNetCore.Mvc.NewtonsoftJson
Microsoft.EntityFrameworkCore
Microsoft.IdentityModel.Tokens
Microsoft.NET.Test.Sdk
Microsoft.VisualStudio.Threading
Nito.AsyncEx
SSH.NET
StreamJsonRpc
Swahsbuckle.AspNetCore
Synergex.SynergyDE.Build
Synergex.SynergyDE.synrnt
System.Linq.DynamicCore
System.Text.Encoding.CodePages
This batch file contains an example of how to publish a runtime instance of your Harmony Core web service to a folder named PUBLISH. Once published you could, for example, configure IIS to host the application.
To use this script, use the Tools menu to open a command prompt, cd to the main solution directory, then execute the batch file.
This batch file contains all of the settings and commands that are used to generate the source code for your Harmony Core web service, based on the repository structures that are listed in the DATA_STRUCTURES environment variable.
To use this script, use the Tools menu to open a command prompt, cd to the main solution directory, then execute the batch file.
This is a CodeGen user-defined tokens file; it contains values that are associated with several user-defined tokens that in turn are referenced in several of the CodeGen templates that are used to generate the code for your Harmony Core services.
This folder contains the main Harmony Core CodeGen templates that are used to generate data-centric OData services.
This folder contains CodeGen templates that are used to generate a SignalR hub for the methods in a Synergy Method Catalog interface. The use of this template is related to xfServerPlus Migration.
This folder contains CodeGen templates that are primarily used to generate code to expose the methods in a Synergy Method Catalog interface via Traditional Bridge. The use of this template is mainly related to xfServerPlus Migration.
There is one folder that is not shown by looking at the Visual Studio solution. This is the SampleData folder, which contains sample data that matches the metadata defined in the Harmony Core sample repository.
The sample data is shipped as sequential files (with a .txt file extension), and you will notice that XDL files are also present to describe the five main ISAM files that comprise the sample data. As currently configured, code in the self-hosting environment is used to create new instances of the data files each time the service starts, and delete those data files when the service terminates. This ensures that consistent data is exposed by the service, for testing purposes, each time the service starts.
Clearly that behavior would not be desirable in a production environment, and the behavior can be controlled via the selection of options in the regen.bat file.