Starting from Uno 4.8.26, the Uno Platform solution templates contains the appropriate support to debug Mobile applications. See below for adjusting projects.
## Supported Features
### SourceLink and Sources embedded inside PDB
Both [Source Link](https://github.com/dotnet/designs/blob/main/accepted/2020/diagnostics/source-link.md) and "Sources embedded inside PDB" features are used by Uno Platform and are supported by the extension.
However only Android includes the `.pdb` of the referenced assemblies inside debug builds for net6.0. This makes the features unusable for iOS, macOS and MacCatalyst, see [issue](https://github.com/xamarin/xamarin-macios/issues/11879#issuecomment-1279452073).
This situation [should be](https://github.com/dotnet/sdk/issues/1458#issuecomment-1244736464) fixed with net7.0. A workaround for net6 mobile projects is to install [Cymbal](https://github.com/SimonCropp/Cymbal).
### Remote SSH
VS Code can [connect to a remote computer](https://code.visualstudio.com/docs/remote/ssh)(using`ssh`) to develop and debug projects. Note that all the sources, build and debugging are done on the remote computer, where the Uno Platform extension is being executed.
### Logpoints
[Logpoints](https://code.visualstudio.com/blogs/2018/07/12/introducing-logpoints-and-auto-attach#_introducing-logpoints) are functionally similar to adding `Console.WriteLine` but without modifying the sources.
## Converting existing projects
Existing Uno Platform projects requires a few simple changes to work properly with multiples TargetFrameworks inside VS Code.
### launch.json
You can add a default entry for all mobile targets by adding the following JSON block inside your `launch.json`.
This will ask the `Uno` debug provider how to build and launch the application. The Target Framework Moniker (TFM) selected in VS Code's status bar, e.g. `net7.0-ios`, and the target platform, e.g. `iossimulator-x64`, will be used automatically.
> [!NOTE]
> Uno Platform's [templates](https://www.nuget.org/packages/uno.templates/) already include this change.
## Debugging with the Windows Subsystem for Android
You first need to [connect](https://learn.microsoft.com/en-us/windows/android/wsa/#connect-to-the-windows-subsystem-for-android-for-debugging) to the Windows Subsystem for Android (WSA) in order to use it for debugging. From the command-line type:
```bash
adb connect 127.0.0.1:58526
```
and you should then be able to see the WSA device inside VSCode. You can also confirm it's connected from the command-line:
You can choose to break execution on specific exceptions, either always or if the exception is unhandled.
Note: Those settings do not apply when debugging Windows (WinUI) or macOS (AppKit) application since it use the CoreCLR debugger.
### Unoplatform › Debugger › Ios › Mlaunch: Extra Arguments
For example you can add `-vvvvv` to get more verbosity from `mlaunch`.
This can be useful if you run into issues deploying your application to an iOS device.
### Unoplatform › Debugger › Ios › Mlaunch: Path
By default the version of `mlaunch` associated with the currently iOS workload will be used to launch application to iOS devices.
You can override the path to the `mlaunch` tool to be used. For example you could set the path to `/Library/Frameworks/Xamarin.iOS.framework/Versions/Current/bin/mlaunch` to use the version from the legacy (pre-net6.0) Xamarin.iOS SDK.
This can be useful when a new Xcode is released, requiring an update to `mlaunch`, while allowing you to use the current stable SDK version for development.
### Unoplatform › Debugger › Ios › Simulator: X64
By default the simulators are listed for both `arm64` and `x64` on Apple Silicon Macs.
`x64` simulators are provided using Rosetta emulation and is required if `arm64` support is missing for some dependencies (e.g. SkiaSharp).
This can be useful if your project has dependencies that are not available yet for the `arm64` architecture.
## Environment Variables
### Xcode override
The Uno extension uses `xcrun` to find the active Xcode version to use. You can override this version of Xcode by setting the `DEVELOPER_DIR` environment variable. More information can be found running `man xcrun` inside the terminal.
## Advanced Debugger Configuration
It is possible to create advanced `launch.json` and `tasks.json` entries if additional customization is needed for a project.
### Editing `launch.json`
The extension provides default launch configurations for supported platforms, without the need to define them inside the `launch.json` file.
If you need to define launches or modify the defaults then you can can create your own.
1. Press the `Shift+Cmd+P` keys to open the **Command Palette**
1. Select the `Debug: Select and Start Debugging` item
1. Select the `Add Configuration...` item
1. Select `.NET Custom Launch Configuration for Uno Platform` item
1. This will insert a JSON block that looks like the following:
```json
{
"comment1":"// name: unique name for the configuration, can be identical to preLaunchTask",
If you follow the `Uno: {tfm} | {config}[ | {rid]}]` convention then there is no need to add entries inside the `tasks.json` file, the extension already provides them.
### Customizing tasks.json
The extension provides default build tasks for most platforms without the need to define them inside the `tasks.json` file.
If you need to define tasks or something that the defaut, built-in tasks do not provide you can create your own.
1. Press the `Shift+Cmd+P` keys to open the **Command Palette**
1. Select the `Tasks: Configure Tasks` item
1. Pick the `Uno: *` task that is the closed to your need
1. Edit the `args` section but avoid changing the other values (beside the `label`) to keep automation working
See [VS Code documentation](https://code.visualstudio.com/docs/editor/tasks) for more information.
* Most of the build settings should be done (or changed) inside the `.csproj` file. This way only a simple `dotnet build` is needed to create the applications.
* The easiest way to create a custom task is to look at the build logs and see what is normally provided, by default, to build for a specific target platform.
* You will also need a custom launch target that will use the `label` name for it's `preLaunchTask`.
@@ -25,17 +25,24 @@ See these sections for information about using Uno Platform with:
### Create the project
In the terminal, type the following to create a new project:
Let's start by updating the Uno project templates. In a terminal, type the following command:
```bash
dotnet new unoapp -o MyApp -mobile=false--skia-wpf=false--skia-linux-fb=false--vscode
dotnet new install Uno.Templates
```
Then inside the same terminal, type the following to create a new project:
```bash
dotnet new unoapp -o MyApp --skia-wpf=false--skia-linux-fb=false--vscode
```
> [!TIP]
> `MyApp` is the name you want to give to your project.
This will create a solution that only contains the WebAssembly and Skia+GTK platforms support.
This will create a solution that only contains the WebAssembly, Skia+GTK and Mobile platforms support.
## Prepare the WebAssembly application
## Prepare the application
1. Open the project using Visual Studio Code. In the terminal type
...
...
@@ -46,7 +53,7 @@ This will create a solution that only contains the WebAssembly and Skia+GTK plat
> For this command to work you need to previously have configured Visual Studio Code to be launched from the terminal.
1. Visual Studio Code will ask to restore the NuGet packages.
1. Once the project has been loaded, in the status bar at the bottom left of VS Code, `MyApp.sln` is selected by default. Select `MyApp.Wasm.csproj` or `MyApp.Skia.Gtk.csproj` instead.
1. Once the project has been loaded, in the status bar at the bottom left of VS Code, `MyApp.sln` is selected by default. Select `MyApp.Wasm.csproj`, `MyApp.Skia.Gtk.csproj` or `MyApp.Mobile.csproj` instead.
## Modify the template
...
...
@@ -76,29 +83,97 @@ This will create a solution that only contains the WebAssembly and Skia+GTK plat
## Run and Debug application
### WebAssembly
1. In the debugger section of the Code activity bar, select `Debug (Chrome, WebAssembly)`
1. In the debugger section of the Code activity bar
* Select `Debug (Chrome, WebAssembly)`
* If needed, the project from `MyApp.sln` to `MyApp.Wasm.csproj`
1. Press `F5` to start the debugging session
1. Place a breakpoint inside the `OnClick` method
1. Click the button in the app, and the breakpoint will hit
### Skia GTK
1. In the debugger section of the Code activity bar, select `Skia.GTK (Debug)`
1. In the debugger section of the Code activity bar
1. Select `Skia.GTK (Debug)`
1. If needed, the project from `MyApp.sln` to `MyApp.Skia.Gtk.csproj`
1. Press `F5` to start the debugging session
1. Place a breakpoint inside the `OnClick` method
1. Click the button in the app, and the breakpoint will hit
Note that C# Hot Reload is not available when running with the debugger. In order to use C# Hot Reload, run the app using the following:
- On Windows, type the following:
```
```bash
$env:DOTNET_MODIFIABLE_ASSEMBLIES="debug"
dotnet run
```
- On Linux or macOS:
```
```bash
export DOTNET_MODIFIABLE_ASSEMBLIES=debug
dotnet run
```
### Mobile Targets (iOS, Android, Mac Catalyst)
The Uno Platform extension provides support for debugging:
- The Android target on Windows
- The iOS, Android and Mac Catalyst targets on macOS
It is also possible to use [Remote - SSH](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-ssh) addin to connect to a macOS machine from a Windows or Linux machine to debug iOS and Mac Catalyst apps remotely.
# [**Android**](#tab/android-debug)
#### Debugging for Android
- In the status bar, select the `MyApp.Mobile` project (by default `MyApp.sln` is selected)
- Then, to the right of the target framework, select the device to debug with. You will need to connect an android device, or create an Android simulator.
- Then, to the right of the target framework, select the device to debug with. You will need to connect an iOS device, or use an existing iOS simulator.
- Finally, in the debugger side menu, select the `Uno Plaform Mobile` profile
- Either press `F5` or press the green arrow to start the debugging session.
***
Once your app is running, place a breakpoint in the `OnClick` method, the breakpoint will be hit when clicking the button in the app.
You can find [advanced Code debugging topic here](xref:uno.vscode.mobile.advanced.debugging).
## Using code snippets
### Adding a new Page
...
...
@@ -137,7 +212,7 @@ An existing application needs additional changes to be debugged properly.
3. Replace all instances of `UnoQuickStart` with your application's name in `launch.json`.
4. Inside this folder, create a file named `tasks.json` and copy the [contents of this file](https://github.com/unoplatform/uno/blob/master/src/SolutionTemplate/Uno.ProjectTemplates.Dotnet/content/unoapp/.vscode/tasks.json).
### Known limitations for Code support
### Known limitations for VS Code support
- C# Debugging is not supported when running in a remote Linux Container, Code Spaces or GitPod.
- C# Hot Reload for WebAssembly only supports modifying method bodies. Any other modification is rejected by the compiler.
- C# Hot Reload for Skia supports modifying method bodies, adding properties, adding methods, adding classes. A more accurate list is provided here in Microsoft's documentation.
...
...
@@ -148,6 +223,7 @@ If you're not sure whether your environment is correctly configured for Uno Plat
The Uno Platform extension provides multiple output windows to troubleshoot its activities:
-**Uno Platform**, which indicates general messages about the extension
-**Uno Platform - Debugger**, which provides activity messages about the debugger feature
-**Uno Platform - Hot Reload**, which provides activity messages about the Hot Reload feature
-**Uno Platform - XAML**, which provides activity messages about the XAML Code Completion feature
***Android** on Linux: Xamarin.Android does not natively support linux development. Rider has been capable of Android development on Linux in the past, but [previous directions are considered obsolete.](https://rider-support.jetbrains.com/hc/en-us/articles/360000557259--Obsolete-How-to-develop-Xamarin-Android-applications-on-Linux-with-Rider) As of this comment (3 Nov 2021) [Xamarin Android builds on linux fail](https://github.com/xamarin/xamarin-android).
* † **Android** on Linux: Xamarin.Android does not natively support linux development. Rider has been capable of Android development on Linux in the past, but [previous directions are considered obsolete.](https://rider-support.jetbrains.com/hc/en-us/articles/360000557259--Obsolete-How-to-develop-Xamarin-Android-applications-on-Linux-with-Rider) As of this comment (3 Nov 2021) [Xamarin Android builds on linux fail](https://github.com/xamarin/xamarin-android).
* †† Using `net6.0-android` (or later) SDK only. Not officially supported by Microsoft.
