|
| 1 | +# Developer Guide |
| 2 | + |
| 3 | +This document provides comprehensive guidance for developers working on the Linq2GraphQL.Client project, particularly when modifying T4 templates and the code generation system. |
| 4 | + |
| 5 | +## Table of Contents |
| 6 | + |
| 7 | +- [Prerequisites](#prerequisites) |
| 8 | +- [Project Structure](#project-structure) |
| 9 | +- [T4 Template Development](#t4-template-development) |
| 10 | +- [Code Generation Workflow](#code-generation-workflow) |
| 11 | +- [Troubleshooting](#troubleshooting) |
| 12 | +- [Best Practices](#best-practices) |
| 13 | + |
| 14 | +## Prerequisites |
| 15 | + |
| 16 | +- **Visual Studio 2022** (recommended) or Visual Studio 2019/2022 |
| 17 | +- **.NET 8.0 SDK** or later |
| 18 | +- **T4 Template Support** - Ensure the "Text Template Transformation" workload is installed in Visual Studio |
| 19 | + |
| 20 | +## Project Structure |
| 21 | + |
| 22 | +``` |
| 23 | +src/ |
| 24 | +├── Linq2GraphQL.Generator/ # Main code generation project |
| 25 | +│ ├── Templates/ # T4 template files |
| 26 | +│ │ ├── Client/ # Client generation templates |
| 27 | +│ │ ├── Class/ # Class generation templates |
| 28 | +│ │ ├── Interface/ # Interface generation templates |
| 29 | +│ │ ├── Methods/ # Method generation templates |
| 30 | +│ │ └── Enum/ # Enum generation templates |
| 31 | +│ ├── GraphQLSchema/ # Schema parsing and processing |
| 32 | +│ └── ClientGenerator.cs # Main generation orchestration |
| 33 | +└── Linq2GraphQL.Client/ # Core client library |
| 34 | +``` |
| 35 | + |
| 36 | +## T4 Template Development |
| 37 | + |
| 38 | +### Understanding T4 Templates |
| 39 | + |
| 40 | +This project uses **T4 (Text Template Transformation Toolkit)** for code generation. T4 templates are `.tt` files that generate C# source code based on GraphQL schema information. |
| 41 | + |
| 42 | +#### Template File Types |
| 43 | + |
| 44 | +- **`.tt`** - Source T4 template files (human-editable) |
| 45 | +- **`.tt.cs`** - Partial class definitions for template variables and helper methods |
| 46 | +- **`.cs`** - Preprocessed T4 templates (auto-generated, contains the actual `TransformText()` method) |
| 47 | + |
| 48 | +### Template Development Workflow |
| 49 | + |
| 50 | +#### 1. Modifying T4 Templates |
| 51 | + |
| 52 | +When modifying `.tt` files: |
| 53 | + |
| 54 | +1. **Edit the `.tt` file** with your changes |
| 55 | +2. **Manually regenerate the `.cs` file** using Visual Studio's custom tool |
| 56 | +3. **Build the project** to ensure compilation |
| 57 | +4. **Test the generation** by running the client generator |
| 58 | + |
| 59 | +#### 2. Manual Template Regeneration |
| 60 | + |
| 61 | +**⚠️ IMPORTANT: After modifying any `.tt` file, you MUST manually regenerate the corresponding `.cs` file.** |
| 62 | + |
| 63 | +**In Visual Studio 2022:** |
| 64 | + |
| 65 | +1. Right-click on the `.tt` file in Solution Explorer |
| 66 | +2. Select **"Run Custom Tool"** |
| 67 | +3. This will regenerate the `.cs` file with your changes |
| 68 | +4. Verify the `.cs` file contains your updated template logic |
| 69 | + |
| 70 | +**Alternative method:** |
| 71 | +1. Right-click on the `.tt` file |
| 72 | +2. Select **"Properties"** |
| 73 | +3. Set **"Custom Tool"** to `TextTemplatingFilePreprocessor` |
| 74 | +4. Set **"Custom Tool Namespace"** to your desired namespace |
| 75 | +5. Save the file to trigger regeneration |
| 76 | + |
| 77 | +#### 3. Template File Dependencies |
| 78 | + |
| 79 | +Each T4 template requires: |
| 80 | + |
| 81 | +- **`.tt` file** - Contains the template logic and output format |
| 82 | +- **`.tt.cs` file** - Provides the partial class with constructor parameters and helper methods |
| 83 | +- **`.cs` file** - Auto-generated preprocessed template (regenerated from `.tt`) |
| 84 | + |
| 85 | +### Template Syntax |
| 86 | + |
| 87 | +#### Basic T4 Directives |
| 88 | + |
| 89 | +```t4 |
| 90 | +<#@ template language="C#" #> |
| 91 | +<#@ assembly name="System.Core" #> |
| 92 | +<#@ import namespace="System.Linq" #> |
| 93 | +``` |
| 94 | + |
| 95 | +#### Template Expressions |
| 96 | + |
| 97 | +```t4 |
| 98 | +<#= variableName #> <!-- Output variable value --> |
| 99 | +<# if (condition) { #> <!-- Conditional blocks --> |
| 100 | + // C# code here |
| 101 | +<# } #> |
| 102 | +<# foreach (var item in collection) { #> <!-- Loops --> |
| 103 | + // Process each item |
| 104 | +<# } #> |
| 105 | +``` |
| 106 | + |
| 107 | +#### Helper Methods |
| 108 | + |
| 109 | +Define helper methods in the `.tt.cs` file: |
| 110 | + |
| 111 | +```csharp |
| 112 | +public partial class TemplateName |
| 113 | +{ |
| 114 | + private readonly string variableName; |
| 115 | + |
| 116 | + public TemplateName(string variableName) |
| 117 | + { |
| 118 | + this.variableName = variableName; |
| 119 | + } |
| 120 | + |
| 121 | + private string HelperMethod() |
| 122 | + { |
| 123 | + return "Helper logic here"; |
| 124 | + } |
| 125 | +} |
| 126 | +``` |
| 127 | + |
| 128 | +## Code Generation Workflow |
| 129 | + |
| 130 | +### 1. Development Cycle |
| 131 | + |
| 132 | +``` |
| 133 | +Edit .tt file → Run Custom Tool → Build Project → Test Generation → Repeat |
| 134 | +``` |
| 135 | + |
| 136 | +### 2. Testing Changes |
| 137 | + |
| 138 | +After modifying templates: |
| 139 | + |
| 140 | +1. **Build the project** to ensure no compilation errors |
| 141 | +2. **Run the client generator** to test template output |
| 142 | +3. **Verify generated code** matches your expectations |
| 143 | +4. **Test the generated client** in a sample application |
| 144 | + |
| 145 | +### 3. Command Line Generation |
| 146 | + |
| 147 | +```bash |
| 148 | +# Build the generator project |
| 149 | +dotnet build src/Linq2GraphQL.Generator |
| 150 | + |
| 151 | +# Generate a client |
| 152 | +dotnet run --project src/Linq2GraphQL.Generator -- <endpoint> [options] |
| 153 | +``` |
| 154 | + |
| 155 | +## Troubleshooting |
| 156 | + |
| 157 | +### Common Issues |
| 158 | + |
| 159 | +#### T4 Templates Not Regenerating |
| 160 | + |
| 161 | +**Problem:** Changes to `.tt` files not reflected in generated output. |
| 162 | + |
| 163 | +**Solution:** |
| 164 | +1. Ensure you've run the **"Run Custom Tool"** on the `.tt` file |
| 165 | +2. Check that the `.cs` file was updated with your changes |
| 166 | +3. Clean and rebuild the project |
| 167 | +4. Verify the T4 preprocessor is working in Visual Studio |
| 168 | + |
| 169 | +#### Missing TransformText Method |
| 170 | + |
| 171 | +**Problem:** Compilation error "does not contain a definition for 'TransformText'". |
| 172 | + |
| 173 | +**Solution:** |
| 174 | +1. The `.cs` file is missing or outdated |
| 175 | +2. Run **"Run Custom Tool"** on the corresponding `.tt` file |
| 176 | +3. Ensure the `.tt.cs` file exists and has the correct partial class definition |
| 177 | + |
| 178 | +#### Template Variables Not Available |
| 179 | + |
| 180 | +**Problem:** Template variables like `namespaceName` or `name` are undefined. |
| 181 | + |
| 182 | +**Solution:** |
| 183 | +1. Check the `.tt.cs` file has the correct constructor parameters |
| 184 | +2. Verify the partial class has `readonly` fields for all template variables |
| 185 | +3. Ensure the `ClientGenerator.cs` passes the correct parameters when instantiating templates |
| 186 | + |
| 187 | +### Debugging Tips |
| 188 | + |
| 189 | +1. **Check the `.cs` file content** - It should contain your template logic in the `TransformText()` method |
| 190 | +2. **Verify template compilation** - Build errors often indicate template syntax issues |
| 191 | +3. **Use Visual Studio's T4 debugging** - Set breakpoints in the generated `.cs` files |
| 192 | +4. **Check build output** - Look for T4-related error messages |
| 193 | + |
| 194 | +## Best Practices |
| 195 | + |
| 196 | +### Template Design |
| 197 | + |
| 198 | +1. **Keep templates focused** - Each template should handle one specific aspect of code generation |
| 199 | +2. **Use helper methods** - Move complex logic to the `.tt.cs` file |
| 200 | +3. **Maintain readability** - Use clear variable names and consistent formatting |
| 201 | +4. **Handle edge cases** - Always check for null values and empty collections |
| 202 | + |
| 203 | +### Code Organization |
| 204 | + |
| 205 | +1. **Separate concerns** - Keep template logic separate from business logic |
| 206 | +2. **Use partial classes** - Leverage C# partial classes for template organization |
| 207 | +3. **Consistent naming** - Follow the project's naming conventions |
| 208 | +4. **Documentation** - Include XML comments in generated code |
| 209 | + |
| 210 | +### Testing |
| 211 | + |
| 212 | +1. **Test with various schemas** - Ensure templates work with different GraphQL schemas |
| 213 | +2. **Validate generated code** - Check that generated code compiles and works correctly |
| 214 | +3. **Regression testing** - Ensure changes don't break existing functionality |
| 215 | +4. **Integration testing** - Test the complete generation pipeline |
| 216 | + |
| 217 | +### Version Control |
| 218 | + |
| 219 | +1. **Commit `.tt` and `.tt.cs` files** - These are source files |
| 220 | +2. **Ignore generated `.cs` files** - Add `**/*.cs` to `.gitignore` for auto-generated files |
| 221 | +3. **Document template changes** - Include clear commit messages for template modifications |
| 222 | +4. **Review generated output** - Verify that template changes produce the expected results |
| 223 | + |
| 224 | +## Getting Help |
| 225 | + |
| 226 | +- **Check existing templates** - Review similar templates for examples |
| 227 | +- **T4 documentation** - Microsoft's T4 documentation provides comprehensive guidance |
| 228 | +- **Project issues** - Search existing GitHub issues for similar problems |
| 229 | +- **Community support** - Reach out to the project maintainers or community |
| 230 | + |
| 231 | +--- |
| 232 | + |
| 233 | +**Note:** T4 template development requires careful attention to the regeneration workflow. Always remember to run the custom tool after modifying `.tt` files to ensure your changes are applied to the generated code. |
0 commit comments