mirror of
https://github.com/chylex/.NET-Community-Toolkit.git
synced 2024-10-17 06:42:48 +02:00
41abf66445
- Add default Git attributes. - Update Git ignores to latest. - Merge duplicate EditorConfig rules. - Format projects to EditorConfig rules. - Fix formatting errors in 'Guard.md' file.
18 lines
2.0 KiB
Markdown
18 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.
|