Tutorial 01 03 Development Environment Tour
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.
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.
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.
Examine the EdmBuilder Class
Look in your Services project and select and open the source file EdmBuilder.dbl.
EdmBuilder stands for “Enterprise Data Model Builder” and is an Entity Framework class that is responsible for describing the structure of the data being used.
In this case you will see that the code declares all of the entity types that you have declared in your environment. For example, in the Harmony Core sample data set the code that declares the entities looks like this:
;;Declare entities
builder.EntitySet<Customer>("Customers")
builder.EntitySet<Item>("Items")
builder.EntitySet<Order>("Orders")
builder.EntitySet<OrderItem>("OrderItems")
builder.EntitySet<Vendor>("Vendors")
If your environment includes any structures that have segmented primary keys then you will also see a section of code that declares the individual properties that are involved with declaring these segmented keys:
builder.EntityType<OrderItem>().HasKey<OrderItem,int>("OrderNumber")
builder.EntityType<OrderItem>().HasKey<OrderItem,int>("ItemNumber")
You won't see any specific information relating to the properties associated with single segment primary keys, those are declared elsewhere using a different mechanism.
You may also notice is code that declares any alternate keys that are present within each entity type. For example:
data itemType = (@EdmEntityType)tempModel.FindDeclaredType("Services.Models.Item")
tempModel.AddAlternateKeyAnnotation(itemType, new Dictionary<string, IEdmProperty>() {{"VendorNumber",itemType.FindProperty("VendorNumber")}})
tempModel.AddAlternateKeyAnnotation(itemType, new Dictionary<string, IEdmProperty>() {{"FlowerColor",itemType.FindProperty("FlowerColor")}})
tempModel.AddAlternateKeyAnnotation(itemType, new Dictionary<string, IEdmProperty>() {{"Size",itemType.FindProperty("Size")}})
tempModel.AddAlternateKeyAnnotation(itemType, new Dictionary<string, IEdmProperty>() {{"CommonName",itemType.FindProperty("CommonName")}})
Examine the Startup Class
Edit Startup.dbl
The final class that was generated was the Startup class, which is responsible for configuring the whole ASP.NET Core MVC, Web API and OData environments, as well as various other optional components.
Currently the code in the 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”
Once again additional code will be added to the Startup class as we progress through the workshop and enable additional features.
Examine a Controller Class
Look in your Services.Controllers project and select and open one of the controller classes that you have generated. The controller classes have the same name as the structure they represent, suffixed with the word "Controller".
If you have ever worked in an ASP.NET MVC or ASP.NET Web API environment then 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 which 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.
Currently, the controller classes don't actually expose any web service endpoints, but that will change as you enable various code generation options as you build out your REST API. Many of the options in regen.bat result in additional code being generated into the controller classes.
Examine a Model Class
Look in your Services.Models project and select and open one of the data model classes that you have generated. The data model classes have the same name as the structure they represent.
Model classes are data classes that represents the data of a particular record. Instances of data model classes are referred to as data objects.
The main purpose of the data classes is to internally store the value of a record (in the private field mSynergyData) as well as a copy of the original record (in the private field mOriginalSynergyData) if the instance was originally constructed from an existing record.
There are constructors to create blank and populated instances, and the main bulk of the code consists of properties that represent the fields in the underlying Synergy record, as .NET CLS types.
There are properties that expose the current state of the full record, as well as the original state of the full record, and also a property that exposes a copy of the metadata related to the type. That will be discussed next.
A data class is generated for each of the structures being processed.
Examine a MetaData Class
Look in your Services.Models project and select and open one of the metadata classes that you have generated. The metadata classes have the same name as the structure they represent, suffixed with the word "MetaData".
As the name suggests, metadata classes expose additional metadata related to the structure being represented. This metadata is used by the internal code within Harmony Core.
You will notice that code in the class declares information about the fields and keys in the structure, and provides information relates to things like underlying Synergy data type, length of field, position in the overall record, any decimal precision, and so on.
The code also declares any and all fields that are involved with the structures keys.
Other utility code is present to, for example, assist in preparing literal key values for the various keys present in the structure.
A metadata class is generated for each of the structures being processed.
Examine the DbContext Class
Look in your Services.Models project and select and open the source file DbContext.dbl.
A DB Context 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.
You will notice that its primary purpose is to expose properties that represent all of the various data types that are being exposed in the environment. For example, if your environment exposes a CUSTOMER structure then you will see a public property named Customers that looks like this:
;;; <summary>
;;; Exposes Customer data.
;;; </summary>
public readwrite property Customers, @DbSet<Customer>
You will see one such public property for each of the data structures that you expose.
As you enable additiona options within the code generation environment, you will notice that additional code is often generated into the DbContext class.
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.
An instance of the DbContext class provides the mechanism by which your code interacts with the back-end data, via the Harmony Core Entity Framework provider.