Tutorial 01 03 Development Environment Tour
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.
The first step in building any Harmony Core REST API is to generate a base set of files that provide the environment in which your API will operate, and the Entity Framework data access code that will be used to interact with your data.
To build a basic environment you simply need to list the repository structures related to the records that you wish to expose in the DATA_STRUCTURES environment variable in regen.bat, leave all of the various optional components disabled for the time being.
When you execute the regen.bat batch file you will be generating the following files:
- For each of the structures that you list
- A
modelclass will be generated in theServices.Modelsfolder. - a
metadataclass will be generated in theServices.Modelsfolder. - A
controllerclass will be generated in theServices.Controllersfolder.
- A
- An entity framework
DbContextclass will be generated in theServices.Modelsfolder. - An entity framework
EdmBuilderclass will be generated in theServicesfolder. - A
Startupclass will be generated in theServicesfolder.
You are now ready to generate the code for your basic environment, and you will do that by executing the regen.bat batch file.
If you have added a custom Generate Code tool to your Visual Studio Tools menu then go ahead and execute that tool. If not then from the Visual Studio Tools menu, open a command promot, go to the main soluton folder and execute regen.bat.
You should see messages as the code generation process completes, and if all is well the final message should say DONE.
Having generated the code, your next step is to add the source files into the corresponfing Visual Studio projects.
Richt-click on each of the projects that you need to add code to (refer to the list of files generated above) and use the "Add Existing Item" option.