Copilot instructions

1---
2applyTo: "src/Templates/**"
3---
4 
5# Working with .NET MAUI Templates
6 
7## 1. Overview
8 
9When 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. This guide covers conditional compilation directives, naming conventions, file exclusions, and testing procedures.
10 
11## 2. Conditional Compilation
12 
13Templates use special comment markers to control how preprocessor directives are processed during template instantiation.
14 
15### Build-Time Directives (Platform-Specific)
16 
17Platform-specific `#if` directives (like `#if WINDOWS`, `#if ANDROID`, `#if IOS`, `#if MACCATALYST`) must be wrapped with `//-:cnd:noEmit` and `//+:cnd:noEmit` markers:
18 
19```csharp
20//-:cnd:noEmit
21#if WINDOWS
22    // Windows-specific code
23#endif
24//+:cnd:noEmit
25```
26 
27**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.
28 
29**Examples:**
30```csharp
31//-:cnd:noEmit
32#if DEBUG
33    builder.Logging.AddDebug();
34#endif
35//+:cnd:noEmit
36 
37//-:cnd:noEmit
38#if IOS || MACCATALYST
39    handlers.AddHandler<CollectionView, CollectionViewHandler2>();
40#endif
41//+:cnd:noEmit
42 
43//-:cnd:noEmit
44#if WINDOWS
45    Microsoft.Maui.Controls.Handlers.Items.CollectionViewHandler.Mapper.AppendToMapping(
46        "KeyboardAccessibleCollectionView", 
47        (handler, view) => { /* ... */ });
48#endif
49//+:cnd:noEmit
50```
51 
52### Template-Time Directives (Template Parameters)
53 
54Template parameter directives (like `#if (IncludeSampleContent)`) do NOT use the `//-:cnd:noEmit` markers:
55 
56```csharp
57#if (IncludeSampleContent)
58using CommunityToolkit.Maui;
59#endif
60```
61 
62**Why?** These directives are evaluated when the template is instantiated (when user runs `dotnet new maui`), not when the code is compiled.
63 
64## 3. Naming and Placeholders
65 
66- Template project names use placeholders like `MauiApp._1` which get replaced with the user's actual project name
67- Namespaces follow the same pattern: `namespace MauiApp._1;`
68- These will be transformed to the user's chosen project name during template instantiation
69 
70## 4. Files to Avoid Editing
71 
72Never modify auto-generated files in templates:
73- `cgmanifest.json` - Auto-generated component governance manifest
74- `templatestrings.json` - Auto-generated localization file
75 
76These files are regenerated during the build process and should not be manually edited.
77 
78## 5. Testing and Verification
79 
80When making changes to templates:
811. Build the template project: `dotnet build src/Templates/src/Microsoft.Maui.Templates.csproj`
822. For comprehensive testing, use the `build.ps1` script in the Templates directory to pack, install, and test the template
833. Verify the generated project compiles for all target platforms
84 
85## 6. Quick Reference Table
86 
87| Directive Type | Wrapper Needed | Example |
88| --- | --- | --- |
89| Platform-specific (`#if WINDOWS`, `#if ANDROID`, etc.) | ✅ Yes - use `//-:cnd:noEmit` | Build-time platform detection |
90| Debug mode (`#if DEBUG`) | ✅ Yes - use `//-:cnd:noEmit` | Build configuration |
91| Template parameters (`#if (IncludeSampleContent)`) | ❌ No | Template instantiation options |
92