Customizing Generated Code

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.

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.

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.

Partial Methods

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

        ;Give developers the chance to add a PreInitialize method, and define its signature
        partial method PreInitialize, void
        endmethod

        ;Give developers the chance to add a PostInitialize method, and define its signature
        partial method PostInitialize, void
        endmethod

        public method Initialize, void

        proc
            ;If there is a PreInitialize method, call it.
            PreInitialize()

            ;Normal initialization code goes here




            ;If there is a PostInitialize method, call it.
            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 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.