This repository contains documentation for .NET Multi-platform App UI (MAUI).
Home Page: https://docs.microsoft.com/dotnet/maui
License: Creative Commons Attribution 4.0 International
This repository contains the conceptual documentation for .NET Multi-platform App UI (MAUI). It's published at the .NET MAUI documentation site.
This project has adopted the code of conduct defined by the Contributor Covenant to clarify expected behavior in our community. For more information, see the .NET Foundation Code of Conduct.
I am a mac user and on this page there is only windows and vs for windows. It would be cool to have something for mac, too and the cli commands to build and run because I always need to look them up :-D
⚠ Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.
Please state somewhere on the page that maui-check needs to be run (again if previously ran) and that this needs to be done at the end after changing the workloads of the Visual Studio being used.
One might get the feeling that if maui-check was done already, then all is good. But when the VS workloads are changed then maui-check may find missing stuff!
⚠ Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.
Lift and shift the quick docs from the .NET maui wiki, and expand upon them to create a basic initial set of docs for getting started with the .NET MAUI preview releases.
Add instructions to the first-app doc that describe how to use .NET CLI to create and launch apps. This will also involve restructuring the page to use zone pivots.
MAUI includes Resizeter, which resizes your images to the different resolutions required on different platforms.
Following the installation steps shows a message indicating there are minor problems. I reran maui-check and, while it made it through all of its checks, it still indicated there were minor problems. I then opened the solution in VS 2019 Preview. It allowed me to build the WindowsUI application, which retrieved missing files. After this step, I reran maui-check and got the, "Congratulations, everything looks great!" message.
⚠ Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.
Enable the localization workflow, once some docs are live.
GotoAsync now allows user to pass complex objects. See dotnet/maui#2004
MAUI includes the cross-platform Microsoft.Maui.Graphics library, which is supported in MAUI apps, iOS, Android, Mac, WPF, UWP, WinForms, Tizen, and Linux. It includes the following features:
The GraphicsView control, which is added in P5, can be used to consume this library.
I love MAUI very much since it really solved our cross-platform desktop app problem. The biggest thing I like is that it improved our deployment process when the target environment is Windows. We used to implement Blazor Server with Electron.Net and convert the final executable into MSIX package. But because of MAUI WinUI, we can shrink the deployment process into a single step.
However, while I am trying to do a production deployment, I have a couple questions and I couldn't find the information from the doc.
For Windows, do we package the app using the old Xamarin.Win deployment process? Or MAUI has a different way to proceed here. I am fairly new to Xamarin, but I know Blazor very well.
For Mac Catalyst, can we build/deploy the project without using Apple Developer Id? I am wondering if there is a way to deploy the project into a pkp package.
⚠ Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.
The supported platforms page says that macOS 11 or higher is supported (which is already a problem, almost no developer supports only the latest version of macOS, but I digress).
It doesn't say what frameworks are supported. Is macOS supported natively using Cocoa? (As it should be.) Or just using Catalyst? Or both? I've seen conflicting information in the blog posts and as it is still in preview I don't really trust the current state of things to properly indicate the future.
I'd like to see the supported platforms page clearly state which UI framework is being used to support macOS. Thank you.
⚠ Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.
Docs on this page says:
.NET MAUI apps can be written on PC or Mac, and compile into native app packages:
....
- Windows apps built using .NET MAUI use Windows UI Library (WinUI) 3 to create native apps that can target the Windows desktop and the Universal Windows Platform (UWP)
Please make it clear whether MAUI for Windows apps, will support outputting any of WinUI flavors: 1) WinUI Desktop, 2) WinUI UWP, or only one of them, which then is the question: which one.
If both are planned to be supported, the next question comes up how this scenario for targeting both will work in development, is it either UWP only or Desktop, or will it be possible to develop for both targets (WinUI-Desktop, WinUI UWP) in the same project simultaneously, meaning, they will be treated as different platforms like iOS, and Android, and so will be able to use compile-time platform directives for when compiling, like
#if WIN_UWP
or
#if WIN_DESKTOP
The question gets even greater with the fact that UWP runs on a restricted sandbox environment, vs WinUI desktop can access all system resources, so when coding in MAUI if targeting both UWP and Windows Desktop environments is possible, how would it handle code which is using windows resources (such as System.Diagnostics.Process) which are not allowed in UWP
⚠ Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.
[Enter feedback here]
Preview 6 is out. Please update the page content.
⚠ Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.
[Enter feedback here]
I'm having a problem with WinUI SDKs looks like there's a warning also when I tried to run WeatherTwenyOne App on my android phone I got this Error
Severity Code Description Project File Line Suppression State
Error ADB0020: Mono.AndroidTools.IncompatibleCpuAbiExceptiopn: The package does not support the CPU architecture of this device.
at Mono.AndroidTools.Internal.AdbOutputParsing.CheckInstallSuccess(String output, String packageName) in /Users/builder/azdo/_work/1/s/xamarin-android/external/monodroid/tools/msbuild/external/androidtools/Mono.AndroidTools/Internal/AdbOutputParsing.cs:line 342
at System.Threading.Tasks.Task.Execute()
--- End of stack trace from previous location where exception was thrown ---
at System.Runtime.ExceptionServices.ExceptionDispatchInfo.Throw()
at System.Runtime.CompilerServices.TaskAwaiter.HandleNonSuccessAndDebuggerNotification(Task task)
at AndroidDeviceExtensions.d__12.MoveNext() in /Users/builder/azdo/_work/1/s/xamarin-android/external/monodroid/tools/msbuild/external/androidtools/Xamarin.AndroidTools/Devices/AndroidDeviceExtensions.cs:line 206
--- End of stack trace from previous location where exception was thrown ---
at System.Runtime.ExceptionServices.ExceptionDispatchInfo.Throw()
at AndroidDeviceExtensions.d__12.MoveNext() in /Users/builder/azdo/_work/1/s/xamarin-android/external/monodroid/tools/msbuild/external/androidtools/Xamarin.AndroidTools/Devices/AndroidDeviceExtensions.cs:line 223
--- End of stack trace from previous location where exception was thrown ---
at System.Runtime.ExceptionServices.ExceptionDispatchInfo.Throw()
at System.Runtime.CompilerServices.TaskAwaiter.HandleNonSuccessAndDebuggerNotification(Task task)
at Xamarin.Android.Tasks.FastDeploy.d__105.MoveNext() in /Users/builder/azdo/_work/1/s/xamarin-android/external/monodroid/tools/msbuild/Tasks/FastDeploy.cs:line 339
--- End of stack trace from previous location where exception was thrown ---
at System.Runtime.ExceptionServices.ExceptionDispatchInfo.Throw()
at Xamarin.Android.Tasks.FastDeploy.d__105.MoveNext() in /Users/builder/azdo/_work/1/s/xamarin-android/external/monodroid/tools/msbuild/Tasks/FastDeploy.cs:line 356
--- End of stack trace from previous location where exception was thrown ---
at System.Runtime.ExceptionServices.ExceptionDispatchInfo.Throw()
at System.Runtime.CompilerServices.TaskAwaiter.HandleNonSuccessAndDebuggerNotification(Task task)
at Xamarin.Android.Tasks.FastDeploy.d__100.MoveNext() in /Users/builder/azdo/_work/1/s/xamarin-android/external/monodroid/tools/msbuild/Tasks/FastDeploy.cs:line 213 0
⚠ Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.
Ensure use of .NET CLI in MAUI is fully documented.
Ensure single project experiences are fully documented.
The initial docs include content on customising a handler, with some simple customisations. This doc really needs splitting into three docs:
Ensure that handler lifecycle events are covered: dotnet/maui#1200
Cross-platform lifecycle and native lifecycle.
The Window object supports lifecycle events and overrides: dotnet/maui#1754
Hi David, I am missing how to run the windows version from CLI...
⚠ Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.
Fully document how to automatically, and manually, migrate a Xamarin.Forms application to .NET MAUI.
Consider edge cases.
MAUI includes a performant VerticalStackLayout class, that should be added to User Interface > Layouts.
Call out to use this when it fits your layout need. Only use StackLayout if the orientation will change at runtime (adaptive layout based on screen size or device idiom).
The bullets under Prerequisites should be reordered (Installation of the new Visual Studio should be the first thing). In order to install .NET MAUI workloads, Visual studio 2022 must be already installed in the machine (.net 6 is necessary). At least, this happened to my case.
⚠ Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.
.NET MAUI introduces semantic properties, which map plat properties to native accessibility properties. This is in addition to the existing AutomationProperties from Xamarin.Forms.
Current semantic properties:
For more info, see dotnet/maui#469
https://devblogs.microsoft.com/xamarin/the-journey-to-accessible-apps-making-visual-text-accessible/
Additional specs:
dotnet/maui#845
dotnet/maui#927
dotnet/maui#1214
Also, see the internal .NET MAUI accessibility doc.
TabIndex removed
IsTabStop removed
TabIndex and IsTabStop properties were introduced in Xamarin.Forms to help developers control the order in which UI elements would be read by a screen reader. In practice, they ended up being confusing and not meeting that need. In .NET MAUI we recommend a thoughtful design approach that orders your UI as you would want it to be read, rather than looking for programmatic ways to manipulate the structure of your interface. For cases when you must take control over the order, we recommend the community toolkit’s SemanticOrderView which will be available in the .NET MAUI version of the same.
SemanticExtensions class
SetSemanticFocus method allows you to move screen reader focus to a specific element.
<VerticalStackLayout>
<Label
Text="Explore SemanticExtensions below"
TextColor="RoyalBlue"
FontAttributes="Bold"
FontSize="16"
Margin="0,10"/>
<Button
Text="Click to set semantic focus to label below"
FontSize="14"
Clicked="SetSemanticFocusButton_Clicked"/>
<Label
x:Name="semanticFocusLabel"
Text="Label receiving semantic focus"
FontSize="14"/>
</VerticalStackLayout>
private void SetSemanticFocusButton_Clicked(object sender, System.EventArgs e)
{
semanticFocusLabel.SetSemanticFocus();
}
SemanticScreenReader.Announce in Essentials
cc: @rachelkang
MAUI allows splash screens to be specified in the single project:
<MauiSplashScreen Include="Resources\appiconfg.svg" Color="#512BD4" />
Any image format can be provided along with a background brush, similar to how we also do app icons. For more advanced scenarios, platform-native splash screen methods still apply.
Related to #8
Migrate the Xamarin.Essentials docs to this repo, with updated namespaces, instructions etc.
Essentials is part of MAUI, rather than a separate product, and the content should live under /docs/platform-integration/essentials.
Note that at the time of writing, the ConfigureEssentials method that should be used in app startup is not in the correct namespace and so isn't easily callable.
Might be important, haven't had time to follow up...
dotnet : Workload installation failed: Inconsistency in workload manifest 'microsoft.net.workload.mono.toolchain': missing dependency 'Microsoft.NET.Workload.Emscripten'
At line:1 char:1
+ CategoryInfo : NotSpecified: (Workload
⚠ Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.
The Page class exposes navigation events and overrides: dotnet/maui#1812
These need documenting.
I have installed all the latest versions of the pre-requisites indicated here:
https://docs.microsoft.com/en-us/dotnet/maui/get-started/installation
I ran the maui-check tool and passed.
I then tried to build my first app:
https://docs.microsoft.com/en-us/dotnet/maui/get-started/first-app?pivots=dotnet-cli
This instruction failed:
dotnet new maui -n HelloMauiPreview
I has to run this command first before the templates were available:
dotnet new -i Microsoft.Maui.Templates
⚠ Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.
Document the BlazorWebView control, introduced in P4, which is used to host a Blazor web app in a .NET MAUI app.
For more info, see https://devblogs.microsoft.com/aspnet/asp-net-core-updates-in-net-6-preview-4/#net-maui-blazor-apps
Usage:
Add aBlazorWebView to any page and point to the root of the Blazor app:
<BlazorWebView
HostPage="wwwroot/index.html"
Services="{StaticResource Services}">
<BlazorWebView.RootComponent>
<RootComponent
Selector="#app"
ComponentType="{x:Type local:Main}" />
</BlazorWebView.RootComponent>
</BlazorWebView>
To complete the installation process we also need to set the Nuget source for MAUI.
While in Preview, IMHO the best practice is to add the source directly into the Visual Studio options:
So I think is better to add this to the page.
⚠ Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.
.NET SDK - Workloads (6.0.100-preview.7.21379.14) Checkup...
x android-aot (Microsoft.NET.Sdk.Android.Manifest-6.0.100 : 30.0.100-preview.7.110) not installed.
x ios (Microsoft.NET.Sdk.iOS.Manifest-6.0.100 : 15.0.100-preview.7.230) not installed.
x maccatalyst (Microsoft.NET.Sdk.MacCatalyst.Manifest-6.0.100 : 15.0.100-preview.7.230) not installed.
x tvos (Microsoft.NET.Sdk.tvOS.Manifest-6.0.100 : 15.0.100-preview.7.230) not installed.
x macos (Microsoft.NET.Sdk.macOS.Manifest-6.0.100 : 12.0.100-preview.7.230) not installed.
x maui (Microsoft.NET.Sdk.Maui.Manifest-6.0.100 : 6.0.100-preview.7.1345) not installed.
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
☼ Recommendation: Install or Update SDK Workloads
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
! Attempt to fix? [y/n] (y): y
» Attempting to fix: .NET SDK - Workloads (6.0.100-preview.7.21379.14)
SHELL: C:\Program Files\dotnet\dotnet.exe workload repair --source "https://api.nuget.org/v3/index.json" --source "https://pkgs.dev.azure.com/dnceng/public/_packaging/6.0.100-preview.7.21379.14-shipping-1/nuget/v3/index.json"
Repairing workload installation for workloads: maui
Installing pack Microsoft.Maui.Core.Ref.android version 6.0.100-preview.7.1063+sha.f5acc965e-azdo.5006556...
Rolling back pack Microsoft.Maui.Core.Ref.android installation...
Workload repair failed: microsoft.maui.core.ref.android::6.0.100-preview.7.1063 is not found in NuGet feeds https://api.nuget.org/v3/index.json;https://pkgs.dev.azure.com/dnceng/public/_packaging/6.0.100-preview.7.21379.14-shipping-1/nuget/v3/index.json".
repair
Repair workload installations.
Usage:
dotnet [options] workload repair
Options:
--sdk-version The version of the SDK.
--configfile The NuGet configuration file to use.
-s, --source
-v, --verbosity <d|detailed|diag|diagnostic|m|minimal|n|normal|q|quiet> Set the MSBuild verbosity level. Allowed values are q[uiet], m[inimal], n[ormal], d[etailed], and diag[nostic].
--disable-parallel Prevent restoring multiple projects in parallel.
--ignore-failed-sources Treat package source failures as warnings.
--no-cache Do not cache packages and http requests.
--interactive Allows the command to stop and wait for user input or action (for example to complete authentication).
-?, -h, --help Show help and usage information
Fix failed - Workload Repair failed: dotnet workload repair --source "https://api.nuget.org/v3/index.json" --source "https://pkgs.dev.azure.com/dnceng/public/_packaging/6.0.100-preview.7.21379.14-shipping-1/nuget/v3/index.json"
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
! There were one or more problems detected.
Please review the errors and correct them and run maui-check again.
Press enter to exit...
⚠ Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.
It would be great if the document would explain what to do when maui-check says:
x This version of the tool is incompatible with installing an older version of .NET 6
⚠ Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.
Use the :::image::: extension to display images.
Turn off borders on diagrams.
[Enter feedback here]
⚠ Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.
When VS2022 P3 drops, the build your first app doc should be updated to use the templates bundled in VS2022, rather than having to use .NET CLI.
MAUI updates the image handling used by Xamarin.Forms, and includes:
While an initial app startup doc has been created, there are more configuration options available that haven't been explained yet. Exhaustively determine all the configuration options and ensure they are documented. At the very least this includes ConfigureLifecycleEvents to register native lifecycle events.
These steps do not work. I get this error:
This version of the tool is incompatible with installing an older version of .NET 6
⚠ Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.
MAUI includes a performant HorizontalStackLayout class, that should be added to User Interface > Layouts.
Call out to use this when it fits your layout need. Only use StackLayout if the orientation will change at runtime (adaptive layout based on screen size or device idiom).
MAUI allows raw assets to be included in the single project:
<MauiAsset Include="Resources\Raw\index.html" />
You can also use wildcards to enable all files in a directory: "Include="Resources\Raw\*".
The raw asset can then be consumed e.g. <WebView Source="index.html" />.
Related to #8
A large amount of Xamarin.Forms docs requires migrating to .NET MAUI docs. This includes:
The good news is that most of the above has been done in the Xamarin docs private repo.
The remaining work to be done is:
Current installation instructions are not up to date for the latest preview. dotnet workload install maui appears to be necessary to get the templates to appear in dotnet new --list.
⚠ Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.
Hi everyone,
On a fresh setup of Vs VS2022 there's a missing step, the Android Emulator hasn't been installed.
When I try to install the emulator in VS2022 it fails, asks to send a report. This is the maui-check report.
¡ Unable to find any Android Emulators. You can use Visual Studio to create one if necessary:
The report has this message:
Please file an issue by choosing "Report a Problem" in the Help menu, and attach your logs.
Error summary: It looks like you are using an incompatible JDK. Please install and configure Microsoft Mobile OpenJDK.
I have the latest OpenJDK installed: C:\Program Files\Android\jdk\microsoft_dist_openjdk_1.8.0.25
I checked and this same error happened a year ago. I'm not sure if I shoudl try the solution as it seems like a regression caused by a different bug a year on?
https://developercommunity2.visualstudio.com/t/loading-Android-virtual-device-in-device/1154493
Any solution to install the Preview 5?
OpenJDK 11.0 Checkup...
Visual Studio 16.10.0 Checkup...
Android SDK Checkup...
Android Emulator Checkup...
¡ Unable to find any Android Emulators. You can use Visual Studio to create
one if necessary:
https://docs.microsoft.com/xamarin/android/get-started/installation/android-emulator/device-manager
.NET SDK Checkup...
.NET SDK - Workload Deduplication Checkup...
.NET SDK - EnableWorkloadResolver.sentinel Checkup...
.NET SDK - Workloads (6.0.100-preview.5.21302.13) Checkup...
.NET SDK - Packs (6.0.100-preview.5.21302.13) Checkup...
¡ Things look almost great, except some pesky warning(s) which may or may not bea problem, but at least if they are, you'll know where to start searching!
Press enter to exit...
⚠ Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.
Add periods to the end of alt-text so screen readers pause at the end of the alt-text.
Ensure .NET hot reload is fully documented.
[Enter feedback here]
There is no mention that .net 5 runtime has to be installed before running maui-check in your installation guide.
Also, OpenJdk11 is not recognized and the tool always install Microsoft OpenJdk 11 either way, not sure if this is normal.
⚠ Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.
MAUI includes a GraphicsView control, that can consume the types included in Microsoft.Maui.Graphics.
Document how to use this control.
Related to #17.
The "Build your first app" preview doc currently links to an Android emulator setup doc that's hosted under docs.microsoft.com/xamarin. This doc, and associated docs, need porting into this repo and also need updating.
The following docs may have content that needs porting:
https://docs.microsoft.com/en-us/xamarin/android/get-started/installation/windows
https://docs.microsoft.com/en-us/xamarin/android/get-started/installation/android-sdk?tabs=windows
https://docs.microsoft.com/en-us/xamarin/android/get-started/installation/android-emulator/
https://docs.microsoft.com/en-us/xamarin/android/get-started/installation/android-emulator/hardware-acceleration?pivots=windows
https://docs.microsoft.com/en-us/xamarin/android/get-started/installation/android-emulator/device-manager?tabs=windows&pivots=windows
https://docs.microsoft.com/en-us/xamarin/android/get-started/installation/android-emulator/device-properties?pivots=windows
https://docs.microsoft.com/en-us/xamarin/android/get-started/installation/android-emulator/troubleshooting?pivots=windows
https://docs.microsoft.com/en-us/xamarin/android/get-started/installation/set-up-device-for-development
The location for the ported docs in this repo needs deciding.
There are no steps that I can find for how to build the WinUI project through the command line.
I had assumed it was simple but has started to get complicated beyond what I understand so maybe I am missing the magic step. When I run the dotnet build command on the WinUI project, I get an error:
error MSB4086: A numeric comparison was attempted on "$(registry:HKEY_LOCAL_MACHINE\Software\Microsoft\Windows NT\CurrentVersion@CurrentVersion)" that evaluates to "" instead of a number, in condition "'$(AppxUseResourceIndexerApi)' == '' AND '$(registry:HKEY_LOCAL_MACHINE\Software\Microsoft\Windows NT\CurrentVersion@CurrentVersion)' < '6.3'"
It does work OK through Visual Studio 2022 - because of the Single-project MSIX Packaging Tools for VS 2022 (I think).
⚠ Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
Django
The Web framework for perfectionists with deadlines.
Laravel
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
Microsoft
Open source projects and samples from Microsoft.
Google
Google ❤️ Open Source for everyone.
Alibaba
Alibaba Open Source for everyone
D3
Data-Driven Documents codes.
Tencent
China tencent open source team.