Tutorial 02 03 Enabling OData Support

Enabling OData Support

Before you can start really implementing your RESTful API by choosing to add various types of endpoints, etc., you first need to get various pieces of "scaffolding" code in place to support a basic OData environment.

Data-centric Harmony Core OData services rely heavily on the automatic generation of code, and that code generation is based on three things:

• Information about your data structures and files. This information is obtained from your repository.
• Information about how to do certain things. This information is predefined in various CodeGen template files.
• Information your goals and objectives for the service. This is specified using Harmony Core settings (set in the Harmony Core GUI tool).

When designing Harmony Core, we defined various options that you can pick and choose from in order to produce a RESTful web service that meets your needs. Assuming that an appropriate repository is in place, you must provide two types of information:

• Which repository (data) structures are to be exposed by the RESTful web service
• Which Harmony Core options are to be used

You provide this information by setting options in the Harmony Core GUI tool.

Selecting the Structure(s) to Include

1. At a Windows command prompt, move to the directory that contains the solution file (.sln) for your Harmony Core solution and enter the following command:

   cd MyApi
   harmonycore gui
   

2. After briefly displaying a "Loading Solution" message, the Harmony Core GUI tool opens with five labels that represent tabs in the tool: Solution, OData, Structures, Traditional Bridge, and Interfaces. Click Structures. This is where you specify the names of the repository structures associated with the data that you want your RESTful web services to expose.

3. Click "Add structures" at the bottom of the screen (or press CTRL+A), which opens the "Add structures" screen. Then highlight a structure you want to include and click OK or press ENTER to add it. Repeat the process until the following structures have been added:

   • CUSTOMERS
   • ITEMS
   • ORDERS
   • ORDER_ITEMS
   • VENDORS

Note that Harmony Core is making several assumptions about the state of the repository:

• It assumes that your data structures have meaningful names--in other words, names that make sense to use in the URLs of a RESTful web service. For example, the name CUSTOMERS will probably work reasonably well because it is relatively obvious what the name refers to, whereas CTMMST is not so obvious.

• It assumes that each structure is assigned to exactly one file definition and that the name of that file definition is the same as the name of the structure.

If these assumptions are correct, as indeed they are for the Harmony Core sample repository, all you need to do is add the structures as instructed above.

Code Generation Options

The Harmony Core GUI tool also contains various options that determine which source files are generated, which CodeGen templates they are generated from, and in some cases what code is generated within those files. Some of these options are on the OData tab (you'll need to scroll down to see all the options available on this tab):

Other options are specific to a structure and can be accessed by selecting a structure on the Structures tab and scrolling up or down the screen to the right of the structure names. For example, in the following screen capture, the options in the right-hand pane of the Structures screen are for the Items structure, which is selected in the left-hand pane.

Each of these options is used to enable or disable some feature or functionality within the resulting RESTful web service, and each does one of two things:

• Causes additional source files to be generated
• Causes some change in the content of the files being generated

Generating the Initial Code

4. Save your changes by selecting File > Save from the menu.

5. Select CodeGen > Regen from the menu to generate code based on the settings you set in previous steps.

When code generation is finished, you'll see a message like the following indicating which source files were generated:

What Code was Generated

Code generation just generated 20 source files into four different locations:

Services.Models
Services.Controllers
Services
Services.Host

In the Services.Models Project Folder

Five model classes were generated in this folder. These classes are used to "wrap" an instance of a Synergy record in an OO way. One model class is produced for each of the repository structures selected for processing.

• Customer.dbl
• Item.dbl
• Order.dbl
• OrderItem.dbl
• Vendor.dbl

Five metadata classes were generated in this folder. These classes provide additional information about the model classes and things like keys and relationships to the Harmony Core environment. One metadata class is produced for each of the repository structures selected for processing.

• CustomerMetaData.dbl
• ItemMetaData.dbl
• OrderMetaData.dbl
• OrderItemMetaData.dbl
• VendorMetaData.dbl

Additionally, a DbContext class was generated in this folder. This class represents the available data, and is used by code elsewhere in the service to access data at runtime.

• DbContext.dbl

In the Services.Controllers Project Folder

Five controller classes were generated in this folder. These web service controllers expose web service endpoints to consumers of the service. Initially these controllers don't have any functionality because no endpoint types have been selected yet. One controller class is produced for each of the repository structures selected for processing.

• CustomersController.dbl
• ItemsController.dbl
• OrdersController.dbl
• OrderItemsController.dbl
• VendorsController.dbl

In the Services Project Folder

An EDM builder class was generated in this folder. This class builds an Entity Data Model for use by the Synergy EF Core provider that is used to access the data.

• EdmBuilder.dbl

A startup class was generated in this folder. This class contains code to configure the ASP.NET, OData, and EF Core environments at service startup.

• Startup.dbl

In the Services.Host Folder

When we selected ODataGenerator as one of the "Enabled generators" for each included structure, we instructed CodeGen to generate self-hosting code, SelfHost.dbl and SelfHostEnvironment.dbl (in addition to the EdmBuilder.dbl and Startup.dbl files this added to the Services folder). We won't do anything with the files in Services.Host at this point, but in the next tutorial (Configuring Self Hosting), we'll add this code to the Services.Host project, build it, and use it as we access the web service.

Adding the Code to the Visual Studio Projects

The next step is to add the source files that were just generated to the various Visual Studio projects:

6. In Solution Explorer, right-click on the Services project and select Add > Existing Item. Then, in the Add Existing Items window, navigate to the Services project folder, select the EdmBuilder.dbl and Startup.dbl source files, and click the Add button.

7. Repeat the process for the Services.Controllers project, adding the five new source files, the names of which all end with Controller.dbl.

8. Repeat the process for the Services.Models project, adding eleven new source files--i.e., all the .dbl files except AppSettings.dbl, which is already in the project.

At this point, it would be a good idea to take a few minutes to review the code that was just added and start to become familiar with it.

Building the Service

You don't have a fully working solution yet, but to check that things are in good shape, you can attempt to build the service.

9. From the Visual Studio menu, select Build > Rebuild Solution.

10. Check the Output window, where you should see something like this:

    1>------ Rebuild All started: Project: Repository, Configuration: Debug Any CPU ------
    2>------ Rebuild All started: Project: Services.Models, Configuration: Debug Any CPU ------
    3>------ Rebuild All started: Project: Services.Controllers, Configuration: Debug Any CPU ------
    4>------ Rebuild All started: Project: Services.Isolated, Configuration: Debug Any CPU ------
    5>------ Rebuild All started: Project: Services, Configuration: Debug Any CPU ------
    6>------ Rebuild All started: Project: Services.Host, Configuration: Debug Any CPU ------
    6>	bin\Debug\net6.0\(0,0): Error DBL-F-NULPR: %DBL-F-NULPR, No primary files specified
    6>Done building project "Services.Host.synproj" -- FAILED.
    ========== Rebuild All: 5 succeeded, 1 failed, 0 skipped ==========
    

All the code that was just generated should compile, but the Services.Host project will currently fail. The reason for the failure is that the project does not currently contain any self-hosting code.

---

Next topic: Configuring Self Hosting

---