In this chapter, you will be guided through the process of setting up your development machine. To work through all the examples in the book, you will need a machine running any of the following:

• Windows 10 (1809) or higher
• macOS 10.15 (Catalina) or higher

If you only have access to one, you'll still be able to follow along with most of the book. The book will primarily assume you are working with a Windows machine. We will only show examples that use Mac when absolutely necessary.

There is no source code for this chapter. However, the code for the other chapters can be found at the following URL: https://github.com/PacktPublishing/Creating-Cross-Platform-C-Sharp-Applications-with-Uno-Platform.

According to the website (https://platform.uno/), Uno Platform is "the first and only UI Platform for single-codebase applications for Windows, WebAssembly, iOS, macOS, Android and Linux."

That's a complex sentence so let's break down the key elements:

• As a UI platform, it's a way of building applications with a User Interface (UI). This is in contrast to those platforms that are text-based and run from the command line (or equivalent), are embedded in hardware, or are interacted with in other ways, such as by voice.
• Using a single code base means you only need to write code once to have it run on multiple devices and operating systems. Specifically, this means the same code can be compiled for each platform the app will run on. This is in contrast with tools that convert or transpile code into a different programming language before being compiled for another platform. It's also the only code base that's singular, not the output. Some comparable tools create a unique package that runs inside a host application on each OS, or create everything in HTML and JavaScript, and run inside an embedded browser. Uno Platform does neither of these. Instead, it produces native application packages for each platform.
• Windows apps are based on the Universal Windows Platform (UWP) for Windows 10. Work is currently being done at Microsoft to make WinUI 3 the successor to UWP. Uno Platform has partnered with Microsoft to ensure that Uno Platform can easily transition from UWP once WinUI 3 is at a comparable operative level.
• Windows support also includes the Windows Presentation Foundation (WPF), powered by SkiaSharp, for apps that need to run on older versions of Windows (7.1 or 8.1).
• Applications that run in WebAssembly have all their code compiled to run inside a web browser. This means they can be accessed from any device with a compatible browser, without running code on the server.
• By supporting iOS, the apps that are created can run on iPhones and iPads.
• With support for macOS, the apps can run on a MacBook, iMac, or Mac Mini.
• Support for Android applies to phones and tablets running the Android operating system.
• Linux support applies to specific Linux PC equivalent distributions and is powered by SkiaSharp.

Uno Platform does all of the preceding by reusing the tooling, APIs, and XAML that Microsoft created for building UWP apps.

Another way to answer the "what is Uno Platform?" question is that it's a way to write code once and have it run everywhere. The exact definition of "everywhere" is imprecise, as it doesn't include every embedded system or microcontroller capable of running code. Still, many developers and businesses have long had the desire to write code once and run it easily on multiple platforms. Uno Platform makes this possible.

One of the early criticisms of Microsoft's UWP was that it was only universal on Windows. With Uno Platform, developers can now make their UWP apps genuinely universal.

A brief history of Uno Platform

With the varied number of cross-platform tools available today, it's easy to forget how limited the options were back in 2013. At that time, there were no general-purpose tools for easily building native apps that ran on multiple operating systems.

It was at that time that nventive (https://nventive.com/), a Canadian software design and development company, faced a challenge. They had lots of knowledge and experience in building applications for Windows and Microsoft tools, but their customers were also asking them to create applications for Android and iOS devices. Rather than retrain staff or duplicate effort by building multiple versions of the same software for the different platforms, they invented a way to compile the code they wrote for Windows Phone (and later UWP) apps and transfer it to other platforms.

By 2018, it was obvious this approach had been successful for them. They then did the two following things:

1. They turned the tool they had created into an open source project, calling it Uno Platform.
2. They added support for WebAssembly.

As an open source project, this allowed other developers tackling the same problem to work together. Uno Platform has since seen thousands of contributions from over 200 external contributors, and involvement has been expanded to support more platforms and add additional functionality for the initially supported platforms.

As an open source project, it is free to use. Additionally, it is supported by a company with a business model that was made popular by Red Hat, and has been adopted widely. Usage is free and there is some free public support. However, professional support, training, and custom development are available only through payment.

How Uno Platform works

Uno Platform works in different ways and uses multiple underlying technologies, depending on the platform you're building for. These are summarized in Figure 1.1:

• If you're building an app for Windows 10, Uno Platform does nothing and lets all the UWP tooling compile and execute your app.
• If you're building an app for iOS, macOS, or Android, Uno Platform maps your UI to the native platform equivalents and uses native Xamarin libraries to call into the OS it is running on. It produces the appropriate native packages for each OS.
• If you're building a WebAssembly app, Uno Platform compiles your code against the mono.wasm runtime and maps the UI to HTML and CSS. This is then packaged into a .NET library that is launched with the Uno Platform web bootstrapper as static web content.
• To create Linux apps, Uno Platform converts your code to the .NET equivalent and uses Skia to create a version of the UI. It then outputs a .NET5 app that uses GTK3 to present the UI.
• Apps for Windows 7 and 8 are created by Uno Platform by wrapping the compiled code in a simple WPF (NETCore 3.1) app that uses SkiaSharp to render the UI.

  Refer to the following diagram:

Figure 1.1 – The high-level architecture of Uno Platform

Whichever operating system or platform you're building for, Uno Platform uses the native controls for the platform. This enables your apps to achieve the experience and performance of a fully native app. The exception to this is where it uses SkiaSharp. By using SkiaSharp, Uno Platform draws all UI content on a canvas rather than using platform-native controls. Uno Platform does not add an extra layer of abstraction to the running app (as you might find with cross-platform solutions that use a container, such as an embedded WebView within a shell app).

Uno Platform enables you to do a lot with a single code base. But can it do everything?

Is it a panacea?

The principle of writing code once and running that code everywhere is both powerful and appealing. However, it's necessary to be aware of the following two key points:

• Not all applications should be created for all platforms.
• It's not an excuse for not knowing the platforms the apps will run on.

Additionally, not everything warrants an app. Suppose you just want to share some information that won't be frequently updated. In such a scenario, a website with static web pages would likely be more appropriate.

The lesson just because you can do something doesn't mean you should applies to applications too. When you see how easy it is to create applications that run on multiple platforms, you may be tempted to deploy your applications everywhere you can. Before you do this, there are some important questions you need to ask:

• Is the app wanted or needed on all the platforms? Do people want and need to use it on all the platforms you make it available? If not, you may be wasting effort by putting it there.
• Does the application make sense on all the platforms? Suppose the application has key functionality that involves capturing images while outside. Does it make sense to make it available on a PC or Mac? In contrast, if the application requires the entry of lots of information, is this something people will want to do on the small screen of a mobile phone? Your decision about where to make an application available should be determined by its functionality and the people who will use it. Don't let your decision be based solely on what's possible.
• Can you support it on all platforms? Does the value you gain by making an application available on a platform justify the time and effort in releasing, maintaining, and supporting the application on that platform? If you only have a small number of people use the app on a particular type of device, but they generate many support requests, it's OK to reevaluate your support for such devices.

No technology will render a perfect solution for all scenarios, but hopefully, you can already see the opportunity that Uno Platform provides. Let's now look a bit closer at why and when you might want to use it.

Now you know what Uno Platform is, we'll look at what you need to consider when choosing whether to use it. There are four factors to consider:

• What you already know.
• What platforms do you wish to target?
• The functionality required in the app.
• How it compares to alternatives.

Let's explore each of these factors in relation to Uno Platform.

Uno Platform allows you to use what you already know

Uno Platform was initially created for developers using C# and XAML within Visual Studio. If this is familiar to you, this will make it easy to start using Uno Platform, as you'll be working with the software you already know.

If you're already familiar with UWP development, the differences will be minimal. If you're familiar with WPF development, there are minor differences in XAML syntax and available functionality. As we go through the book, you'll learn everything you need to build with Uno Platform. As long as you don't expect everything to work as it does in WPF, you'll be fine. Also, as the WinUI and Uno Platform teams are working to remove the minor differences that exist, you may never notice a difference.

If you don't know C# or XAML, Uno Platform may still be suitable for you, but as this book assumes familiarity with these languages, you may find it helpful to first read C# 9 and .NET 5 – Modern Cross-Platform Development – Fifth Edition, Mark J. Price, Packt Publishing, and Learn WinUI 3.0, Alvin Ashcraft, Packt Publishing.

Uno Platform supports many platforms

One of the great things about Uno Platform is the number of platforms it allows you to build for. Uno Platform has support for the most common platforms, but if you need to build applications that run on a niche platform or specialist device, then it may not be suitable for you. Additionally, if you need to support an old version of a platform or operating system, you may have to find workarounds or alternative solutions. The following table shows the versions of the supported platforms you can build for with Uno Platform:

Figure 1.2 – The lowest supported platform versions supported by Uno Platform

Support for multiple platforms can also be advantageous, even when you want very different application behaviors or functionalities across different platforms. It's possible to support multiple platforms by creating multiple solutions, rather than by combining everything into a single solution.

Uno Platform boasts up to 99% reuse of code and UI. This is great when you need the same thing on all devices. However, if you require different behavior or a UI that's highly customized for different platforms (something that we'll look into in future chapters), it can be easier to build the different applications in different solutions, as opposed to putting lots of conditional logic in the code. There is no hard and fast rule for how much conditional code is too much, and it varies based on project and personal preference. Just remember it remains an option if you ever find your code is becoming full of conditional comments that make it hard to manage.

Accordingly, it's also possible to use Uno Platform to build for a single platform. You may not want to create an app that runs everywhere. You may only be interested in a single platform. If that's the case, you can use Uno Platform for that too. It also makes it easy to add additional platforms in the future if your needs change.

Can Uno Platform do everything that your app requires?

Core to Uno Platform's ability to reuse the UWP APIs to build for other platforms is that it has code to map the UWP API to its equivalent on the other platforms. Due to time, practicality, and priority limitations, not all APIs are available on all platforms. By way of general guidance, the most common APIs are available on the broadest number of platforms. Suppose you need to use more specialist functionality or are targeting something other than Android, iOS, Mac, or WebAssembly? In that case, it's advisable to check that the features you need are available.

Tip

We recommended confirming that the functionality you need for your app is available before you start writing code. This will allow you to avoid any nasty surprises late in the development process.

Due to the permanence of printed books and the frequency with which new functionality is added and more APIs are supported, it's not appropriate to list what is supported here. Instead, you can see a high-level list of supported features at the following URL: https://platform.uno/docs/articles/supported-features.html. There's also a list of supported UI elements at the following URL: https://platform.uno/docs/articles/implemented-views.html. Of course, the definitive way to confirm what is and isn't available is to check the source code at the following URL: https://github.com/unoplatform/uno.

If you try and use an API that is not supported, you'll see a hint inside Visual Studio, as is shown in Figure 1.3. If you try and use this at runtime, you'll either get nothing (a NOOP) or a NotSupported exception:

Figure 1.3 – An example of an unsupported API being indicated in Visual Studio

If necessary, you can check for supported features at runtime by using the Windows.Foundation.Metadata.ApiInformation class.

As an open source project, there is also the option to add any currently unsupported features yourself. Contributing such an addition back into the project is always greatly appreciated and new contributors are always welcomed by the team.

How does Uno Platform compare to the alternatives?

As mentioned earlier, many tools are available for developing applications that run on more than one platform. It is not our intention to discuss all the options available, as they can be evaluated and compared with the previous three points. However, as this book is intended for developers already familiar with C#, XAML, and Microsoft technologies, it is appropriate to mention Xamarin.Forms.

Xamarin.Forms was created at around the same time as Uno Platform and has several similarities. The two key ones are using C# and XAML to create apps that run on multiple operating systems. Both do this by providing an abstraction over the Xamarin.iOS and Xamarin.Android libraries that contain the C# bindings to the underlying operating systems.

The two biggest differences between Uno Platform and Xamarin.Forms are as follows:

• Uno Platform supports building for a greater number of platforms.
• Uno Platform reuses the UWP APIs and XAML syntax, rather than building a custom one.

The second point is important for developers already familiar with UWP development. The names of many Xamarin.Forms elements and properties are similar-sounding, so remembering the variations can be challenging.

Version 5 of Xamarin.Forms was released toward the end of 2020 and is intended to be the last version of Xamarin.Forms. It will be replaced with .NET Multi-platform App UI (MAUI) as part of .NET 6. .NET MAUI will support building apps for iOS, Android, Windows, and Mac from a single code base. However, it will not include the ability to also build for WebAssembly. Microsoft already has Blazor for building for WebAssembly, and so is not looking to add this capability to .NET MAUI.

.NET 6 will bring with it many new capabilities. Some of these capabilities are being added specifically for .NET MAUI. Once part of .NET 6, these capabilities will not be limited only to .NET MAUI. They will be available to Uno Platform apps too. The most obvious of these new capabilities is in having a single project that can produce different outputs for different platforms. This will enable a significant simplification of the required solution structure.

Important note

As we write this book, Microsoft is preparing to release WinUI 3 as the next-generation Windows development platform. This will build upon UWP and is part of the Project Reunion effort to make all Windows functionality and APIs available to developers, regardless of the UI framework or application packaging technology they use.

As WinUI 3 is the successor of UWP development, the Uno Platform team has publicly stated that plans and preparations are underway for Uno Platform to transition to using WinUI 3 as the base upon which it builds. This is being done in partnership with Microsoft, allowing the Uno Platform team to take the WinUI code and modify it to work elsewhere. You can be confident that anything you make now will have a path to transition to and take advantage of the benefits and functionality that WinUI will bring.

Another similar cross-platform solution that uses XAML to define the UI of an app is Avalonia (https://avaloniaui.net/). This, however, is different in that it focuses only on applications for desktop environments.

As you now have a solid understanding of what Uno Platform is and why you'll want to use it, you'll need to set up your machine so you can write code and create apps.

Now that you are familiar with Uno Platform, you're undoubtedly eager to begin writing code. We'll start that in the next chapter, but you'll need to set up your development environment before we can begin.

Visual Studio is the most popular Integrated Development Environment (IDE) for developing Uno Platform apps. A large part of this is because it has the broadest set of capabilities and the best support for building UWP apps.

Developing with Visual Studio

To build apps with Uno Platform using Visual Studio, you will need to do the following three things:

• Ensure you have Visual Studio 2019 version 16.3 or higher, although using the latest version is recommended.
• Install the necessary workloads.
• Install the project and item templates.

Installing the required workloads

The many tools, libraries, templates, SDK, and other utilities that can be installed as part of Visual Studio are collectively called components. With over 100 components available, related components are grouped into workloads to make it easier to choose what you need. You select workloads in the Visual Studio Installer, and these are shown in Figure 1.4:

Figure 1.4 – The Visual Studio Installer showing various workload options

To build apps with Uno Platform, you'll need the following workloads installed:

• Universal Windows Platform Development
• Mobile development with .NET
• ASP.NET and web development
• .NET Core cross-platform development

Installing the required templates from the marketplace

To make it easier to build your Uno Platform applications, multiple project and item templates are available. These are installed as part of the Uno Platform Solution Templates extension. You can install this from within Visual Studio, or directly from the marketplace.

Installing templates from within Visual Studio

To install the extension containing the templates, perform the following actions within Visual Studio:

1. Go to Extensions>Manage Extensions.
2. Search for Uno. It should be the first result.
3. Click the Download button.
4. Click Close, let the extension installer complete, and then restart Visual Studio:

Figure 1.5 – Uno Platform Solution Templates shown in the Manage Extensions dialog

Installing templates from the marketplace

Follow these steps to install the extension from the marketplace:

1. Go to https://marketplace.visualstudio.com and search for Uno. It should be the first result returned.

   Alternatively, go directly to the following URL: https://marketplace.visualstudio.com/items?itemName=nventivecorp.uno-platform-addin.

2. Click on the Download button.
3. Double-click on the downloaded .vsix file to start the install wizard.
4. Follow the steps in the wizard.

With the workloads and templates installed, you're now ready to start building apps. However, if you want to develop for iOS or Mac, you'll also need a Mac device set up so that you can connect to it from Visual Studio on Windows.

Using other editors and IDEs

It's not compulsory to use Visual Studio 2019 on a Windows PC, and the Uno Platform team has worked hard to make building Uno Platform apps as flexible as possible. Therefore, you can use it within your existing working patterns and preferences.

Installing the required templates with the command line

In addition to working with the templates inside Visual Studio, it's also possible to install them for use from the command line. To install them this way, run the following at the command line or terminal:

dotnet new -i Uno.ProjectTemplates.Dotnet

After this command has finished, it will list all the available templates. You should see multiple entries with a short name, beginning with uno.

Building Uno Platform apps with Visual Studio for Mac

To build Uno Platform apps using Visual Studio for Mac, you will require the following:

• Visual Studio for Mac version 8.8 or higher (using the latest version is recommended).
• Xcode 12.0 or higher (using the latest version is recommended).
• An Apple ID.
• .NET Core 3.1 and 5.0 SDKs.
• GTK+3 (for running the Skia/GTK projects).
• The templates installed (see previous section).
• Enable the templates to be visible in Visual Studio for Mac by opening the Preferences menu option and then selecting Other>Preview Features and checking Show all .NET Core templates in the New Project Dialog.

Links to all these are available at the following URL: https://platform.uno/docs/articles/get-started-vsmac.html.

Building Uno Platform apps with Visual Studio Code

You can use Visual Studio Code to build WebAssembly apps on Windows, Linux, or Mac. Using it to build apps for other platforms is not yet supported.

To build Uno Platform apps using Visual Studio Code, you will need the following:

• Visual Studio Code (using the latest version is recommended)
• Mono
• .NET Core 3.1 and 5.0 SDKs
• The templates installed (see previous section)
• C# extension for Visual Studio Code
• JavaScript Debugger (Nightly) extension for Visual Studio Code

Links to all these are available at the following URL: https://platform.uno/docs/articles/get-started-vscode.html.

Building Uno Platform apps with JetBrains Rider

It is possible to use JetBrains Rider on Windows, Mac, and Linux, but not all platforms can be built for with all versions.

To build Uno Platform apps with JetBrains Rider, you will need the following:

• Rider version 2020.2 or higher, although using the latest version is recommended
• Rider Xamarin Android Support Plugin
• .NET Core 3.1 and 5.0 SDKs
• The templates installed (see previous section)

There are some additional points to be aware of when using JetBrains Rider, as follows:

• WebAssembly apps cannot yet be debugged from within the IDE. As a workaround, it's possible to use the Chromium in-browser debugger instead.
• If building the Skia/GTK projects on a Mac, you'll also need to install GTK+3.
• If you wish to build iOS or Mac apps using a Windows PC, you will need an attached Mac (as you would if using Visual Studio).

Links to all these and more details are available at the following URL: https://platform.uno/docs/articles/get-started-rider.html.

Important note

It is also possible to use Blend for Visual Studio (on Windows) to work with code as you can for regular UWP apps. However, Blend does not support all the project types that an Uno Platform solution contains. You may find it beneficial to have a separate version of the solution that doesn't include those projects, and access that version in Blend.

Checking your setup

Uno Platform has a dotnet global tool to check if your machine is set up correctly and walk you through addressing any issues it finds. It's called uno-check and it's very simple to use, as follows:

1. Open a developer Command Prompt, Terminal, or PowerShell window.
2. Install the tool by entering the following:

   dotnet tool install --global Uno.Check

3. Run the tool by entering the following:

   uno-check

4. Follow any prompts it gives you and enjoy looking at the following message: Congratulations, everything looks great!

Debugging your setup

Whichever IDE or code editor you use, there will be many parts, and the use of multiple tools, SDKs, and even machines can make it hard to know where to begin when things aren't working. The following are general tips to help work out what isn't working. Some of these may seem obvious, but I'd rather look a fool for reminding you to check something obvious than have you waste time on an unchecked assumption:

• Try restarting your machine. Yes, I know, it would be funny if it didn't work so often.
• Read and then re-read any error messages carefully. They can sometimes be helpful.
• Check you have installed everything correctly.
• Has anything changed? Even if you didn't do it directly, something might have been changed automatically or without your knowledge (including, but not limited to, OS updates, security patches, IDE updates, other apps being installed or uninstalled, and network security permission changes).
• If one thing has been updated, have all dependencies and referenced components been updated too? It's common that when things are connected, share references, or communicate, they must be updated together.
• Have any keys or licenses expired?
• If there is a problem with a previously created app, can you create a new app and compile and run that?
• Can you create a new app and confirm that it compiles and runs on each platform?
• If on Windows, can you create a new blank UWP app and then compile and debug it?

Trying equivalent actions or creating equivalent apps with other tools can often produce different error messages. In addition, you may also find paths to solutions that fix problems in your Uno Platform project setup:

• If using a WebAssembly app, can you create a new, blank ASP.NET web app or Blazor project and compile and debug that?
• If a WebAssembly app doesn't work in one browser, are error messages shown in the browser log or debug window? Does it work in another browser?
• For Android, iOS, or macOS issues, can you create, compile, and debug Xamarin.Forms apps?
• If there is an Android-specific issue, can you create and debug an app with Android Studio?
• If using a Mac, can you create and debug a blank app with Xcode?

Additional tips for resolving common setup and configuration issues can be found at the following two URLs:

• https://platform.uno/docs/articles/get-started-wizard.html#common-issues
• https://platform.uno/docs/articles/uno-builds-troubleshooting.html

If the issue comes from connecting to a Mac from a PC, the Xamarin documentation may be helpful. It is available at the following URL: https://docs.microsoft.com/en-us/xamarin/ios/get-started/installation/windows/connecting-to-mac/. This can also help identify and address the issue in Uno Platform projects as well.

Details on where to go for answers to specific Uno Platform-related questions can be found in Chapter 8, Deploying Your Apps and Going Further.

In this chapter, we learned what Uno Platform is, the problem it was designed to solve, and the types of projects we can use it for. We then looked at how to set up your development environment, making it ready in order to build your first application with Uno Platform.

In the next chapter, we will build our first Uno Platform app. We will explore the structure of the generated solution, look at how to debug on different environments, and customize the app when it runs on those different environments. We will look at how you can create reusable libraries for use within your future Uno Platform projects. Finally, we will look at some of the other options available for creating Uno Platform apps.

The following titles were mentioned earlier in this chapter and may provide useful background on working with C# and XAML if you are unfamiliar with them:

• C# 9 and .NET 5 – Modern Cross-Platform Development – Fifth Edition, Price, Packt Publishing (2020)
• Learn WinUI 3.0, Ashcraft, Packt Publishing (2021)