Add template semantic markers for platform-specific directives and document template conventions

Copilot · PureWeen · Copilot · commit 89550005f8cc · 2025-10-22T16:18:00.000Z
Co-authored-by: PureWeen &lt;5375137+PureWeen@users.noreply.github.com&gt;
diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
@@ -266,6 +266,92 @@ All PRs are required to have this at the top of the description:
 
 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!
 
+## Working with Templates
+
+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.
+
+### Template Conditional Compilation Directives
+
+Templates use special comment markers to control how preprocessor directives are processed during template instantiation:
+
+#### Platform-Specific Directives (Build-Time)
+
+Platform-specific `#if` directives (like `#if WINDOWS`, `#if ANDROID`, `#if IOS`, `#if MACCATALYST`) must be wrapped with `//-:cnd:noEmit` and `//+:cnd:noEmit` markers:
+
+```csharp
+//-:cnd:noEmit
+#if WINDOWS
+    // Windows-specific code
+#endif
+//+:cnd:noEmit
+```
+
+**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.
+
+**Examples:**
+```csharp
+//-:cnd:noEmit
+#if DEBUG
+    builder.Logging.AddDebug();
+#endif
+//+:cnd:noEmit
+
+//-:cnd:noEmit
+#if IOS || MACCATALYST
+    handlers.AddHandler<CollectionView, CollectionViewHandler2>();
+#endif
+//+:cnd:noEmit
+
+//-:cnd:noEmit
+#if WINDOWS
+    Microsoft.Maui.Controls.Handlers.Items.CollectionViewHandler.Mapper.AppendToMapping(
+        "KeyboardAccessibleCollectionView", 
+        (handler, view) => { /* ... */ });
+#endif
+//+:cnd:noEmit
+```
+
+#### Template Parameter Directives (Template-Time)
+
+Template parameter directives (like `#if (IncludeSampleContent)`) do NOT use the `//-:cnd:noEmit` markers:
+
+```csharp
+#if (IncludeSampleContent)
+using CommunityToolkit.Maui;
+#endif
+```
+
+**Why?** These directives are evaluated when the template is instantiated (when user runs `dotnet new maui`), not when the code is compiled.
+
+### Template Naming Conventions
+
+- Template project names use placeholders like `MauiApp._1` which get replaced with the user's actual project name
+- Namespaces follow the same pattern: `namespace MauiApp._1;`
+- These will be transformed to the user's chosen project name during template instantiation
+
+### Files to Exclude from Template Changes
+
+Never modify auto-generated files in templates:
+- `cgmanifest.json` - Auto-generated component governance manifest
+- `templatestrings.json` - Auto-generated localization file
+
+These files are regenerated during the build process and should not be manually edited.
+
+### Template Testing
+
+When making changes to templates:
+1. Build the template project: `dotnet build src/Templates/src/Microsoft.Maui.Templates.csproj`
+2. For comprehensive testing, use the `build.ps1` script in the Templates directory to pack, install, and test the template
+3. Verify the generated project compiles for all target platforms
+
+### Quick Reference
+
+| Directive Type | Wrapper Needed | Example |
+|---|---|---|
+| Platform-specific (`#if WINDOWS`, `#if ANDROID`, etc.) | ✅ Yes - use `//-:cnd:noEmit` | Build-time platform detection |
+| Debug mode (`#if DEBUG`) | ✅ Yes - use `//-:cnd:noEmit` | Build configuration |
+| Template parameters (`#if (IncludeSampleContent)`) | ❌ No | Template instantiation options |
+
 ## Additional Resources
 
 - [Development Guide](.github/DEVELOPMENT.md)
diff --git a/src/Templates/src/templates/maui-mobile/MauiProgram.cs b/src/Templates/src/templates/maui-mobile/MauiProgram.cs
@@ -21,6 +21,7 @@ public static MauiApp CreateMauiApp()
 #endif
 			.ConfigureMauiHandlers(handlers =>
 			{
+//-:cnd:noEmit
 #if WINDOWS
 				Microsoft.Maui.Controls.Handlers.Items.CollectionViewHandler.Mapper.AppendToMapping("KeyboardAccessibleCollectionView", (handler, view) =>
 				{
@@ -35,6 +36,7 @@ public static MauiApp CreateMauiApp()
                 	}
             	});
 #endif
+//+:cnd:noEmit
 //-:cnd:noEmit
 #if IOS || MACCATALYST
 				handlers.AddHandler<Microsoft.Maui.Controls.CollectionView, Microsoft.Maui.Controls.Handlers.Items2.CollectionViewHandler2>();

Original file line number	Diff line number	Diff line change
`@@ -21,6 +21,7 @@ public static MauiApp CreateMauiApp()`
`21`	`21`	`#endif`
`22`	`22`	`.ConfigureMauiHandlers(handlers =>`
`23`	`23`	`{`
	`24`	`+//-:cnd:noEmit`
`24`	`25`	`#if WINDOWS`
`25`	`26`	`Microsoft.Maui.Controls.Handlers.Items.CollectionViewHandler.Mapper.AppendToMapping("KeyboardAccessibleCollectionView", (handler, view) =>`
`26`	`27`	`{`
`@@ -35,6 +36,7 @@ public static MauiApp CreateMauiApp()`
`35`	`36`	`}`
`36`	`37`	`});`
`37`	`38`	`#endif`
	`39`	`+//+:cnd:noEmit`
`38`	`40`	`//-:cnd:noEmit`
`39`	`41`	`#if IOS \|\| MACCATALYST`
`40`	`42`	`handlers.AddHandler<Microsoft.Maui.Controls.CollectionView, Microsoft.Maui.Controls.Handlers.Items2.CollectionViewHandler2>();`