Dynamics Template-based Code Generator – Supercharged – Overview | SwissKnife Series

Microsoft provides a tool within the Dynamics SDK called CrmSvcUtil. It generates early-bound entity code, which includes classes for each entity in CRM with properties for each field and relation. Microsoft’s Dynamics early-bound entity generator provides basic functionality through a command-line interface. In this article, I am going to introduce the Dynamics Template-based Code Generator whose only goal is to make our (developers’) lives easier.

The first part of this article will highlight some of the tool’s features. I won’t go into too much detail, as I want to give you an idea of what is offered. Specifics, details, and how-tos will be covered in later parts of the article.

Downsides

The tool produces SDK-specific properties, like EntityReference and OptionSetValue, which requires a tiny bit extra work to map to a more generic type that is more suited when communicating with an external party. From a CRM developer perspective, it’s a bit tedious to wrap straightforward values in another object layer that simply points to a single entity. In addition, when using OptionSetValues, we have to manually define those values somewhere in the code to avoid mistakes. Early-bound is hinged on alleviating this type of issues.

By default, the utility generates all entities, in order to limit the number of entities generated, we have to create an XML definition file (steps here). It’s a step in the right direction, but still, you have to manually configure the names by hand.

Finally, the generated code is based on a hard-coded template, which is hard to modify. In addition, the tool is external to the target projects’ IDE (Visual Studio), which leads to an inconvenient context switching or requiring manual configuration per project.

Improvement Steps

Considering the above downsides, there are a few areas and ideas that could make our lives so much easier.

First, create a UI that can easily filter the list of entities generated. That has been realised by our community in the form of XrmToolBox plugins. Those tools also support replacing the OptionSetValue type with safer enum-based types.

Let’s take this a few steps further and supercharge a-near-daily activity in our development workflow. In the next few sections, I will demonstrate the features of the custom Dynamics Template-based Code Generator Visual Studio extension (I will point out the base-code author’s work of course).

Visual Studio Integration

Back in 2015, I found a gem of a tool created by Eric Labashosky (here). The tool did what the SDK tool did exactly, except, it provided a UI integrated into Visual Studio. Furthermore, it provided a per-project T4 template that greatly facilitated customising the generated code in ways only the SDK tool can dream of.

I had such a vision for this tool, that I took it upon myself to expand it to new heights. Thank you so much, Eric, for the innovative idea, and for providing the base for so many other tools I have created.

Dynamics Template-based Code Generator

The tool gives the following benefits:

• It preserves the original CrmSvcUtil structure and logic
  • Replaced the SDK types with .NET types
    • E.g. OptionSetValue => Enum (Enum[] for Multi-select), EntityReference => Guid, Money => decimal, … etc.
• Generate only what’s needed
  • Only choose the entities required
  • Only the fields required
• Additional control
  • Option to use display names of entities and fields as variable names instead of logical names
  • Override field names inside the tool’s UI
  • Ability to Lock variable names to avoid code errors on regeneration
• Greatly enhanced regeneration speed by only fetching changed metadata from the server
• Support for strongly-typed alternate keys, for entities and Entity References
• Add annotations for model validation
• Generate metadata
  • Field logical and schema names
  • Localised labels
• Many options to optimise generated code size even further
• Define web service contracts with different profiles
  • Option to mark certain fields as ‘read-only’
• Generate concrete classes for CRM Actions
• Support bulk relation loading
  • Support filtering on relation loading

Installation

The tool can be easily installed as a Visual Studio extension from the marketplace (here). Also available as an XrmToolBox plugin (here).

Adding a Template

The first step is simple:

Configuring the Tool

The configuration is used at the discretion of the templates. You can create your own template and use the configuration however you see fit. As such, the description below is only from the perspective of the default template.

Many options have a tooltip if you hover for 1 second or more.

Start it up

After adding the template, the tool is started automatically. If that doesn’t happen, you can always start it manually:

Define the connection parameters

Insert the connection string:

Select the entities

Click on ‘Early-bound and Metadata’ button.

The table displays the list of entities on your CRM server. The checkbox on the left selects the entity for generation, and the checkboxes on the right function as follows:

• Early-bound: generate the entity attributes.
• Apply Filter: when you double click the entity name, a filtering window appears. This option applies that filtering to the generated code; otherwise, it will be ignored, except renaming.
• Generate Metadata: generate class and constants for field logical names, schema names … etc.
• Option-set Labels: generate properties that contain all localised labels of option-set values.
• Lookup Labels: generate properties that contain the localised labels of lookup fields.
• Select Actions: generate concrete classes for the selected Actions. Global Actions are generated from the General Options window.

The filtering textbox at the top filters the list of entities — acts as a search box.

Filter Fields and Relationships

Double-clicking any entity name opens up the following window:

In this window, you can select which fields and relationships you want to generate, and rename those items if required (renaming is optional). However, the default template ignores other options (clear mode, flattening … etc.) for CRM entities. It will apply filtering only when ‘Apply Filter’ is selected for said entity, and only renaming is taken into account.

Contracts

Although the tool (and template) provides the option to adapt the SDK Entity objects to be serialised and communicated directly across web services, some architects prefer using specific contracts that satisfy the CQRS pattern in some way (more details here). That pattern requires much more than simple filtering for generated classes on the same fields; however, the tool provides the simple ability to define different contracts for different operations. E.g. you might want to share most fields on the entity on retrieve, but only allow updating 2 or 3 fields only.

The template provides two convenience extension methods to convert between CRM Entity and Contract objects, namely ConvertTo.

Click on the ‘Web Service Contracts’ button to access the contracts window. The options here are fairly similar to the ones in the CRM Entity window. You can access the field filtering by double-clicking an entity.

Clear value

An additional option is provided: ‘Clear Mode’, which changes the behaviour of dealing with ‘clearing’ values when saving to CRM, in other words, how to deal with null values. This effect is observed when ConvertTo is called. Possible values for this option:

• Default: uses the global setting option.
• Disabled: do not clear any CRM field values at all, regardless of the value provided through the contract object.
• Empty: if a contract field is empty, clear the value of the corresponding field in CRM.
• Convention: use certain value in the contract field object as a ‘convention’ to clear value in the CRM object; e.g. a value of -1 in an enum field, a 1970 date, a int.MinValue for integers, a Guid.Empty for Guid fields … etc.
• Flag: this option is a bit messy, in that it creates a property for each field that clears its corresponding field when set to ‘true’.

Filtering additional options

In the filtering window, some options that are ignored by CRM entities will now have an effect with contracts:

• Read-only: the field value will be ignored when converting a contract object to a CRM one.
• Clear Flag: generate a Flag property as described above.
• Language: sets this field as the label value for any lookups of this entity for this language.
• Flat: takes N-1 relation entity fields, and creates properties in the parent entity with its name as the prefix.

Flattening a relation

For relations, the template generates either an array of a related entity class or simply a property of the related entity type. E.g. if we have an Account entity that is related to a Contact by a 1-N relation, a property of type Contact[] will be created under the Account class. Another property of type Account will be created under the Contact class, representing the lookup there.

If we flatten that relationship, the template will create a property for each field in the Account under the Contact entity; e.g. AccountNumber on the Account entity will become Account_AccountNumber under the Contact class.

Global Settings

Click on the ‘gear’ icon at the bottom to open the settings window:

The global settings are mostly self-explanatory. In addition, hovering over some options will result in a descriptive overlay popping up after 1 second or so. Please post a comment/question here if you have any enquiries, and I will provide more details in this article.

Conclusion

The official SDK utility provides a great way to statically bind your CRM code; however, it’s not very convenient to use, and results in a large code size unnecessarily. The Visual Studio extension I described in this article makes dealing with entity-based code generation a breeze for developers.

Now that we have gone through a quick overview of the Dynamics Template-based Code Generator VS extension, in the next part of the article, we will go into more detail, delving into some features, and exploring the generated code using the default template.

The post Dynamics Template-based Code Generator – Supercharged – Overview | SwissKnife Series appeared first on Yagasoft Blog.