Skip to content

Commit a2fe61d

Browse files
jeromelabanjeromelaban
authored
Merge pull request #19351 from unoplatform/dev/jela/bp19250
docs: Update Hot Reload documentation based on latest changes (bp #19250)
2 parents 8bcbb73 + 77b2f81 commit a2fe61d

File tree

2 files changed

+128
-112
lines changed

2 files changed

+128
-112
lines changed

‎doc/articles/Assets/features/hotreload/hot-reload-button.png

1.49 KB
Loading

‎doc/articles/features/working-with-xaml-hot-reload.md

Lines changed: 128 additions & 112 deletions
Original file line numberDiff line numberDiff line change
@@ -12,11 +12,11 @@ The Uno Platform **Hot Reload** feature provides a way to modify the XAML and C#
1212

1313
## Features
1414

15-
- Supported in **Visual Studio 2022** (Windows), **VS Code** (Linux, macOS, Windows, CodeSpaces, and GitPod) and **Rider** (Linux, macOS, Windows)
16-
- XAML and [C# Markup](xref:Uno.Extensions.Markup.Overview) Hot Reload for **iOS, Catalyst, Android, WebAssembly, and Skia (X11, Windows, macOS and FrameBuffer)**
17-
- All **[C# of Hot Reload](https://learn.microsoft.com/visualstudio/debugger/hot-reload)** in both Visual Studio and VS Code. See [supported code changes](https://learn.microsoft.com/visualstudio/debugger/supported-code-changes-csharp).
18-
- **Simulator and physical devices** support
19-
- **Hot Reload Indicator** visuals for an enhanced development experience on Uno Platform targets (not currently supported on WinAppSDK target)
15+
- Supported in **Visual Studio 2022** (Windows), **VS Code** (Linux, macOS, Windows, CodeSpaces, and GitPod) and **Rider** (Linux, macOS, Windows).
16+
- XAML and [C# Markup](xref:Uno.Extensions.Markup.Overview) Hot Reload for **iOS, Catalyst, Android, WebAssembly, and Skia (X11, Windows, macOS and FrameBuffer)**.
17+
- All **[C# of Hot Reload](https://learn.microsoft.com/visualstudio/debugger/hot-reload)** in both Visual Studio, VS Code and Rider. See [supported code changes](https://learn.microsoft.com/visualstudio/debugger/supported-code-changes-csharp).
18+
- **Simulator and physical devices** support.
19+
- **Hot Reload Indicator** visuals for an enhanced development experience on Uno Platform targets (not currently supported on WinAppSDK target).
2020
- What can be Hot Reloaded:
2121
- **XAML files** in the **main project** and **referenced projects libraries**
2222
- **C# Markup controls**
@@ -26,31 +26,33 @@ The Uno Platform **Hot Reload** feature provides a way to modify the XAML and C#
2626
- **DataTemplates**
2727
- **Styles**
2828
- Extensible [**State restoration**](xref:Uno.Contributing.Internals.HotReload)
29-
- Support for partial **tree hot reload**, where modifying a `UserControl` instantiated in multiple locations will reload it without reloading its parents
29+
- Support for partial **tree hot reload**, where modifying a `UserControl` instantiated in multiple locations will reload it without reloading its parents.
3030

31-
Hot Reload features vary between platforms and IDE, you can check below the list of currently supported features.
31+
Hot Reload features are now consistent across platforms and IDEs, but with some debugger-specific variations. You can check below the list of currently supported features.
3232

3333
## How to use Hot Reload
3434

3535
### [**Visual Studio 2022**](#tab/vswin)
3636

3737
- Setup your environment by following our [getting started guides](xref:Uno.GetStarted.vs2022).
38-
- Start your application (with or without the debugger, depending on the supported features below)
39-
- Make changes to your XAML or C# code, save your file then press the red flame icon in the toolbar or use `Alt+F10`
40-
38+
- Start your application (with or without the debugger, depending on the supported features below).
39+
- Make changes to your XAML or C# code, save your file then press the red flame button in the toolbar or use `Alt+F10`.
40+
41+
![Hot Reload button](../Assets/features/hotreload/hot-reload-button.png)
42+
4143
### [**Visual Studio Code**](#tab/vscode)
4244

43-
- Setup your environment by following our [getting started guide](xref:Uno.GetStarted.vscode)
44-
- Start the application (with or without the debugger, depending on the supported features below)
45-
- Wait a few seconds for the hot reload engine to become available (see our troubleshooting tips below)
46-
- Make changes to your XAML or C# code, then save your file
45+
- Setup your environment by following our [getting started guide](xref:Uno.GetStarted.vscode).
46+
- Start the application without the debugger.
47+
- Wait a few seconds for the hot reload engine to become available (see our troubleshooting tips below).
48+
- Make changes to your XAML or C# code, then save your file.
4749

4850
### [**Rider**](#tab/rider)
4951

50-
- Setup your environment by following our [getting started guide](xref:Uno.GetStarted.Rider)
51-
- Start the application without the debugger
52-
- Wait a few seconds for the hot reload engine to become available (see our troubleshooting tips below)
53-
- Make changes to your XAML or C# code, then save your file
52+
- Setup your environment by following our [getting started guide](xref:Uno.GetStarted.Rider).
53+
- Start the application without the debugger.
54+
- Wait a few seconds for the hot reload engine to become available (see our troubleshooting tips below).
55+
- Make changes to your XAML or C# code, then save your file.
5456

5557
---
5658

@@ -70,57 +72,57 @@ Hot Reload features vary between platforms and IDE, you can check below the list
7072
<th colspan="2">Rider</th>
7173
</tr>
7274
<tr>
73-
<th>Target</th>
74-
<th>C#</th>
75-
<th>XAML</th>
76-
<th>C#</th>
77-
<th>XAML</th>
78-
<th>C#</th>
79-
<th>XAML</th>
75+
<th>🐞 Debugger</th>
76+
<th>With</th>
77+
<th>Without</th>
78+
<th>With</th>
79+
<th>Without</th>
80+
<th>With</th>
81+
<th>Without</th>
8082
</tr>
8183
</thead>
8284
<tbody>
8385
<tr>
84-
<td>Desktop Windows</td>
85-
<td>✅🐞</td><td>✅🐞</td>
86-
<td>✅🐞</td><td>✅🐞</td>
86+
<td>Desktop<br /><small><code>net9.0-desktop</code></code></small></td>
8787
<td>✅</td><td>✅</td>
88+
<td>🔳</td><td>✅</td>
89+
<td>🔳</td><td>✅</td>
8890
</tr>
8991
<tr>
90-
<td>Desktop/WSL</td>
91-
<td>⌛<sup><a href="#hr-footnotes">[1]</a></sup> </td><td>⌛<sup><a href="#hr-footnotes">[1]</a></sup></td>
92-
<td>✅</td><td>✅</td>
92+
<td>Desktop - WSL<br /><small><code>net9.0-desktop</code></small></td>
93+
<td>⌛<sup><a href="#hr-footnotes">[1]</a></sup></td><td>⌛<sup><a href="#hr-footnotes">[1]</a></sup></td>
94+
<td>🔳</td><td>✅</td>
9395
<td>🔳<sup><a href="#hr-footnotes">[2]</a></sup></td><td>🔳<sup><a href="#hr-footnotes">[2]</a></sup></td>
9496
</tr>
9597
<tr>
96-
<td>iOS</td>
97-
<td>⌛<sup><a href="#hr-footnotes">[3]</a></sup></td><td>✅<sup><a href="#hr-footnotes">[4]</a></sup></td>
98-
<td>⌛<sup><a href="#hr-footnotes">[3]</a></sup>🛜</td><td>✅<sup><a href="#hr-footnotes">[4]</a></sup>🛜</td>
99-
<td>🔳</td><td>🔳</td>
98+
<td>iOS<br /><small><code>net9.0-ios</code></small></td>
99+
<td>✅</a></sup></td><td>🔳</td>
100+
<td>🟥</a></td><td>✅🛜</td>
101+
<td>🔳</a></td><td>✅</td>
100102
</tr>
101103
<tr>
102-
<td>Android</td>
103-
<td>⌛<sup><a href="#hr-footnotes">[3]</a></sup></td><td>✅<sup><a href="#hr-footnotes">[4]</a></sup></td>
104-
<td>⌛<sup><a href="#hr-footnotes">[3]</a></sup></td><td>✅<sup><a href="#hr-footnotes">[4]</a></sup></td>
105-
<td>⌛<sup><a href="#hr-footnotes">[3]</a></sup></td><td>✅<sup><a href="#hr-footnotes">[4]</a></sup></td>
104+
<td>Android<br /><small><code>net9.0-android</code></small></td>
105+
<td>✅</td><td>🔳</td>
106+
<td>🟥</a></td><td>✅</td>
107+
<td>🔳</a></td><td>✅</td>
106108
</tr>
107109
</tr>
108110
<tr>
109-
<td>WinAppSDK</td>
110-
<td>✅<sup><a href="#hr-footnotes">[5]</a></sup>🐞</td><td>✅🐞</td>
111+
<td>WinAppSDK<br /><small><code>net9.0-windows10.x.x</code></small></td>
112+
<td>✅<sup><a href="#hr-footnotes">[3]</a></sup></td><td>✅<sup><a href="#hr-footnotes">[4]</a></sup></td>
111113
<td>🔳</td><td>🔳</td>
112114
<td>🔳</td><td>🔳</td>
113115
</tr>
114116
<tr>
115-
<td>WebAssembly</td>
116-
<td>✅🐞</td><td>✅🐞</td>
117-
<td>✅</td><td>✅</td>
117+
<td>WebAssembly<br /><small><code>net9.0-browserwasm</code></small></td>
118118
<td>✅</td><td>✅</td>
119+
<td>🔳</td><td>✅</td>
120+
<td>🔳</td><td>✅</td>
119121
</tr>
120122
<tr>
121-
<td>Catalyst</td>
123+
<td>Catalyst<br /><small><code>net9.0-maccatalyst</code></small></td>
122124
<td>🔳</td><td>🔳</td>
123-
<td>⌛<sup><a href="#hr-footnotes">[3]</a></sup>🛜</td><td>✅<sup><a href="#hr-footnotes">[4]</a></sup>🛜</td>
125+
<td>🔳</td><td>✅🛜</td>
124126
<td>🔳</td><td>🔳</td>
125127
</tr>
126128
</tbody>
@@ -136,44 +138,48 @@ Hot Reload features vary between platforms and IDE, you can check below the list
136138
<th colspan="2">Rider</th>
137139
</tr>
138140
<tr>
139-
<th>Target</th>
140-
<th>C#</th>
141-
<th>XAML</th>
142-
<th>C#</th>
143-
<th>XAML</th>
141+
<th>🐞 Debugger</th>
142+
<th>With</th>
143+
<th>Without</th>
144+
<th>With</th>
145+
<th>Without</th>
144146
</tr>
145147
</thead>
146148
<tbody>
147149
<tr>
148-
<td>Desktop macOS</td>
149-
<td>✅</td><td>✅</td>
150-
<td>✅</td><td>✅</td>
150+
<td>Desktop<br /><small><code>net9.0-desktop</code></code></small></td>
151+
<td>🔳</td><td>✅</td>
152+
<td>🔳</td><td>✅</td>
151153
</tr>
152154
<tr>
153-
<td>iOS</td>
154-
<td>⌛<sup><a href="#hr-footnotes">[3]</a></sup></td><td>✅<sup><a href="#hr-footnotes">[4]</a></sup></td>
155-
<td>⌛<sup><a href="#hr-footnotes">[3]</a></sup></td><td>✅<sup><a href="#hr-footnotes">[4]</a></sup></td>
155+
<td>Desktop - WSL<br /><small><code>net9.0-desktop</code></small></td>
156+
<td>🔳</td><td>🔳</td>
157+
<td>🔳</td><td>🔳</td>
156158
</tr>
157159
<tr>
158-
<td>Android</td>
159-
<td>⌛<sup><a href="#hr-footnotes">[3]</a></sup></td><td>✅<sup><a href="#hr-footnotes">[4]</a></sup></td>
160-
<td>⌛<sup><a href="#hr-footnotes">[3]</a></sup></td><td>✅<sup><a href="#hr-footnotes">[4]</a></sup></td>
161-
</tr>
160+
<td>iOS<br /><small><code>net9.0-ios</code></small></td>
161+
<td>🟥</td><td>✅</td>
162+
<td>🔳</td><td>✅</td>
162163
</tr>
163164
<tr>
164-
<td>Catalyst</td>
165-
<td>⌛<sup><a href="#hr-footnotes">[3]</a></sup></td><td>✅<sup><a href="#hr-footnotes">[4]</a></sup></td>
166-
<td>⌛<sup><a href="#hr-footnotes">[3]</a></sup></td><td>✅<sup><a href="#hr-footnotes">[4]</a></sup></td>
165+
<td>Android<br /><small><code>net9.0-android</code></small></td>
166+
<td>🟥</td><td>✅</td>
167+
<td>🔳</td><td>✅</td>
167168
</tr>
168169
<tr>
169-
<td>WinAppSDK</td>
170+
<td>WinAppSDK<br /><small><code>net9.0-windows10.x.x</code></small></td>
170171
<td>🔳</td><td>🔳</td>
171172
<td>🔳</td><td>🔳</td>
172173
</tr>
173174
<tr>
174-
<td>WebAssembly</td>
175-
<td>✅</td><td>✅</td>
176-
<td>✅</td><td>✅</td>
175+
<td>WebAssembly<br /><small><code>net9.0-browserwasm</code></small></td>
176+
<td>🔳</td><td>✅</td>
177+
<td>🔳</td><td>✅</td>
178+
</tr>
179+
<tr>
180+
<td>Catalyst<br /><small><code>net9.0-maccatalyst</code></small></td>
181+
<td>🔳</td><td>✅</td>
182+
<td>🔳</td><td>✅</td>
177183
</tr>
178184
</tbody>
179185
</table>
@@ -188,42 +194,47 @@ Hot Reload features vary between platforms and IDE, you can check below the list
188194
<th colspan="2">Rider</th>
189195
</tr>
190196
<tr>
191-
<th>Target</th>
192-
<th>C#</th>
193-
<th>XAML</th>
194-
<th>C#</th>
195-
<th>XAML</th>
197+
<th>🐞 Debugger</th>
198+
<th>With</th>
199+
<th>Without</th>
200+
<th>With</th>
201+
<th>Without</th>
196202
</tr>
197203
</thead>
198204
<tbody>
199205
<tr>
200-
<td>Desktop Linux</td>
201-
<td>✅</td><td>✅</td>
202-
<td>✅</td><td>✅</td>
206+
<td>Desktop<br /><small><code>net9.0-desktop</code></code></small></td>
207+
<td>🔳</td><td>✅</td>
208+
<td>🔳</td><td>✅</td>
203209
</tr>
204210
<tr>
205-
<td>Android</td>
206-
<td>⌛<sup><a href="#hr-footnotes">[3]</a></sup></td><td>✅<sup><a href="#hr-footnotes">[4]</a></sup></td>
207-
<td>⌛<sup><a href="#hr-footnotes">[3]</a></sup></td><td>✅<sup><a href="#hr-footnotes">[4]</a></sup></td>
211+
<td>Desktop - WSL<br /><small><code>net9.0-desktop</code></small></td>
212+
<td>🔳</td><td>🔳</td>
213+
<td>🔳</td><td>🔳</td>
208214
</tr>
209215
<tr>
210-
<td>WebAssembly</td>
211-
<td>✅</td><td>✅</td>
212-
<td>✅</td><td>✅</td>
216+
<td>iOS<br /><small><code>net9.0-ios</code></small></td>
217+
<td>🟥</td><td>✅🛜</td>
218+
<td>🔳</td><td>🔳</td>
213219
</tr>
214220
<tr>
215-
<td>iOS</td>
216-
<td>⌛<sup><a href="#hr-footnotes">[3]</a></sup>🛜</td><td>✅<sup><a href="#hr-footnotes">[4]</a></sup>🛜</td>
217-
<td>🔳</td><td>🔳</td>
221+
<td>Android<br /><small><code>net9.0-android</code></small></td>
222+
<td>🟥</td><td>✅</td>
223+
<td>🔳</td><td>✅</td>
218224
</tr>
219225
<tr>
220-
<td>Catalyst</td>
221-
<td>⌛<sup><a href="#hr-footnotes">[3]</a></sup>🛜</td><td>✅<sup><a href="#hr-footnotes">[4]</a></sup>🛜</td>
226+
<td>WinAppSDK<br /><small><code>net9.0-windows10.x.x</code></small></td>
227+
<td>🔳</td><td>🔳</td>
222228
<td>🔳</td><td>🔳</td>
223229
</tr>
224230
<tr>
225-
<td>WinAppSDK</td>
226-
<td>🔳</td><td>🔳</td>
231+
<td>WebAssembly<br /><small><code>net9.0-browserwasm</code></small></td>
232+
<td>🔳</td><td>✅</td>
233+
<td>🔳</td><td>✅</td>
234+
</tr>
235+
<tr>
236+
<td>Catalyst<br /><small><code>net9.0-maccatalyst</code></small></td>
237+
<td>🔳</td><td>✅🛜</td>
227238
<td>🔳</td><td>🔳</td>
228239
</tr>
229240
</tbody>
@@ -234,9 +245,9 @@ Hot Reload features vary between platforms and IDE, you can check below the list
234245
Legend:
235246

236247
- ✅ Supported
237-
- 🐞 Supported with the debugger
238-
- ⌛ Upcoming support
239248
- 🛜 Supported through [SSH to a Mac](xref:Uno.GettingStarted.CreateAnApp.VSCode#debug-the-app)
249+
- ⌛ Upcoming support
250+
- 🟥 Not supported yet
240251
- 🔳 Not supported by the environment/IDE
241252

242253
### Notes
@@ -245,9 +256,8 @@ Legend:
245256

246257
- [1]: Support is [pending support](https://github.com/dotnet/sdk/pull/40725) in the .NET SDK.
247258
- [2]: Support is [not available](https://youtrack.jetbrains.com/issue/RIDER-53302/launchSettings.json-WSL2-command-support).
248-
- [3]: C# Hot Reload is affected by a [.NET Runtime issue](https://github.com/dotnet/android/issues/9120).
249-
- [4]: XAML Hot Reload is using the XAML Reader, [pending C# Hot Reload update](https://github.com/unoplatform/uno/issues/15918) and a [VS/VS Code update](https://developercommunity.visualstudio.com/t/net70-iosnet70-android-MetadataUpd/10279604).
250-
- [5]: C# Markup Hot Reload is supported when running in Unpackaged mode only
259+
- [3]: Unpackaged: C# & XAML / Packaged: XAML only
260+
- [4]: Unpackaged: C# / Packaged: none
251261

252262
## Supported features per Platform
253263

@@ -259,39 +269,45 @@ Skia-based targets provide support for full XAML Hot Reload and C# Hot Reload. T
259269
- As of VS 2022 17.9 XAML or C# Hot Reload under WSL is not supported
260270
- VS Code
261271
- With the debugger: The C# Dev Kit is handling hot reload [when enabled](https://code.visualstudio.com/docs/csharp/debugging#_hot-reload). As of December 20th, 2023, C# Dev Kit hot reload does not handle class libraries. To experience the best hot reload, do not use the debugger.
262-
- Without the debugger: The VS Code Uno Platform extension is handling Hot Reload (C# or XAML)
263-
- Adding new C# or XAML files to a project is not yet supported
272+
- Without the debugger: The VS Code Uno Platform extension is handling Hot Reload (C# and XAML).
273+
- Adding new C# or XAML files to a project is not yet supported.
264274
- Rider
265275
- Hot Reload is only supported without the debugger.
266-
- Adding new C# or XAML files to a project is not yet supported
276+
- Adding new C# or XAML files to a project is not yet supported.
267277

268278
### [**WebAssembly**](#tab/wasm)
269279

270-
WebAssembly is currently providing both full and partial Hot Reload support, depending on the IDE.
280+
WebAssembly is currently providing full Hot Reload support.
271281

272282
- In Visual Studio Code:
273-
- Both C# and XAML Hot Reload are fully supported
274-
- Adding new C# or XAML files to the project is not yet supported
275-
- Hot Reload is not supported when using the debugger
283+
- Both C# and XAML Hot Reload are fully supported.
284+
- Adding new C# or XAML files to the project is not yet supported.
285+
- Hot Reload is not supported when using the debugger.
276286
- In Rider:
277-
- Both C# and XAML Hot Reload are fully supported
278-
- Adding new C# or XAML files to the project is not yet supported
279-
- Hot Reload is not supported when using the debugger
280-
- In Visual Studio for Windows:
281-
- [`MetadataUpdateHandlers`](https://learn.microsoft.com/dotnet/api/system.reflection.metadata.metadataupdatehandlerattribute) are invoked without the list of changed types, which means that some hot reload features may not be available. This feature is slated to be available for .NET 9.
287+
- Both C# and XAML Hot Reload are fully supported.
288+
- Adding new C# or XAML files to the project is not yet supported.
289+
- Hot Reload is not supported when using the debugger.
290+
291+
### [**iOS, Android**](#tab/mobile)
292+
293+
Mobile targets now support both XAML and C# Hot Reload. Debugger-specific variations apply depending on the IDE.
294+
295+
- In Visual Studio:
296+
- The debugger **has** to be attached.
297+
- In VS Code, and Rider:
298+
- Hot Reload is not supported when using the debugger.
299+
- XAML `x:Bind` Hot Reload is limited to simple expressions and events.
282300

283-
### [**iOS, Android, and Catalyst**](#tab/mobile)
301+
### [**Catalyst**](#tab/catalyst)
284302

285-
Mobile targets are currently using a limited version of XAML Hot Reload and do not support C# Hot Reload until [this dotnet runtime](https://github.com/dotnet/android/issues/9120) issue is fixed.
303+
Mobile targets now support both XAML and C# Hot Reload.
286304

287-
- In Visual Studio, the "Hot Reload on File Save" feature must be disabled to avoid crashing the app. You can find this feature by clicking on the down arrow next to the red flame in the Visual Studio toolbar.
288-
- In VS, VS Code, and Rider, [C# Hot Reload is not yet fully supported](https://developercommunity.visualstudio.com/t/net70-iosnet70-android-MetadataUpd/10279604#T-ND10384434)
289-
- XAML `x:Bind` hot reload is limited to simple expressions and events
305+
- XAML `x:Bind` hot reload is limited to simple expressions and events.
290306

291307
### [**WinAppSDK**](#tab/winappsdk)
292308

293309
- Hot Reload is supported by Visual Studio for WinAppSDK and provides support in unpackaged deployment mode.
294-
- Hot Reload is not supported in Rider
310+
- Hot Reload is not supported in VS Code and Rider.
295311

296312
---
297313

0 commit comments

Comments
 (0)