Skip to content

Commit 6dfb0bd

Browse files
ricredricred
committed
Enhance README with contributing guidelines and development workflow. Update project files to reflect changes in template generation, including new dependency injection support in client templates and improved XML documentation across various templates.
1 parent b2c74a6 commit 6dfb0bd

19 files changed

+879
-323
lines changed

‎DEVELOPER.md‎

Lines changed: 233 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,233 @@
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.

‎README.md‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -100,6 +100,20 @@ Turning on *SafeMode* will make the client before the first request to do an int
100100
# Acknowledgments
101101
Linq2GraphQL is inspired by [GraphQLinq](https://github.com/Giorgi/GraphQLinq) , thank you [Giorgi](https://github.com/Giorgi)
102102

103+
## Contributing
104+
105+
Are you a developer looking to contribute to this project? Please see our [Developer Guide](DEVELOPER.md) for comprehensive information about:
106+
107+
- T4 template development workflow
108+
- Code generation system architecture
109+
- Troubleshooting common issues
110+
- Best practices for template development
111+
- Manual template regeneration process
112+
113+
## Development Workflow
114+
115+
**⚠️ Important for Developers:** When modifying T4 templates (`.tt` files), you must manually regenerate the corresponding `.cs` files using Visual Studio's "Run Custom Tool" feature. See [DEVELOPER.md](DEVELOPER.md) for detailed instructions.
116+
103117
[![Stargazers repo roster for @linq2graphql/linq2graphql.client](https://reporoster.com/stars/dark/linq2graphql/linq2graphql.client)](https://github.com/linq2graphql/linq2graphql.client/stargazers)
104118

105119

‎src/Linq2GraphQL.Generator/Linq2GraphQL.Generator.csproj‎

Lines changed: 5 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -50,10 +50,6 @@
5050
<LastGenOutput>InterfaceTemplate.cs</LastGenOutput>
5151
<Generator>TextTemplatingFilePreprocessor</Generator>
5252
</None>
53-
<None Update="Templates\Methods\MethodsTemplate.tt">
54-
<Generator>TextTemplatingFilePreprocessor</Generator>
55-
<LastGenOutput>MethodsTemplate.cs</LastGenOutput>
56-
</None>
5753
<None Update="Templates\Methods\IMethodsTemplate.tt">
5854
<Generator>TextTemplatingFilePreprocessor</Generator>
5955
<LastGenOutput>IMethodsTemplate.cs</LastGenOutput>
@@ -87,6 +83,11 @@
8783
<AutoGen>True</AutoGen>
8884
<DependentUpon>ClassTemplate.tt</DependentUpon>
8985
</Compile>
86+
<Compile Update="Templates\Client\ClientExtensionsTemplate.cs">
87+
<DesignTime>True</DesignTime>
88+
<AutoGen>True</AutoGen>
89+
<DependentUpon>ClientExtensionsTemplate.tt</DependentUpon>
90+
</Compile>
9091
<Compile Update="Templates\Client\ClientTemplate.cs">
9192
<DesignTime>True</DesignTime>
9293
<AutoGen>True</AutoGen>
@@ -107,11 +108,6 @@
107108
<AutoGen>True</AutoGen>
108109
<DependentUpon>InterfaceTemplate.tt</DependentUpon>
109110
</Compile>
110-
<Compile Update="Templates\Methods\MethodsTemplate.cs">
111-
<DesignTime>True</DesignTime>
112-
<AutoGen>True</AutoGen>
113-
<DependentUpon>MethodsTemplate.tt</DependentUpon>
114-
</Compile>
115111
<Compile Update="Templates\Methods\IMethodsTemplate.cs">
116112
<DesignTime>True</DesignTime>
117113
<AutoGen>True</AutoGen>
@@ -122,11 +118,6 @@
122118
<DesignTime>True</DesignTime>
123119
<DependentUpon>InputFactoryClassTemplate.tt</DependentUpon>
124120
</Compile>
125-
<Compile Update="Templates\Client\ClientExtensionsTemplate.cs">
126-
<AutoGen>True</AutoGen>
127-
<DesignTime>True</DesignTime>
128-
<DependentUpon>ClientExtensionsTemplate.tt</DependentUpon>
129-
</Compile>
130121
<Compile Update="Templates\Scalars\ScalarTemplate.cs">
131122
<DesignTime>True</DesignTime>
132123
<AutoGen>True</AutoGen>

0 commit comments

Comments
 (0)