Merge pull request #4778 from unoplatform/dev/djo/docs-migrating

docs: Expand guidance for migrating code, working with cross-targeted libraries

doc/articles/cross-targeted-libraries.md

@@ -0,0 +1,68 @@
+# Working with cross-targeted class libraries
+
+Using cross-targeted library projects allows the same code to be compiled for multiple platforms from a single project, and offers advantages over older project formats, such as not having to explicitly include every file. However, certain operations are not yet well-supported for cross-target projects in Visual Studio. This article details how to perform common operations with cross-target library projects, like adding references.
+
+*(Improved IDE support for cross-targeted projects is expected in the .NET 6 timeframe.)*
+
+## The .csproj format
+
+Cross-targeted libraries use the new 'SDK-style' [project file format](https://docs.microsoft.com/en-us/dotnet/core/tools/csproj). This format is considerably cleaner than older-style `.csproj` files.
+
+Note that you can edit new-style `.csproj` files directly without needing to unload the project first. 
+
+### Platform-conditional settings
+
+Often you'll want some properties or items to only be defined for specific targets. To do this you put them in a `PropertyGroup` or `ItemGroup` with `Condition=" '$(TargetFramework)' == 'targetname' "` set. You can use the `or` keyword to match multiple targets.
+
+
+## Adding references
+
+### NuGet references
+
+NuGet references that should be shared by all platforms can be added through the Visual Studio NuGet UI.
+
+If you want to apply NuGet references only to specific platforms, you can do so by manually editing the `csproj` file and putting the `PackageReference` within a conditional `ItemGroup`, eg:
+```xml
+	<ItemGroup Condition="'$(TargetFramework)' == 'MonoAndroid11.0'">
+		<PackageReference Include="Com.Airbnb.Android.Lottie" Version="3.0.4" PrivateAssets="none" />
+		<PackageReference Include="Newtonsoft.Json" Version="9.0.1" />
+	</ItemGroup>
+
+	<ItemGroup Condition="'$(TargetFramework)' == 'xamarinios10' or '$(TargetFramework)' == 'xamarinmac20'">
+		<PackageReference Include="Com.Airbnb.iOS.Lottie" Version="2.5.11" PrivateAssets="none" />
+	</ItemGroup>
+```
+
+### Project references and SDK references
+
+Adding project references and framework references is not currently working through Visual Studio's interface is not currently working, it gives an error of "Missing value for TargetPlatformWinMDLocation property". You need to add the reference by editing the `csproj` file directly.
+
+Example project reference:
+```xml
+  <ItemGroup>
+    <ProjectReference Include="..\CoolControls.Core\CoolControls.Core.csproj" />
+  </ItemGroup>
+```
+
+Example SDK reference:
+```xml
+	<ItemGroup Condition=" '$(TargetFramework)' == 'MonoAndroid11.0' or '$(TargetFramework)' == 'xamarinios10' or '$(TargetFramework)' == 'xamarinmac20' ">
+		<Reference Include="System.Numerics" />
+		<Reference Include="System.Numerics.Vectors" />
+	</ItemGroup>
+```
+
+## Adding Xaml files
+
+All Xaml files within the project folder are automatically included in the project, via the 'globbing' defined in the default cross-targeted library template.
+
+In Visual Studio you can add new Xaml files via the normal 'Add Items...' UI. Note that this will also add explicit references to the file in the `.csproj`. The explicit references can be safely deleted, they're not necessary.
+
+## Defining conditional symbols
+
+Adding a new conditional symbol via the Visual Studio UI may result in it only being defined for a single target platform. To add it for all platforms (or a specific subset), manually edit the `csproj` file:
+```xml
+  <PropertyGroup>
+    <DefineConstants>UNO_1213</DefineConstants>
+  </PropertyGroup>
+```

doc/articles/features/pointers-keyboard-and-other-user-inputs.md

@@ -71,7 +71,7 @@ On Skia however, they are fully managed events.
 
 Like on WinUI as soon as the system detects that the user wants to scroll, a control gets a `PointerCancelled` and that control won't receive
 any other pointer event until the user releases the pointer. That behavior can be prevented by setting the `ManipulationMode` 
-to something else than `System` on a control nested in the `ScrollViewer`. (cf. [Manipulation events](#Manipulation_Events))
+to something else than `System` on a control nested in the `ScrollViewer`. (cf. [Manipulation events](#manipulation-events))
 
 Be aware that on iOS this will set `DelaysContentTouches` to `false` so it means that it will slightly reduce the performance
 of the scrolling (cf. [documentation](https://developer.apple.com/documentation/uikit/uiscrollview/1619398-delayscontenttouches)).

doc/articles/get-started-wizard.md

@@ -71,4 +71,4 @@ Unhandled exception. System.TypeInitializationException: The type initializer fo
 
 On Windows, you will need to install the [GTK+3 runtime](https://github.com/tschoonj/GTK-for-Windows-Runtime-Environment-Installer/releases). **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](get-started-with-linux.md#setting-up-for-linux) setup instructions.
-On macOS, you'll need to follow the [Uno Platform](get-started-with-vsmac.md) setup instructions.
+On macOS, you'll need to follow the [Uno Platform](get-started-vsmac.md) setup instructions.

doc/articles/how-to-host-a-webassembly-app.md

@@ -1,6 +1,6 @@
 # How to host a WebAssembly App
 
-- [WASM Web Server Configuration](#wasm-web-server-configuration)
+- WASM Web Server Configuration
   - [Nginx](#nginx)
   - [Apache](#apache)
 

doc/articles/howto-migrate-existing-code.md

@@ -1,33 +1,12 @@
-# How to migrate existing UWP code to Uno
+# Migrating UWP-only code to Uno
 
-There are two separate paths for using an existing UWP codebase on top of uno:
-- An existing UWP application
-- An existing UWP library
+Uno Platform takes UWP code and makes it run on almost any target platform. If you have an existing application or library that was written to target UWP, you'll find guidance here for converting it to a cross-platform codebase, using UWP to target Windows 10 and Uno Platform to target other platforms. Depending on the APIs your code uses, it may run with minimal modifications, or you may need to add [platform-specific code](platform-specific-csharp.md) to cover missing functionality.
 
-For migrating UWP application, see [this article](migrating-apps.md).
+The articles in this guide cover:
 
-## Migrate an existing library
+ - Initial [checklist](migrating-before-you-start.md)
+ - Steps for [migrating an application](migrating-apps.md)
+ - Steps for [migrating a class library](migrating-libraries.md)
+ - [General guidance](migrating-guidance.md) for converting UWP-only code to Uno-compatible code
 
-To migrate an existing library, the shortest path is to create a Cross-Platform library and replace the existing library's project with it.
-
-### Steps
-Here's how to do it, from scratch. Let's start by creating a basic UWP library, so we can transform it to a cross-platform one:
-- In Visual Studio, create a **Class Library (Universal Windows)** project named `MyLibrary`
-- Make sure it builds.
-- Using the Uno Visual Studio Extension, create a **Cross-Platform Library (Uno Platform)** project in the same solution, and name it `TempUno`
-- Right click on `MyLibrary`, then **Unload Project**
-- Right click again on `MyLibrary`, then **Edit MyLibrary.csproj**
-- Right click on `TempUno`, then **Edit TempUno.csproj** _(There is no need to unload this type of project)_
--  Copy the whole content of the `TempUno` csproj, and paste it in the `MyLibrary` project file.
--  Right click on the `MyLibrary` project, then **Reload Project**
--  Delete the `TempUno` project from your solution
--  In the **Properties** folder, you'll need to remove the `AssemblyVersion` and similar properties as those are now generated by [msbuild using AssemblyInfo properties](https://docs.microsoft.com/en-us/dotnet/core/tools/csproj#assemblyinfo-properties).
-
-Your Library project is now ready to be used on iOS, Android and WebAssembly.
-
-### Dependencies
-If you have a set of existing nuget dependencies in your project:
-- If the dependency **is using .NET Standard 2.0**, there's no need to make any changes, the library will be used as-is. This type of dependency will generally work on other platforms, depending on the type of APIs used, and runtime platform features.
-- If the dependency **is not using .NET Standard 2.0**:
-  - It may already support the iOS and Android targets, in which case it can be used directly
-  - If it does not, the Uno Platform team may have already created an Uno port of the library available on Nuget.
+See also the [guide to working with cross-targeted class libraries](cross-targeted-libraries.md).