dotnet · davidbritch · Jun 16, 2021 · Jun 11, 2021 · Jun 11, 2021 · Jun 11, 2021
diff --git a/.gitignore b/.gitignore
@@ -5,4 +5,5 @@ _site/
 _themes*/
 _repo.*/
 
-.openpublishing.buildcore.ps1
+.openpublishing.buildcore.ps1
+.DS_Store
diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md
@@ -0,0 +1,3 @@
+# Code of Conduct
+
+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](https://dotnetfoundation.org/code-of-conduct).
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -0,0 +1,5 @@
+# Contributing
+
+Thank you for your interest in contributing to the .NET documentation!
+
+We have moved our guidelines into a site-wide contribution guide. To see the guidance, visit the [Microsoft Docs contributor guide](https://docs.microsoft.com/contribute/dotnet/dotnet-contribute).
diff --git a/README.md b/README.md
@@ -1,6 +1,6 @@
 # .NET MAUI Docs
 
-This repository will contain the conceptual documentation for .NET MAUI.
+This repository contains the conceptual documentation for .NET Multi-platform App UI (MAUI). It's published at the [.NET MAUI documentation site](https://docs.microsoft.com/dotnet/maui).
 
 ## Code of Conduct
 

diff --git a/docs/TOC.yml b/docs/TOC.yml
@@ -1,2 +1,28 @@
-- name: Index
- href: index.md
+- name: .NET MAUI
+ href: index.yml
+ items:
+ - name: What is .NET Multi-platform App UI?
+ href: what-is-maui.md
+ - name: Supported platforms
+ href: supported-platforms.md
+ - name: Get started
+ expanded: true
+ items:
+ - name: Installation
+ href: get-started/installation.md
+ - name: Build your first app
+ href: get-started/first-app.md
+ - name: Migrate from Xamarin.Forms
+ href: get-started/migrate.md
+ - name: Fundamentals
+ expanded: true
+ items:
+ - name: App startup
+ href: fundamentals/app-startup.md
+ - name: Single project
+ href: fundamentals/single-project.md
+ - name: User interface
+ expanded: true
+ items:
+ - name: Customize controls
+ href: user-interface/handlers/customize.md
diff --git a/docs/docfx.json b/docs/docfx.json
@@ -49,7 +49,7 @@
  "feedback_github_repo": "dotnet/docs-maui",
  "ms.author": "dabritch",
  "ms.prod": "dotnet-mobile",
- "title": ".NET Multi-platform App UI"
+ "ms.technology": "dotnet-maui"
  },
  "fileMetadata": {},
  "template": [],

diff --git a/docs/fundamentals/app-startup.md b/docs/fundamentals/app-startup.md
@@ -0,0 +1,194 @@
+---
+title: ".NET MAUI app startup"
+description: ".NET MAUI apps are bootstrapped using HostBuilder from the Microsoft.Extensions library, enabling apps to be initialized from a single location."
+ms.date: 06/10/2021
+---
+
+# .NET MAUI app startup
+
+.NET Multi-platform App UI (MAUI) apps are bootstrapped using the [.NET Generic Host](/dotnet/core/extensions/generic-host). This enables apps to be initialized from a single location, and provides the ability to configure fonts, services, and third-party libraries.
+
+Each platform has an entry point that initializes the app host builder, and then invokes the `Configure` method of the `Startup` class in your app. The `Startup` class can be considered the entry point for your app, and is responsible for creating a window that defines the initial page of your app.
+
+The `Startup` class, which must implement the `IStartup` interface, must at a minimum provide an app to run:
+
+```csharp
+using Microsoft.Maui;
+using Microsoft.Maui.Hosting;
+
+public class Startup : IStartup
+{
+ public void Configure(IAppHostBuilder appBuilder)
+ {
+ appBuilder
+ .UseMauiApp<App>();
+ }
+}
+```
+
+The `App` class should derive from the `Application` class, and must override the `CreateWindow` method to provide a `Window` within which your app runs, and that defines the UI for the initial page of the app:
+
+```csharp
+using Microsoft.Maui;
+using Microsoft.Maui.Controls;
+
+public partial class App : Application
+{
+ protected override IWindow CreateWindow(IActivationState activationState)
+ {
+ return new Window(new MainPage());
+ }
+}
+```
+
+In the example above, `MainPage` is a `ContentPage` that defines the UI for the initial page of the app.
+
+## Register fonts
+
+Fonts can be added to your app and referenced by filename or alias. This is accomplished by invoking the `ConfigureFonts` method on the `IAppHostBuilder` object. Then, on the `IFontCollection` object, call the `AddFont` method to add the required font:
+
+```csharp
+using Microsoft.Maui;
+using Microsoft.Maui.Hosting;
+
+public class Startup : IStartup
+{
+ public void Configure(IAppHostBuilder appBuilder)
+ {
+ appBuilder
+ .UseMauiApp<App>()
+ .ConfigureFonts(fonts =>
+ {
+ fonts.AddFont("Lobster-Regular.ttf", "Lobster");
+ }); 
+ }
+}
+```
+
+In the example above, the first argument to the `AddFont` method is the font filename, while the second argument represents an optional alias by which the font can be referenced when consuming it.
+
+Any custom fonts consumed by an app must be included in your .csproj file. This can be accomplished by referencing their filenames, or by using a wildcard:
+
+```xml
+<ItemGroup>
+ <MauiFont Include="Resources\Fonts\*" />
+</ItemGroup>
+```
+
+> [!NOTE]
+> Fonts added to the project through the Solution Explorer in Visual Studio will automatically be included in the .csproj file.
+
+The font can then be consumed by referencing its name, without the file extension:
+
+```xaml
+<!-- Use font name -->
+<Label Text="Hello .NET MAUI"
+ FontFamily="Lobster-Regular" />
+```
+
+Alternatively, it can be consumed by referencing its alias:
+
+```xaml
+<!-- Use font alias -->
+<Label Text="Hello .NET MAUI"
+ FontFamily="Lobster" />
+```
+
+<!-- ## Configure Essentials
+
+```csharp
+appBuilder
+ .UseMauiApp<App>()
+ .ConfigureEssentials(essentials =>
+ {
+ essentials
+ .UseVersionTracking()
+ .UseMapServiceToken("YOUR-KEY-HERE");
+ });
+``` -->
+
+## Register handlers
+
+To register your own handlers, call the `ConfigureMauiHandlers` method on the `IAppHostBuidler` object. Then, on the `IMauiHandlersCollection` object, call the `AddHandler` method to add the required handler:
+
+```csharp
+using Microsoft.Maui;
+using Microsoft.Maui.Hosting;
+
+public class Startup : IStartup
+{
+ public void Configure(IAppHostBuilder appBuilder)
+ {
+ appBuilder
+ .ConfigureMauiHandlers(handlers =>
+ {
+ handlers.AddHandler(typeof(MyEntry), typeof(MyEntryHandler));
+ }) 
+ .UseMauiApp<App>(); 
+ }
+}
+```
+
+In this example, the `MyEntryHandler` handler is registered against the `MyEntry` control. Therefore, any instances of the `MyEntry` control will be handled by the `MyEntryHandler`.
+
+## Configure compatibility
+
+To use Xamarin.Forms compatibility features, including controls backed by Xamarin.Forms renderers instead of .NET MAUI handlers, call the `UseFormsCompatibility` method on the `IAppHostBuilder` object:
+
+```csharp
+using Microsoft.Maui;
+using Microsoft.Maui.Hosting;
+using Microsoft.Maui.Controls.Compatibility;
+
+public class Startup : IStartup
+{
+ public void Configure(IAppHostBuilder appBuilder)
+ {
+ appBuilder
+ .UseFormsCompatibility()
+ .UseMauiApp<App>();
+
+ }
+}
+```
+
+The `UseCompatibility` method also accepts an optional `bool` argument that specifies whether to register renderers. By passing `false` to this method you can use all Xamarin.Forms compatibility features except for renderers.
+
+### Register renderers
+
+To use controls backed by .NET MAUI handlers, with specific controls backed by Xamarin.Forms renderers, call the `ConfigureMauiHandlers` method on the `IAppHostBuilder` object. Then, on the `IMauiHandlersCollection` object, call the `AddCompatibilityRenderer` method to add the required renderer:
+
+```csharp
+using Microsoft.Maui;
+using Microsoft.Maui.Hosting;
+using Microsoft.Maui.Controls.Compatibility;
+
+public class Startup : IStartup
+{
+ public void Configure(IAppHostBuilder appBuilder)
+ {
+ appBuilder
+ .UseFormsCompatibility(false)
+ #if __ANDROID__
+ .ConfigureMauiHandlers(handlers =>
+ {
+ handlers.AddCompatibilityRenderer(typeof(Microsoft.Maui.Controls.BoxView),
+ typeof(Microsoft.Maui.Controls.Compatibility.Platform.Android.BoxRenderer));
+ handlers.AddCompatibilityRenderer(typeof(Microsoft.Maui.Controls.Frame),
+ typeof(Microsoft.Maui.Controls.Compatibility.Platform.Android.FastRenderers.FrameRenderer));
+ })
+ #elif __IOS__
+ .ConfigureMauiHandlers(handlers =>
+ {
+ handlers.AddCompatibilityRenderer(typeof(Microsoft.Maui.Controls.BoxView),
+ typeof(Microsoft.Maui.Controls.Compatibility.Platform.iOS.BoxRenderer));
+ handlers.AddCompatibilityRenderer(typeof(Microsoft.Maui.Controls.Frame),
+ typeof(Microsoft.Maui.Controls.Compatibility.Platform.iOS.FrameRenderer));
+ })
+ #endif 
+ .UseMauiApp<App>();
+ }
+}
+```
+
+In this example, all controls in the app will be backed by handlers, aside from the `BoxView` and `Frame` controls that will be backed by Xamarin.Forms renderers.
diff --git a/docs/fundamentals/single-project-images/example.png b/docs/fundamentals/single-project-images/example.png
diff --git a/docs/fundamentals/single-project.md b/docs/fundamentals/single-project.md
@@ -0,0 +1,33 @@
+---
+title: ".NET MAUI single project"
+description: "The .NET MAUI single project brings all the platform-specific experiences across Android, iOS, macOS, and Windows, into one shared head project."
+ms.date: 06/10/2021
+---
+
+# .NET MAUI single project
+
+.NET Multi-platform App UI (MAUI) single project is a collection of features that brings all the platform-specific experiences you encounter while developing apps into one shared head project that can target Android, iOS, macOS, and Windows.
+
+Single project is enabled using multi-targeting and the use of SDK-style projects in .NET 6. You can still expect access to all the platform-specific experiences and tools when you need them, while enjoying a simplified, shared development experience across all the platforms you're targeting.
+
+## Simplify development
+
+Single project is built on top of a collection of experiences that are being simplified in .NET 6. The following list shows the experiences that will be shared in .NET MAUI single project:
+
+- Resources
+ - Images
+ - Fonts
+ - App icons
+ - Splash screens
+ - Raw Assets
+- App manifest
+- NuGet
+- Platform-specific code
+
+All other features are being moved from their own platform-projects into platform folders in the single project.
+
+## Visual Studio changes
+
+In addition to the simplified, shared experiences in single project, there are changes being made to Visual Studio to support single project. These changes will enable the use of a shared resource file within the single project, platform files for platform-specific development, and a simplified debug target selection for running your .NET MAUI apps:
+
+:::image type="content" source="single-project-images/example.png" alt-text="Single project screenshot.":::
diff --git a/docs/get-started/first-app-images/broken-dependencies.PNG b/docs/get-started/first-app-images/broken-dependencies.PNG
diff --git a/docs/get-started/first-app-images/configure-project.PNG b/docs/get-started/first-app-images/configure-project.PNG
diff --git a/docs/get-started/first-app-images/new-project.PNG b/docs/get-started/first-app-images/new-project.PNG
diff --git a/docs/get-started/first-app-images/new-solution.PNG b/docs/get-started/first-app-images/new-solution.PNG
diff --git a/docs/get-started/first-app-images/restored-dependencies.PNG b/docs/get-started/first-app-images/restored-dependencies.PNG
diff --git a/docs/get-started/first-app-images/running-app-large.png b/docs/get-started/first-app-images/running-app-large.png
diff --git a/docs/get-started/first-app-images/running-app.png b/docs/get-started/first-app-images/running-app.png
diff --git a/docs/get-started/first-app-images/select-android-emulator.PNG b/docs/get-started/first-app-images/select-android-emulator.PNG
diff --git a/docs/get-started/first-app.md b/docs/get-started/first-app.md
@@ -0,0 +1,60 @@
+---
+title: "Build your first .NET MAUI app in Visual Studio"
+description: "How to create and run your first .NET MAUI app."
+ms.date: 06/09/2021
+---
+
+# Build your first .NET MAUI app
+
+In this tutorial, you'll learn how to create your first .NET Multi-platform App UI (MAUI) app, and run it in an Android emulator.
+
+## Prerequisites
+
+- Visual Studio 2019 (build 16.11 Preview 1 or greater) or Visual Studio 2022 (any edition).
+- An environment that has been configured for .NET MAUI development, using the maui-check tool. For more information, see [Installation](installation.md).
+- A configured Android emulator. For more information about creating an Android emulator, see [Android emulator setup](/xamarin/android/get-started/installation/android-emulator/).
+
+## Get started with Visual Studio 2019
+
+1. Launch VS2019 build 16.11 (Preview 1 or greater), and in the start window click **Create a new project** to create a new project:
+
+ :::image type="content" source="first-app-images/new-solution.png" alt-text="New solution":::
+
+1. In the **Create a new project** window, select **MAUI** in the **Project type** drop-down, select the **.NET MAUI App** template, and click the **Next** button:
+
+ :::image type="content" source="first-app-images/new-project.png" alt-text="Choose a template":::
+
+1. In the **Configure your new project** window, name your project, choose a suitable location for it, and click the **Create** button:
+
+ :::image type="content" source="first-app-images/configure-project.png" alt-text="Configure the project":::
+
+ Wait for the project to be created. Note that Visual Studio hasn't restored the required .NET 6 dependencies. You'll restore them in a later step.
+
+ :::image type="content" source="first-app-images/broken-dependencies.png" alt-text="Broken dependencies":::
+
+1. In the .NET CLI, create a *nuget.config* file in the root folder of the project and add the `maui-preview` feed:
+
+ ```dotnetcli
+ dotnet new nugetconfig
+ dotnet nuget add source -n maui-preview https://aka.ms/maui-preview/index.json
+ ```
+
+1. In the .NET CLI, restore the dependencies for the newly created project:
+
+ ```dotnetcli
+ dotnet restore
+ ```
+
+ In Visual Studio, note that the dependencies have now been restored:
+
+ :::image type="content" source="first-app-images/restored-dependencies.png" alt-text="Restored dependencies":::
+
+1. In the Visual Studio toolbar, select the drop-down next to the **Start** button (the triangular button that resembles a Play button), select **Android Emulator**, and then select the emulator you'd like to deploy the app to:
+
+ :::image type="content" source="first-app-images/select-android-emulator.png" alt-text="Select your Android emulator":::
+
+1. In the Visual Studio toolbar, press the **Start** button to launch the app in your chosen Android emulator.
+
+1. In the running app in the Android emulator, press the **CLICK ME** button several times and observe that the count of the number of button clicks is incremented.
+
+ [![App running in the Android emulator](first-app-images/running-app.png)](first-app-images/running-app-large.png#lightbox)
diff --git a/docs/get-started/installation-images/vs-workloads.png b/docs/get-started/installation-images/vs-workloads.png