bbradson
30 lines
2.0 KiB
Markdown
30 lines
2.0 KiB
Markdown
# T4 templates and generated APIs
|
|
|
|
This folder contains a number of template files (with the `.tt` or `.ttinclude` extensions) and the generated `.g.cs`
|
|
files generated by those templates. The template files use the T4 format, which is natively supported by Visual Studio (
|
|
more info is available [here](https://docs.microsoft.com/visualstudio/modeling/code-generation-and-t4-text-templates)).
|
|
|
|
## Why is this needed?
|
|
|
|
There are a few reasons why T4 templates are used for the `Guard` class:
|
|
|
|
- Especially when many overloads are available for an API, using templates makes it much easier to maintain code and
|
|
spot mistakes, as the actual number of lines of code to review is much smaller: it's just the same code from each
|
|
template!
|
|
- Using type-specific overloads instead of generic methods can result in faster code. For instance, T4 templates are
|
|
used to generate overloads for comparison APIs (eg. `Guard.IsGreaterThan(int, int, string)`). This results in more
|
|
compact and optimized code as opposed to a generic method using `where T : IComparable<T>` as type constraint.
|
|
- In some cases, using generic methods just isn't possible. For instance, types like `Span<T>` and `ReadOnlySpan<T>`
|
|
can't be used as generic type parameters, and even if that had been possible, they don't implement an interface we
|
|
could use in the generic type constraint. Using T4 templates solves this issue, as we can just have specialized method
|
|
for each supported type or collection type.
|
|
|
|
## How to make changes
|
|
|
|
If you need to change an API that is declared in a template, or to add a new one, just edit the right `.tt` file and
|
|
save it: Visual Studio will take care of updating the generated `.g.cs` file automatically. Don't make changes to those
|
|
generated `.g.cs` files directly, as those will be overwritten as soon as their source template is updated.
|
|
|
|
Note that all the `.g.cs` files are checked in into the repository, so if you do make changes to a template file, make
|
|
sure to also include the updated `.g.cs` file in your commits.
|