Welcome to Uno Platform!

Congratulations, you've just created a new project using the Uno Platform project templates!

Verify your developer environment

Open a command-line prompt, Windows Terminal if you have it installed, or else Command Prompt or Windows Powershell from the Start menu.
a. Install the tool by running the following command from the command prompt:
```
dotnet tool install -g uno.check
```
b. To update the tool, if you already have an existing one:
```
dotnet tool update -g uno.check
```
Run the tool from the command prompt with the following command:
```
uno-check
```
Follow the instructions indicated by the tool

Note

Alternatively you can run uno-check --pre to install the preview version of the Uno Platform. This is strongly suggested when using Visual Studio Previews.

Open a Terminal.
a. Install the tool by running the following command from the command prompt:
```
dotnet tool install -g uno.check
```
b. To update the tool, if you already have an existing one:
```
dotnet tool update -g uno.check
```
Run the tool from the command prompt with the following command:
```
uno-check
```
If the above command fails, use the following:
```
~/.dotnet/tools/uno-check
```
Follow the instructions indicated by the tool

Open a Terminal.
a. Install the tool by running the following command from the command prompt:
```
dotnet tool install -g uno.check
```
b. To update the tool, if you already have an existing one:
```
dotnet tool update -g uno.check
```
Run the tool from the command prompt with the following command:
```
uno-check
```
If the above command fails, use the following:
```
~/.dotnet/tools/uno-check
```
Follow the instructions indicated by the tool

You can find additional information about uno-check here.

Next steps

You can give the Single Page app getting started guide a try
Next you can try our Bug Tracker sample walkthrough
More advanced examples in our Uno.Samples repository
Fork a fully-fledged Ch9 application and source code
You can find detailed documentation on Uno topics on our web site.
Run the uno-check command-line tool to ensure your dev environment is set up correctly

Common Issues

The Uno Platform features and support are constantly evolving, but you may encounter some of the issues below while building your application. Some additional topics may be found in the GitHub top discussions.

WebAssembly: Access to fetch at 'https://XXXX' from origin 'http://XXXX' has been blocked by CORS policy

This is a security restriction from the JavaScript fetch API, where the endpoint you're calling needs to provide CORS headers to work properly.

If you control the API, you'll need to use the features from your framework to enable CORS, and if you don't you'll need to ask the maintainers of the endpoint to enable CORS.

To test if CORS is really the issue, you can use CORS Anywhere to proxy the queries.

error NETSDK1148: A referenced assembly was compiled using a newer version of Microsoft.Windows.SDK.NET.dll.

See this article to solve this issue.

The XAML editor shows `The type 'page' does not support direct content` message

XAML Intellisense is not working properly in Visual Studio when the active project is not the UWP one.

To work around this issue, close all XAML editors, open a C# file and select the '[MyApp].Windows' in the top-left drop-down list of the text editor sector. Once selected, re-open the XAML file.

`InitializeComponent` or `x:Name` variable is not available in code-behind

Visual Studio does not refresh the intellisense cache properly, causing variables to be incorrectly defined.

To fix this issue, build your project once, close the solution and reopen it.

It is also important to note that Uno uses a multi-project structure, for which each project has to be build individually for errors to disappear from the Error List window (notice the Project column values).

In order to clear the Error List window, build the whole solution completely once. Thereafter, build a specific project and prefer the use of the Output tool window (in the menu View -> Output), taking build messages by order of appearance.

Event handler cannot be added automatically

Event handlers cannot be automatically added using the XAML editor.

A workaround is to use the x:Bind to events feature. This feature allows to use a simpler syntax like <Button Click="{x:Bind MyClick}" /> and declare a simple method private void MyClick() { } in the code-behind.

Cannot build with both Uno.WinUI and Uno.UI NuGet packages referenced

This issue generally happens when referencing a Uno.UI (using UWP APIs) NuGet package in an application that uses Uno.WinUI (Using WinAppSDK APIs).

For instance, if your application has <PackageReference Include="Uno.WinUI" in the csproj files, this means that you'll need to reference WinUI versions of NuGet packages.

For instance:

Uno.UI -> Uno.WinUI

Build error `Failed to generate AOT layout`

When building for WebAssembly with AOT mode enabled, the following error may appear:

Failed to generate AOT layout (More details are available in diagnostics mode or using the MSBuild /bl switch)

To troubleshoot this error, you can change the text output log level:

Go to Tools, Options, Projects and Solution, then Build and Run
Set MSBuild project build output verbosity to Normal or Detailed
Build your project again and take a look at the additional output next to the Failed to generate AOT layout error

You can get additional build troubleshooting information here.

Runtime error `No parameterless constructor defined for XXXX`

This error is generally caused by some missing IL Linker configuration on WebAssembly. You may need to add some of your application assemblies in the LinkerConfig.xml file of your project. You can find additional information in the documentation.

Similar error messages using various libraries:

Don't know how to detect when XXX is activated/deactivated, you may need to implement IActivationForViewFetcher (ReactiveUI)

System.DllNotFoundException: Gtk: libgtk-3-0.dll

When running the Skia.GTK project head, the following error may happen:

Unhandled exception. System.TypeInitializationException: The type initializer for 'Gtk.Application' threw an exception.
---> System.DllNotFoundException: Gtk: libgtk-3-0.dll, libgtk-3.so.0, libgtk-3.0.dylib, gtk-3.dll

On Windows, you will need to install the GTK+3 runtime. Make sure to restart Visual Studio for the changes to be used by Visual Studio. On Linux, you'll need to follow the Uno Platform setup instructions. On macOS, you'll need to follow the Uno Platform setup instructions.

XAML Hot Reload troubleshooting

The XAML Hot reload provides a Visual Studio for Windows output window name "Uno Platform" with diagnostics messages. You can find additional information there in case XAML Hot Reload does not work properly.

Some common troubleshooting steps:

Make sure to rebuild your application if the XAML changes are not applied
Ensure that the Uno.UI.RemoteControl package has the same version as the Uno.UI package (Similar step is valid for Uno.WinUI packages)

More troubleshooting information is available in this section.

C# Hot Reload troubleshooting

C# Hot Reload is provided by Visual Studio 2022, and there may be occasions where updates are not applied, or the modified code is incorrectly reported as not compiling.

If that is the case:

Make sure that the top left selector in the C# editor is showing the project head being debugged. For instance, if debugging the Skia.Gtk, select the Skia.Gtk project.
WebAssembly does not support C# hot reload when debugging the application. You can start the app without the debugger instead.
Try recompiling the application completely (with the Rebuild command)

Abnormally long build times with using WebAssembly and WSL

When building an application that uses native dependencies (such as Skia, SQLite) or using PG-AOT/AOT, using WSL 2 may cause abnormally long build times.

You can migrate your WSL v2 installation into a v1, by visiting this document.

"Missing value for TargetPlatformWinMDLocation property" when adding a project reference

This issue is caused by VS 2019 support for SDK-Style projects.

To add a reference change the list of <TargetFramework> to place netstandard2.0 at the first position in the project you are trying to add the reference to.

Abnormally long build times when using Roslyn analyzers

It is a good practice to use Roslyn analyzers to validate your code during compilation, but some generators may have difficulty handling the source generated by the Uno Platform (one notable example is GCop). You may need to disable those for Uno projects or get an update from the analyzer's vendor.

`Don't know how to marshal a return value of type 'System.IntPtr'`

This issue may happen for Uno.UI 4.4.20 and later when deploying an application using the iOS Simulator or MacCatalyst when the application contains a TextBox.

In order to fix this, add the following to your csproj (Xamarin, net6.0-ios, net6.0-maccatalyst):

<PropertyGroup>
  <MtouchExtraArgs>$(MtouchExtraArgs) --registrar=static</MtouchExtraArgs>
</PropertyGroup>

WebAssembly: Hot Reload fails to start with Mixed Content: The page at XXX was loaded over HTTPS, but attempted to connect to the insecure WebSocket endpoint

This issue is caused by visual studio enforcing https connections for local content. You can work around this by either:

Removing the https endpoint in the Properties/launchSettings.json file
Unchecking the Use SSL option in the project's Debug launch profiles
Selecting the project name instead of IISExpress in the toolbar debug icon drop down list

Build fails with `error : Error reading response`

In general, this error happens when the XAML parser detects a syntax error. Fixing the error generally fixes the build.

This error may happen occasionally without any explicit error message, rebuilding the project may fix the issue.

Error MSB3030: Could not copy the file "MyProject.Shared\MainPage.xbf" because it was not found.

This issue is present in Visual Studio 17.2 and 17.3, and can be addressed by taking a look at this issue.