Tuesday, September 11, 2007

Write your own Dynamic Template

How do you write your own custom Dynamic-Template for CodeRush?
CodeRush 2.0 introduced the concept of Dynamic-Templates which I blogged about some time ago here. However I don't think I ever went into any detail about how you make your own.

Well the process is fairly simple.

To show you how this is done I will give an example.

Lets create a new template that will spit out code like...
-------------------------------------------------------------
Throw New ApplicationException
-------------------------------------------------------------
OR
-------------------------------------------------------------
Throw New System.InvalidCastException
-------------------------------------------------------------
OR
-------------------------------------------------------------
Throw New System.IO.FileNotFoundException
-------------------------------------------------------------

...based the specifics of your mneumonic.

The first step is to create a Dynamic List.

Follow these steps to get to the Dynamic Lists options page:

-------------------------------------------------------------
1. From the DevExpress menu, select "Options...".
2. In the tree view on the left, navigate to this folder:

Core

3. Select the "Dynamic Lists" options page.
-------------------------------------------------------------

Now we would like to create a "neutral" list, because this list should be available to all language types.

(Note: This is not technically true. I would prefer to make this list available to only VB.net and C#, but for now there is no way to do this other than to duplicate the list for these types. This will not matter too much as we will only be creating templates that use this list in VB.Net and C# anyway)

To do this we must ensure that the language dropdown reads "neutral".

Next we will right click the "Lists" list in the center column of the options screen and select "New".

You will next have to fill out 3 boxes with values for Name, Variable and a Comment.

Name should mean something to you, and it is what will appear in the previously mentioned "Lists" list once you save. I typed "Exception Types" in this box.
Variable is the suitable variable name in which DXCore will store the user/developer's selected item. I typed "Exception" here.

...and Comment is just a comment. I guess you should write a comment here :)

Once saved, your list is ready to be filled. This is accomplished by adding items on the right-hand side of the options dialog.

Each item added requires a mnemonic and a value.
We will add the following items

a - ApplicationException
ic - InvalidCastException
fnf - FileNotFoundException

Then we can push "apply" and our list is saved.

So how do we use this list in a sensible way?

This is the easy part.

Navigate to the "Editor\Templates" options page and create a new template. I'm going to do the VB one for now so I'll select VB.Net from the language dropdown first.

This template will need a special name. You need to use a special syntax within the name to indicate where DXCore should allow the user to substitute one of the mneumonics we created earlier.

We will call our Template "tn?Exception?".

What this means is that our Template will be triggered by the letters 't' , 'n' and any mneumonic from the Dynamic-List.

The expansion of our template will be:-
-------------------------------------------------------------
Throw New «?Get(Exception)»
-------------------------------------------------------------
The '«?Get»' is a StringProvider. StringProviders are available to insert from the right-click context menu in the expansion box. The '(Exception)' is the parameter for the StringProvider. In this case the phrase '«?Get(Exception)»' retrieves the string held in the "Exception" variable placed there by the trigger mneumonic.

Once this little gem is saved, you should be able to trigger your 3 expansions with any of the 3 phrases 'tna', 'tnfnf' or 'tnic'

The great thing is that you can add additional exception types to the "Exception Types" Dynamic-List at any time and they will also work with the template we have defined.

So now you have some simple mneumonics to help throw exceptions.

No comments: