Hot Reload: document HOTRELOAD_XAML_LOG_MESSAGES env var and UTF-8 BOM file encoding requirement

[PureWeen]

Summary

Two critical Hot Reload diagnostic details are absent from official documentation:

1. HOTRELOAD_XAML_LOG_MESSAGES environment variable — enables verbose XAML Hot Reload logging. This is the first thing to set when diagnosing silent XAML hot reload failures, but it doesn't appear in any official docs.
2. UTF-8 with BOM encoding requirement — all .cs files must be saved with UTF-8 BOM encoding for XAML Hot Reload to work. Files without BOM cause silent hot reload failures with no error message.

Why it matters

Both of these are the most common reasons Hot Reload "just doesn't work" with no visible error. Without knowing about the env var, developers have no way to get diagnostic output. Without knowing about the BOM requirement, they spend hours debugging a file encoding issue that doesn't surface in any build output.

These issues affect all IDEs (Visual Studio, VS Code, Rider) and are especially common when:

• Files are created via terminal (touch, cat, or non-BOM editors)
• Code is copied from Linux/macOS environments where UTF-8 without BOM is the default
• Projects are cloned and modified on machines with different editor defaults

What should be documented

1. Document HOTRELOAD_XAML_LOG_MESSAGES

Add to the hot reload troubleshooting docs:

# Enable XAML Hot Reload verbose logging
# macOS/Linux:
export HOTRELOAD_XAML_LOG_MESSAGES=1

# Windows (Command Prompt):
set HOTRELOAD_XAML_LOG_MESSAGES=1

# Windows (PowerShell):
$env:HOTRELOAD_XAML_LOG_MESSAGES=1

Also document Microsoft_CodeAnalysis_EditAndContinue_LogDir for C# Hot Reload:

# macOS/Linux:
export Microsoft_CodeAnalysis_EditAndContinue_LogDir=/tmp/HotReloadLog

# Windows:
set Microsoft_CodeAnalysis_EditAndContinue_LogDir=%temp%\HotReloadLog

2. Document the UTF-8 BOM requirement

Add a prominent note:

File encoding requirement: All .cs files must be saved with UTF-8 with BOM encoding. Files encoded as UTF-8 without BOM (common on Linux/macOS) will cause XAML Hot Reload to silently fail with no error message.

Check encoding:

# macOS/Linux — should show "UTF-8 Unicode (with BOM)"
file -I YourFile.cs

# Find all .cs files missing BOM:
find . -name "*.cs" -exec sh -c 'head -c 3 "$1" | od -An -tx1 | grep -q "ef bb bf" || echo "Missing BOM: $1"' _ {} \;

Fix in VS Code: Open file → bottom-right encoding selector → "Save with Encoding" → "UTF-8 with BOM"

3. Add a quick-start checklist

A checklist of the most common silent-failure causes:

• Running in Debug configuration with debugger attached
• File saved after changes
• .cs files are UTF-8 with BOM
• HOTRELOAD_XAML_LOG_MESSAGES=1 set to see XAML reload diagnostic output
• Hot Reload output panel open (View > Output > Hot Reload in Visual Studio)

Suggested location

Existing hot reload page (e.g., docs/fundamentals/hot-reload.md) or a new troubleshooting sub-page. A dedicated troubleshooting section with the checklist and environment variable reference would be most useful.