Skip to content

Commit 221de0f

Browse files
CopilotPureWeen
Copilot
and
PureWeen
committed
Move template instructions to path-specific YAML file
Co-authored-by: PureWeen <5375137+PureWeen@users.noreply.github.com>
1 parent e81fd7a commit 221de0f

File tree

2 files changed

+94
-86
lines changed

2 files changed

+94
-86
lines changed

‎.github/copilot-instructions.md‎

Lines changed: 0 additions & 86 deletions
Original file line numberDiff line numberDiff line change
@@ -266,92 +266,6 @@ All PRs are required to have this at the top of the description:
266266

267267
Always put that at the top, without the block quotes. Without it, the users will NOT be able to try the PR and your work will have been in vain!
268268

269-
## Working with Templates
270-
271-
When modifying files in the `src/Templates/` directory, you must follow special template semantics and conventions to ensure the templates work correctly when users create new projects.
272-
273-
### Template Conditional Compilation Directives
274-
275-
Templates use special comment markers to control how preprocessor directives are processed during template instantiation:
276-
277-
#### Platform-Specific Directives (Build-Time)
278-
279-
Platform-specific `#if` directives (like `#if WINDOWS`, `#if ANDROID`, `#if IOS`, `#if MACCATALYST`) must be wrapped with `//-:cnd:noEmit` and `//+:cnd:noEmit` markers:
280-
281-
```csharp
282-
//-:cnd:noEmit
283-
#if WINDOWS
284-
// Windows-specific code
285-
#endif
286-
//+:cnd:noEmit
287-
```
288-
289-
**Why?** These markers tell the template engine to preserve these directives in the generated code exactly as-is, so they will be evaluated at compile-time when the user builds their project.
290-
291-
**Examples:**
292-
```csharp
293-
//-:cnd:noEmit
294-
#if DEBUG
295-
builder.Logging.AddDebug();
296-
#endif
297-
//+:cnd:noEmit
298-
299-
//-:cnd:noEmit
300-
#if IOS || MACCATALYST
301-
handlers.AddHandler<CollectionView, CollectionViewHandler2>();
302-
#endif
303-
//+:cnd:noEmit
304-
305-
//-:cnd:noEmit
306-
#if WINDOWS
307-
Microsoft.Maui.Controls.Handlers.Items.CollectionViewHandler.Mapper.AppendToMapping(
308-
"KeyboardAccessibleCollectionView",
309-
(handler, view) => { /* ... */ });
310-
#endif
311-
//+:cnd:noEmit
312-
```
313-
314-
#### Template Parameter Directives (Template-Time)
315-
316-
Template parameter directives (like `#if (IncludeSampleContent)`) do NOT use the `//-:cnd:noEmit` markers:
317-
318-
```csharp
319-
#if (IncludeSampleContent)
320-
using CommunityToolkit.Maui;
321-
#endif
322-
```
323-
324-
**Why?** These directives are evaluated when the template is instantiated (when user runs `dotnet new maui`), not when the code is compiled.
325-
326-
### Template Naming Conventions
327-
328-
- Template project names use placeholders like `MauiApp._1` which get replaced with the user's actual project name
329-
- Namespaces follow the same pattern: `namespace MauiApp._1;`
330-
- These will be transformed to the user's chosen project name during template instantiation
331-
332-
### Files to Exclude from Template Changes
333-
334-
Never modify auto-generated files in templates:
335-
- `cgmanifest.json` - Auto-generated component governance manifest
336-
- `templatestrings.json` - Auto-generated localization file
337-
338-
These files are regenerated during the build process and should not be manually edited.
339-
340-
### Template Testing
341-
342-
When making changes to templates:
343-
1. Build the template project: `dotnet build src/Templates/src/Microsoft.Maui.Templates.csproj`
344-
2. For comprehensive testing, use the `build.ps1` script in the Templates directory to pack, install, and test the template
345-
3. Verify the generated project compiles for all target platforms
346-
347-
### Quick Reference
348-
349-
| Directive Type | Wrapper Needed | Example |
350-
|---|---|---|
351-
| Platform-specific (`#if WINDOWS`, `#if ANDROID`, etc.) | ✅ Yes - use `//-:cnd:noEmit` | Build-time platform detection |
352-
| Debug mode (`#if DEBUG`) | ✅ Yes - use `//-:cnd:noEmit` | Build configuration |
353-
| Template parameters (`#if (IncludeSampleContent)`) | ❌ No | Template instantiation options |
354-
355269
## Additional Resources
356270

357271
- [Development Guide](.github/DEVELOPMENT.md)

‎.github/copilot-instructions/templates.yml‎

Lines changed: 94 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,94 @@
1+
# Copilot instructions for working with .NET MAUI Templates
2+
# This file provides specific guidance when modifying template files in src/Templates/
3+
4+
# Apply these instructions only to files in the Templates directory
5+
applicability:
6+
paths:
7+
- 'src/Templates/**'
8+
9+
instructions: |
10+
# Working with .NET MAUI Templates
11+
12+
When modifying files in the `src/Templates/` directory, you must follow special template semantics and conventions to ensure the templates work correctly when users create new projects.
13+
14+
## Template Conditional Compilation Directives
15+
16+
Templates use special comment markers to control how preprocessor directives are processed during template instantiation:
17+
18+
### Platform-Specific Directives (Build-Time)
19+
20+
Platform-specific `#if` directives (like `#if WINDOWS`, `#if ANDROID`, `#if IOS`, `#if MACCATALYST`) must be wrapped with `//-:cnd:noEmit` and `//+:cnd:noEmit` markers:
21+
22+
```csharp
23+
//-:cnd:noEmit
24+
#if WINDOWS
25+
// Windows-specific code
26+
#endif
27+
//+:cnd:noEmit
28+
```
29+
30+
**Why?** These markers tell the template engine to preserve these directives in the generated code exactly as-is, so they will be evaluated at compile-time when the user builds their project.
31+
32+
**Examples:**
33+
```csharp
34+
//-:cnd:noEmit
35+
#if DEBUG
36+
builder.Logging.AddDebug();
37+
#endif
38+
//+:cnd:noEmit
39+
40+
//-:cnd:noEmit
41+
#if IOS || MACCATALYST
42+
handlers.AddHandler<CollectionView, CollectionViewHandler2>();
43+
#endif
44+
//+:cnd:noEmit
45+
46+
//-:cnd:noEmit
47+
#if WINDOWS
48+
Microsoft.Maui.Controls.Handlers.Items.CollectionViewHandler.Mapper.AppendToMapping(
49+
"KeyboardAccessibleCollectionView",
50+
(handler, view) => { /* ... */ });
51+
#endif
52+
//+:cnd:noEmit
53+
```
54+
55+
### Template Parameter Directives (Template-Time)
56+
57+
Template parameter directives (like `#if (IncludeSampleContent)`) do NOT use the `//-:cnd:noEmit` markers:
58+
59+
```csharp
60+
#if (IncludeSampleContent)
61+
using CommunityToolkit.Maui;
62+
#endif
63+
```
64+
65+
**Why?** These directives are evaluated when the template is instantiated (when user runs `dotnet new maui`), not when the code is compiled.
66+
67+
## Template Naming Conventions
68+
69+
- Template project names use placeholders like `MauiApp._1` which get replaced with the user's actual project name
70+
- Namespaces follow the same pattern: `namespace MauiApp._1;`
71+
- These will be transformed to the user's chosen project name during template instantiation
72+
73+
## Files to Exclude from Template Changes
74+
75+
Never modify auto-generated files in templates:
76+
- `cgmanifest.json` - Auto-generated component governance manifest
77+
- `templatestrings.json` - Auto-generated localization file
78+
79+
These files are regenerated during the build process and should not be manually edited.
80+
81+
## Template Testing
82+
83+
When making changes to templates:
84+
1. Build the template project: `dotnet build src/Templates/src/Microsoft.Maui.Templates.csproj`
85+
2. For comprehensive testing, use the `build.ps1` script in the Templates directory to pack, install, and test the template
86+
3. Verify the generated project compiles for all target platforms
87+
88+
## Quick Reference
89+
90+
| Directive Type | Wrapper Needed | Example |
91+
|---|---|---|
92+
| Platform-specific (`#if WINDOWS`, `#if ANDROID`, etc.) | ✅ Yes - use `//-:cnd:noEmit` | Build-time platform detection |
93+
| Debug mode (`#if DEBUG`) | ✅ Yes - use `//-:cnd:noEmit` | Build configuration |
94+
| Template parameters (`#if (IncludeSampleContent)`) | ❌ No | Template instantiation options |

0 commit comments

Comments
 (0)