Skip to content

Code Generation

Jump to bottom
Steve Ives edited this page Mar 30, 2020 · 29 revisions

Harmony Core Logo

Code Generation

In most Harmony Core development environments CodeGen will be used to generate much of the code required to build the API.

The harmonycore project template provides two files that can be used to drive the required code generation. These files can both be found in the Solution Items folder in the Visual Studio solution, and are named:

  • regen.bat
  • UserDefinedTokens.tkn

Code Generation Batch File (regen.bat)

This batch file is pre configured with commands that will perform the code generation that is required to build out a typical Harmony Core REST API.

  1. Look under Solution Items and edit the regen.bat file.
  2. Near the top of the file look for a comment “Specify the names of the projects to generate code into:”

Near the top of the file you will see a section of code that defines several environment variables, like this:

rem ================================================================================================================================
rem Specify the names of the projects to generate code into:

set ServicesProject=Services
set ModelsProject=Services.Models
set ControllersProject=Services.Controllers
set HostProject=Services.Host
set TestProject=Services.Test

These environment variables are used to define the folders that various types of code will be generated into. The values are pre-configured to match the project folders that were provided by the project template.

Just below you will see a section of code that looks like this:

rem ==================================================================================
rem Specify the names of the repository structures to generate code from:

set DATA_STRUCTURES=
set FILE_STRUCTURES=%DATA_STRUCTURES%

rem DATA_STRUCTURES Is a list all of structures that you wish to generate models and
rem                 controllers for. In other words it declares all of the "entities"
rem                 that are being represented and exposed by the environment.
rem
rem FILE_STRUCTURES If you don't have multi-record format files then this should be the
rem                 same as DATA_STRUCTURES. But if you do then FILE_STRUCTURES should
rem                 only list ONE of the structures assigned to each file, so this list
rem                 will be a subset of DATA_STRUCTURES.

The DATA_STRUCTURES environment variable is used to define which repository structures will be processed by CodeGen, and hence which source files will be produced. Simply list the named of those structures, separated by spaces, like this:

set DATA_STRUCTURES=CUSTOMERS ITEMS ORDERS ORDER_ITEMS VENDORS

In the sample environment we have implemented a mechanism that enables appropriate primary key values to be generated when new records are added via POST operations. This basically involves a “system parameters” relative file that defines data such as “next customer number” and “next order number”.

Further down in the file you will find a block of code that looks like this:

rem ================================================================================
rem Comment or uncomment the following lines to enable or disable optional features:

rem set ENABLE_GET_ALL=-define ENABLE_GET_ALL
rem set ENABLE_GET_ONE=-define ENABLE_GET_ONE
rem set ENABLE_SELF_HOST_GENERATION=YES
rem set ENABLE_CREATE_TEST_FILES=-define ENABLE_CREATE_TEST_FILES
rem set ENABLE_SWAGGER_DOCS=-define ENABLE_SWAGGER_DOCS
rem set ENABLE_POSTMAN_TESTS=YES
rem set ENABLE_ALTERNATE_KEYS=-define ENABLE_ALTERNATE_KEYS
rem set ENABLE_COUNT=-define ENABLE_COUNT
rem set ENABLE_PROPERTY_ENDPOINTS=-define ENABLE_PROPERTY_ENDPOINTS
rem set ENABLE_PROPERTY_VALUE_DOCS=-define ENABLE_PROPERTY_VALUE_DOCS
rem set ENABLE_SELECT=-define ENABLE_SELECT
rem set ENABLE_FILTER=-define ENABLE_FILTER
rem set ENABLE_ORDERBY=-define ENABLE_ORDERBY
rem set ENABLE_TOP=-define ENABLE_TOP
rem set ENABLE_SKIP=-define ENABLE_SKIP
rem set ENABLE_RELATIONS=-define ENABLE_RELATIONS
rem set ENABLE_PUT=-define ENABLE_PUT
rem set ENABLE_POST=-define ENABLE_POST
rem set ENABLE_PATCH=-define ENABLE_PATCH
rem set ENABLE_DELETE=-define ENABLE_DELETE
rem set ENABLE_SPROC=-define ENABLE_SPROC
rem set ENABLE_AUTHENTICATION=-define ENABLE_AUTHENTICATION
rem set ENABLE_FIELD_SECURITY=-define ENABLE_FIELD_SECURITY
rem set ENABLE_UNIT_TEST_GENERATION=YES
rem set ENABLE_CASE_SENSITIVE_URL=-define ENABLE_CASE_SENSITIVE_URL
rem set ENABLE_CORS=-define ENABLE_CORS
rem set ENABLE_IIS_SUPPORT=-define ENABLE_IIS_SUPPORT
rem set ENABLE_OVERLAYS=-f o

Each of these represents an option to enable a certain piece of functionality in your Harmony Core environment. Some of these options cause addiditional files to be generated, while others affect what code is generated in some of the source files.

As you can see all of the options are commented out by default, so they are not active. You can remove the rem statement before an option in order to enable the option.

All of these options and exactly what each option is used for is discussed throughout the various pages of this documentation.

User Defined Tokens File

UserDefinedTokens.tkn is a CodeGen user-defined tokens file that is used to define values for several things. Thes values are inserted into various places in various generated source files.

The fact that the values are provided via user defined tokens gives you the opportunity to change the values to whatever you need to in order to build the REST API the way you want it.

The user defined tokens file looks like this:

;
; User defined tokens for the Harmony Core sample environment
;
<SERVICES_NAMESPACE>Services</SERVICES_NAMESPACE>
<MODELS_NAMESPACE>Services.Models</MODELS_NAMESPACE>
<CLIENT_MODELS_NAMESPACE>Services.Test.Models</CLIENT_MODELS_NAMESPACE>
<UNIT_TESTS_NAMESPACE>Services.Test.UnitTests</UNIT_TESTS_NAMESPACE>
;
<DATA_FOLDER>SampleData</DATA_FOLDER>
;
<API_DOCS_PATH>api-docs</API_DOCS_PATH>
<API_TITLE>Harmony Core Sample API</API_TITLE>
<API_VERSION>1.0.0</API_VERSION>
<API_DESCRIPTION>This environment presents an example of using Harmony Core to expose a collection of RESTful Web Service endpoints that allow you to interact with a small sample dataset.</API_DESCRIPTION>
<API_TERMS_URL>/license.html</API_TERMS_URL>
<API_CONTACT_EMAIL>jodah.veloper@synergexpsg.com</API_CONTACT_EMAIL>
<API_LICENSE_NAME>BSD 2-Clause License</API_LICENSE_NAME>
<API_LICENSE_URL>https://github.com/Synergex/HarmonyCore/blob/master/LICENSE.md</API_LICENSE_URL>
<API_ENABLE_QUERY_PARAMS>(MaxExpansionDepth=4)</API_ENABLE_QUERY_PARAMS>
;
<SERVER_PROTOCOL>https</SERVER_PROTOCOL>
<SERVER_NAME>localhost</SERVER_NAME>
<SERVER_HTTP_PORT>8085</SERVER_HTTP_PORT>
<SERVER_HTTPS_PORT>8086</SERVER_HTTPS_PORT>
<SERVER_BASE_PATH>odata</SERVER_BASE_PATH>
;
<OAUTH_SERVER>http://localhost:5000</OAUTH_SERVER>
<OAUTH_API>api1</OAUTH_API>
<OAUTH_CLIENT>ro.client</OAUTH_CLIENT>
<OAUTH_SECRET>CBF7EBE6-D46E-41A7-903B-766A280616C3</OAUTH_SECRET>
<OAUTH_TEST_USER>jodah</OAUTH_TEST_USER>
<OAUTH_TEST_PASSWORD>P@ssw0rd</OAUTH_TEST_PASSWORD>
;
<ROLES_GET>Employee,Manager</ROLES_GET>
<ROLES_POST>Manager</ROLES_POST>
<ROLES_PUT>Manager</ROLES_PUT>
<ROLES_PATCH>Manager</ROLES_PATCH>
<ROLES_DELETE>Manager</ROLES_DELETE>
;
<BRIDGE_SMC_INTERFACE>SampleXfplEnv</BRIDGE_SMC_INTERFACE>
;

Automating Code Generation in Visual Studio

It is likely that as you develop you may need to generate your code on many occasions, as you add more and more data files to the REST API for example. If you wish you can execute the regen.bat file manually:

  • From the Tools menu select Comand Prompt (x64). It is important to open the command prompt in this way so that the command prompt inherits your environment settings from the Visual Studio environment.
  • In the command prompt, move to the solution folder where regen.bat is located.
  • Execute the batch file.

If you prefer you can add a custom tool to the Visual Studio tools menu to make it easier to execute the regen.bat file. To do so:

  • From the menu select Tools > External Tools
  • Click the Add button to add a new tool
  • Set the Title to Generate Code
  • Set the Command to $(SolutionDir)regen.bat
  • set the Initial directory to $(SolutionDir)
  • Check the Use Output window option
  • Click the OK button to create the custom tool.

Having taken these steps you can now use the menu option Tools > Generate Code each time you need to execute the regen.bat script, and you will see the output from the code generator in the Output window.

Avoiding Editing Generated Code

We recommend that you avoid editing generated source files if possible. This allows you to regenerate your source files from updated and improved templates at any time, without losing custom changes.

We provide several extensibility mechanisms to help you avoid editing generated code, and if at all possible developers should use these mechanisms in preference to editing generated code.

Partial Classes

Wherever possible we try to implement Harmony Core functionality as partial classes, giving developers the opportunity to extend the default base functionality by writing additional complimentary code in separate source files.

Partial Methods

In several key places in the environment, where we know, or think that it is likely that you will need to plug in custom code, we have defined partial methods. You can implement these partial methods (in separate source files within the same project) to add your own custom logic.

Editing Template Files

As a last resort, rather than editing individual source files, determine whether it is possible to effect the change that you need by editing the CodeGen template files instead of generated source files. This may require advanced knowledge of CodeGen and CodeGen template files. If you get to this stage, please reach out to us to see if we can help. We prefer to find a solution that does not even require you to edit template files, even if that means that we need to make a change in the core environment.

Clone this wiki locally