Source templates

How it works

In contrast to traditional templates, source templates can be created anywhere in the code of your project as extension methods. You can define them for some specific types of your project or for any standard types. You can even make a source template available for all types by creating it as an extension method for object.

Here is an example that illustrates a simplest application of a source template. Our template forEach, will be available for all generic collections — this is defined by the parameter this IEnumerable<T> x. It will insert code that iterates the collection, as specified in the method body. We can define the template in any static class in our project. JetBrains Rider will identify it as a template by the [SourceTemplate] attribute:

using JetBrains.Annotations;

public static class MySourceTemplates
{
  [SourceTemplate]
  public static void iterateCollection<T>(this IEnumerable<T> x)
  {
    foreach (var i in x)
    {
      // Do something useful here
      //$ $END$
    }
  }
}

public void Test(IEnumerable<string> enumerable)
{
  foreach (var i in enumerable)
  {
    // Do something useful here

  }
}

Note that the //$ $END$ comment in the template definition is nothing else but the predefined template parameter defining the caret position after the template is applied. You can use other parameters in your template to make the template more flexible.

Why use source templates

Create source templates

Template method and its body

A source template must be a public extension method and have the [SourceTemplate] attribute. The attribute is defined in the JetBrains.Annotations namespace, together with [NotNull], [CanBeNull] and other code annotation attributes. Therefore, to define source template methods, you should enable code annotations in your project.

[SourceTemplate]
public static void Bar(this Entity entity)
{
    /*$ var $entity$Id = entity.GetId();
    DoSomething($entity$Id); */
}

Parameters and macros

You can create a template parameter by adding a new parameter to the template method. By default, it will behave as an editable parameter, that is it will receive focus during the hot spot session when you apply the template. If you want to define a macro for this parameter, you need to add the [Macro] attribute as shown in the example below.
- The Expression property of the attribute defines which macro should be used. You can specify one of the available template macros.
- The Editable property optionally specifies whether the user will be able to edit the parameter when the template is applied. By default, all user-defined parameters are editable; the value -1 makes the parameter non-editable.
  If the same parameter is used several times in the template, only one occurrence becomes editable when the template is applied; other occurrences are changed synchronously. If necessary, you can define which occurrence becomes editable by specifying its zero-based index in the 'Editable' property.
```
[SourceTemplate]
public static void newGuid(this object obj,
    [Macro(Expression = "guid()", Editable = -1)] string newguid)
{
    Console.WriteLine(newguid);
}
```

You can turn any local variable in your template method into a template parameter. To do so, you need to add the [Macro] attribute to the template method definition, and specify the variable name in its Target property. For example:

[SourceTemplate]
[Macro(Target = "item", Expression = "suggestVariableName()")]
public static void forEach<T>(this IEnumerable<T> collection)
{
    foreach (var item in collection)
    {
        //$ $END$
    }
}

You can use predefined parameters as well as all user-defined parameters the same way as in other JetBrains Rider templates, wrapping the parameter identifier with two $ signs $param_name$ .
You can use user-defined template parameters inside string literals, e.g:
```
Console.WriteLine("A random GUID: $newguid$");
```
To use template parameters outside string literals, you need to put them in a special template comment that starts with the $ sign: //$ $param_name$. or /*$ $param_name$ */. For example:
```
[SourceTemplate]
[Macro(Target = "newguid", Expression = "guid()", Editable = -1)]
public static void newGuid(this object obj)
{
    //$ var guid = "$newguid$";
    Console.WriteLine("A random GUID: $newguid$");
}
```
The caller object as well as template parameters created as method parameters and local variables can be used both with and without the $ signs inside the special templates comments.

Source templates﻿

note

How it works﻿

Why use source templates﻿

Create source templates﻿

Template method and its body﻿

Parameters and macros﻿

Apply source templates﻿

Create a code fragment from a source template﻿

How it works

Why use source templates

Create source templates

Template method and its body

Parameters and macros

Apply source templates

Create a code fragment from a source template