Customizing 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.
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.
A partial class is a class that is, or at least could be, made up of code that is defined in multiple class definitions, and most often those are defined in separate source files. For example, imagine that source file person.dbl contains the following code:
namespace MyApp
public partial class Person
public readwrite property PersonID, int
public readwrite property FirstName, string
public readwrite property LastName, string
endclass
endnamespace
And also imagine that a second sourceFile named PersonExtra.dbl contains this code:
namespace MyApp
public partial class Person
public readwrite property TimeOfBirth, DateTime
public readwrite property FavoriteColor, Color
endclass
endnamespace
Notice that both files declare a partial class named Person. When the code in these files is compiled, the compiler adds the code from the two files together and produces a single class that has all five properties. Once compiled, the result is as if the source code had looked like this:
namespace MyApp
public class Person
public readwrite property PersonID, int
public readwrite property FirstName, string
public readwrite property LastName, string
public readwrite property TimeOfBirth, DateTime
public readwrite property FavoriteColor, Color
endclass
endnamespace
In Harmony Core we use this technique to provide a way to extend or enhance code that has been automatically generated, without the need to edit the actual generated code. One source file is generated, and developers can optionally add a second file to enhance the generated code without editing it.
The term partial method is somewhat misleading. Partial methods is a technique that can be used in conjunction with partial classes and provides a way for developers to plug in additional code that will be executed at specific points in the execution of existing code. Here is an example
namespace MyApp
public partial class Environment
;;; <summary>
;;; Declare the ability to add a PreInitialize method, and define its signature
;;; </summary>
partial method PreInitialize, void
endmethod
;;; <summary>
;;; Declare the ability to add a PostInitialize method, and define its signature
;;; </summary>
partial method PostInitialize, void
endmethod
;;; <summary>
;;; Initialize the environment
;;; </summary>
public method Initialize, void
proc
;Call PreInitialize if present
PreInitialize()
;Normal initialization code goes here
;Call PostInitialize if present
PostInitialize()
endmethod
endclass
endnamespace
If a developer needs to execute custom code, either before or after the standard initialization code executes, they can do so by adding a partial class containing implementations for the partial methods. They could close to implement the PreInitialize method, the PostInitialize method, or both. Here is an example:
namespace MyApp
public partial class Environment
;;; <summary>
;;; Defines custom code to run before standard initialization code.
;;; </summary>
partial method PreInitialize, void
proc
;Custom code goes here
endmethod
;;; <summary>
;;; Defines custom code to run after standard initialization code.
;;; </summary>
partial method PostInitialize, void
proc
;Custom code goes here
endmethod
endclass
endnamespace
In the Harmony Core environment, we use this technique in several key places in our generated code, in places where we anticipate that you may need to plug in additional custom code. Let us know if you need more.
As a last resort, rather than editing individual source files, try to determine whether it is possible to cause 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.