diff --git a/docs/architecture/modernize-desktop/deploy-modern-applications.md b/docs/architecture/modernize-desktop/deploy-modern-applications.md index 66a1cbcdd0e4a..16bb61b16ebd1 100644 --- a/docs/architecture/modernize-desktop/deploy-modern-applications.md +++ b/docs/architecture/modernize-desktop/deploy-modern-applications.md @@ -221,4 +221,4 @@ MSIX creates a user interface for installation automatically showing some proper Once you've generated the new MSIX package and moved it to the deployment server, you just have to edit the *.appinstaller* file to reflect these changes, mainly the version and the path to the new MSIX file. The next time the user launches the application, the system is going to detect the change and download the files for the new version in the background. When this is done, installation will execute on new application launch transparently for your user. >[!div class="step-by-step"] ->[Previous](example-migration-core.md) +>[Previous](example-migration.md) diff --git a/docs/architecture/modernize-desktop/example-migration-core.md b/docs/architecture/modernize-desktop/example-migration.md similarity index 61% rename from docs/architecture/modernize-desktop/example-migration-core.md rename to docs/architecture/modernize-desktop/example-migration.md index 47372564b858d..dcb73d102e9eb 100644 --- a/docs/architecture/modernize-desktop/example-migration-core.md +++ b/docs/architecture/modernize-desktop/example-migration.md @@ -1,12 +1,12 @@ --- -title: Example of migrating to .NET Core 3.1 -description: Showing how to migrate a sample applications targeting .NET Framework to .NET Core 3.1. -ms.date: 05/12/2020 +title: Example of migrating to .NET 5 +description: Showing how to migrate a sample applications targeting .NET Framework to .NET 5. +ms.date: 01/19/2021 --- -# Example of migrating to .NET Core 3.1 +# Example of migrating to .NET -In this chapter, we present practical guidelines to help you perform a migration of your existing application from .NET Framework to .NET Core. +In this chapter, we present practical guidelines to help you perform a migration of your existing application from .NET Framework to .NET. We present a well-structured process you can follow and the most important things to consider on each step. @@ -18,9 +18,9 @@ The migration process consists of four sequential steps: 1. **Preparation**: Understand the dependencies the project has to have an idea of what's ahead. In this step, you take the current project into a state that simplifies the startup point for the migration. -2. **Migrate Project File:** .NET Core projects use the new SDK-style project format. Create a new project file with this format or update the one you have to use the SDK style. +2. **Migrate Project File:** .NET projects use the new SDK-style project format. Create a new project file with this format or update the one you have to use the SDK style. -3. **Fix code and build:** Build the code in .NET Core addressing API-level differences between .NET Framework and .NET Core. If needed, update third-party packages to the ones that support .NET Core. +3. **Fix code and build:** Build the code in .NET addressing API-level differences between .NET Framework and .NET. If needed, update third-party packages to the ones that support .NET. 4. **Run and test:** There might be differences that don't show up until run time. So, don't forget to run the application and test that everything works as expected. @@ -28,47 +28,63 @@ The migration process consists of four sequential steps: #### Migrate packages.config file -In a .NET Framework application, all references to external packages are declared in the *packages.config* file. In .NET Core, there's no longer the need to use the *packages.config* file. Instead, use the [PackageReference](../../core/project-sdk/msbuild-props.md#packagereference) property inside the project file to specify the NuGet packages for your app. +In a .NET Framework application, all references to external packages are declared in the *packages.config* file. In .NET, there's no longer the need to use the *packages.config* file. Instead, use the [PackageReference](../../core/project-sdk/msbuild-props.md#packagereference) property inside the project file to specify the NuGet packages for your app. So, you need to transition from one format to another. You can do the update manually, taking the dependencies contained in the *packages.config* file and migrating them to the project file with the `PackageReference` format. Or, you can let Visual Studio do the work for you: right-click on the *packages.config* file and select the **Migrate packages.config to PackageReference** option. -#### Verify every dependency compatibility in .NET Core +#### Verify every dependency compatibility in .NET -Once you've migrated the package references, you must check each reference for compatibility. You can explore the dependencies of each NuGet package your application is using on [nuget.org](https://www.nuget.org/). If the package has .NET Standard dependencies, then it's going to work on .NET Core because .NET Core 3.1 [supports](../../standard/net-standard.md#net-implementation-support) all versions of .NET Standard. The following image shows the dependencies for the `Castle.Windsor` package: +Once you've migrated the package references, you must check each reference for compatibility. You can explore the dependencies of each NuGet package your application is using on [nuget.org](https://www.nuget.org/). If the package has .NET Standard dependencies, then it's going to work on .NET 5.0 because .NET [supports](../../standard/net-standard.md#net-implementation-support) all versions of .NET Standard. The following image shows the dependencies for the `Castle.Windsor` package: ![Screenshot of the NuGet dependencies for the Castle.Windsor package](./media/example-migration-core/nuget-dependencies.png) To check the package compatibility, you can use the tool that offers a more detailed information about versions and dependencies. -Maybe the project is referencing older package versions that don't support .NET Core, but you might find newer versions that do support it. So, updating packages to newer versions is generally a good recommendation. However, you should consider that updating the package version can introduce some breaking changes that would force you to update your code. +Maybe the project is referencing older package versions that don't support .NET, but you might find newer versions that do support it. So, updating packages to newer versions is generally a good recommendation. However, you should consider that updating the package version can introduce some breaking changes that would force you to update your code. -What happens if you don't find a compatible version? What if you just don't want to update the version of a package because of these breaking changes? Don't worry because it's possible to depend on .NET Framework packages from a .NET Core application. Don't forget to test it extensively because it can cause run-time errors if the external package calls an API that isn't available on .NET Core. This is great for when you're using an old package that isn't going to be updated and you can just retarget to work on the .NET Core. +What happens if you don't find a compatible version? What if you just don't want to update the version of a package because of these breaking changes? Don't worry because it's possible to depend on .NET Framework packages from a .NET application. Don't forget to test it extensively because it can cause run-time errors if the external package calls an API that isn't available on .NET. This is great for when you're using an old package that isn't going to be updated and you can just retarget to work on the .NET. #### Check for API compatibility -Since the API surface in .NET Framework and .NET Core is similar but not identical, you must check which APIs are available on .NET Core and which aren't. You can use the .NET Portability Analyzer tool to surface APIs used that aren't present on .NET Core. It looks at the binary level of your app, extracts all the APIs that are called, and then lists which APIs aren't available on your target framework (.NET Core 3.1 in this case). +Since the API surface in .NET Framework and .NET is similar but not identical, you must check which APIs are available on .NET and which aren't. You can use the .NET Portability Analyzer tool to surface APIs used that aren't present on .NET. It looks at the binary level of your app, extracts all the APIs that are called, and then lists which APIs aren't available on your target framework (.NET 5.0 in this case). You can find more information about this tool at: -An interesting aspect of this tool is that it only surfaces the differences from your own code and not code from external packages, which you can't change. Remember you should have updated most of these packages to make them work with .NET Core. +An interesting aspect of this tool is that it only surfaces the differences from your own code and not code from external packages, which you can't change. Remember you should have updated most of these packages to make them work with .NET. -### Migrate project file +### Migrate with Try Convert tool -#### Create the new .NET Core project +The [Try Convert](https://github.com/dotnet/try-convert/releases) tool is a great way to migrate a project. It's a global tool that attempts to upgrade your project file from the old style to the new SDK style, and retargets applicable projects to .NET 5. Once installed, you can run the following commands: -In most of the cases, you'll want to update your existing project to the new .NET Core format. However, you can also create a new project while maintaining the old one. The main drawback from updating the old project is that you lose designer support, which may be important for you. If you want to keep using the designer, you must create a new .NET Core project in parallel with the old one and share assets. If you need to modify UI elements in the designer, you can switch to the old project to do that. And since assets are linked, they'll be updated in the .NET Core project as well. +```dotnetcli +try-convert -p "" +``` + +Or: + +```dotnetcli +try-convert -w "" +``` + +After the tool attempts the conversion, reload your files in Visual Studio to run and test. There's a possibility that Try Convert won't be able to perform the conversion due to the specifics of your project. In that case, you can refer the below steps. + +#### Migrate manually + +1. Create the new .NET project + +In most cases, you'll want to update your existing project to the new .NET format. However, you can also create a new project while maintaining the old one. The main drawback from updating the old project is that you lose designer support, which may be important to you and your development team. If you want to keep using the designer, you must create a new .NET project in parallel with the old one and share assets. If you need to modify UI elements in the designer, you can switch to the old project to do that. And since assets are linked, they'll be updated in the .NET project as well. -The [SDK-style project](../../core/project-sdk/msbuild-props.md) for .NET Core is a lot simpler than .NET Framework's project format. Apart from the previously mentioned `PackageReference` entries, you won't need to do much more. The new project format [includes files with certain extensions by default](../../core/project-sdk/overview.md#default-includes-and-excludes), such as `.cs` and `.xaml` files, without the need to explicitly include them in the project file. +The [SDK-style project](../../core/project-sdk/msbuild-props.md) for .NET is a lot simpler than .NET Framework's project format. Apart from the previously mentioned `PackageReference` entries, you won't need to do much more. The new project format [includes files with certain extensions by default](../../core/project-sdk/overview.md#default-includes-and-excludes), such as `.cs` and `.xaml` files, without the need to explicitly include them in the project file. -#### Assembly.info considerations +#### AssemblyInfo considerations -Attributes are autogenerated on .NET Core projects. If the project contains an *AssemblyInfo.cs* file, the definitions will be duplicated, which will cause compilation conflicts. You can delete the older *AssemblyInfo.cs* file or disable autogeneration by adding the following entry to the .NET Core project file: +Attributes are autogenerated on .NET projects. If the project contains an *AssemblyInfo.cs* file, the definitions will be duplicated, which will cause compilation conflicts. You can delete the older *AssemblyInfo.cs* file or disable autogeneration by adding the following entry to the .NET project file: ```xml - - + + false @@ -90,17 +106,17 @@ Update the versions of the packages you've found to be compatible, as shown in t #### Microsoft.Windows.Compatibility -If your application depends on APIs that aren't available on .NET Core, such as Registry, ACLs, or WCF, you have to include a reference to the `Microsoft.Windows.Compatibility` package to add these Windows-specific APIs. They work on .NET Core but aren't included as they aren't cross-platform. +If your application depends on APIs that aren't available on .NET, such as Registry, ACLs, or WCF, you have to include a reference to the `Microsoft.Windows.Compatibility` package to add these Windows-specific APIs. They work on .NET but aren't included as they aren't cross-platform. There's a tool called API Analyzer () that helps you identify APIs that aren't compatible with your code. #### Use \#if directives -If you need different execution paths when targeting .NET Framework and .NET Core, you should use compilation constants. Add some \#if directives to your code to keep the same code base for both targets. +If you need different execution paths when targeting .NET Framework and .NET, you should use compilation constants. Add some \#if directives to your code to keep the same code base for both targets. -#### Technologies not available on .NET Core +#### Technologies not available on .NET -Some technologies aren't available on .NET Core, such as: +Some technologies aren't available on .NET, such as: * AppDomains * Remoting @@ -108,15 +124,15 @@ Some technologies aren't available on .NET Core, such as: * WCF Server * Windows Workflow -That's why you need to find a replacement for these technologies if you're using them in your application. For more information, see the [.NET Framework technologies unavailable on .NET Core](../../core/porting/net-framework-tech-unavailable.md) article. +That's why you need to find a replacement for these technologies if you're using them in your application. For more information, see the [.NET Framework technologies unavailable on .NET Core and .NET 5+](../../core/porting/net-framework-tech-unavailable.md) article. #### Regenerate autogenerated clients -If your application uses autogenerated code, such as a WCF client, you may need to regenerate this code to target .NET Core. Sometimes, you can find some missing references since they may not be included as part of the default .NET Core assemblies set. Using a tool like , you can easily locate the assembly the missing reference lives in and add it from NuGet. +If your application uses autogenerated code, such as a WCF client, you may need to regenerate this code to target .NET. Sometimes, you can find some missing references since they may not be included as part of the default .NET assemblies set. Using a tool like , you can easily locate the assembly the missing reference lives in and add it from NuGet. #### Rolling back package versions -As a general rule, we've previously stated that you better update every single package version to be compatible with .NET Core. However, you can find that targeting an updated and compatible version of an assembly just doesn't pay off. If the cost of change isn't acceptable, you can consider rolling back package versions keeping the ones you use on .NET Framework. Although they may not be targeting .NET Core, they should work well unless they call some unsupported APIs. +As a general rule, we've previously stated that you better update every single package version to be compatible with .NET. However, you can find that targeting an updated and compatible version of an assembly just doesn't pay off. If the cost of change isn't acceptable, you can consider rolling back package versions keeping the ones you use on .NET Framework. Although they may not be targeting .NET, they should work well unless they call some unsupported APIs. ### Run and test @@ -126,9 +142,9 @@ In this final step, you can find several different issues depending on the compl For example, if you use configuration files (*app.config*), you may find some errors at run time like Configuration Sections not present. Using the `Microsoft.Extensions.Configuration` NuGet package should fix that error. -Another reason for errors is the use of the `BeginInvoke` and `EndInvoke` methods because they aren't supported on .NET Core. They aren't supported on .NET Core because they have a dependency on Remoting, which doesn't exist on .NET Core. To solve this issue, try to use the `await` keyword (when available) or the method. +Another reason for errors is the use of the `BeginInvoke` and `EndInvoke` methods because they aren't supported on .NET. They aren't supported on .NET because they have a dependency on Remoting, which doesn't exist on .NET. To solve this issue, try to use the `await` keyword (when available) or the method. -You can use compatibility analyzers to let you identify APIs and code patterns in your code that can potentially cause problems at run time with .NET Core. Go to and use the .NET API analyzer on your project. +You can use compatibility analyzers to let you identify APIs and code patterns in your code that can potentially cause problems at run time with .NET. Go to and use the .NET API analyzer on your project. ## Migrating a Windows Forms application @@ -145,26 +161,26 @@ If you open the *.csproj* project file, you can see something like this: ![Screenshot of the csproj file contents](./media/example-migration-core/csproj-file.png) -As previously mentioned, .NET Core project has a more compact style and you need to migrate the project structure to the new .NET Core SDK style. +As previously mentioned, .NET project has a more compact style and you need to migrate the project structure to the new .NET SDK style. In the Solution Explorer, right click on the Windows Forms project and select **Unload Project** > **Edit**. Now you can update the .csproj file. You'll delete the entire content and replace it with the following code: ```xml - - - WinExe - netcoreapp3.1 - true - false - + + + WinExe + net5.0-windows + true + false + ``` -Save and reload the project. You're now done updating the project file and the project is targeting the .NET Core. +Save and reload the project. You're now done updating the project file and the project is targeting the .NET. -If you compile the project at this point, you'll find some errors related to the WCF client reference. Since this code is autogenerated, you must regenerate it to target .NET Core. +If you compile the project at this point, you'll find some errors related to the WCF client reference. Since this code is autogenerated, you must regenerate it to target .NET. ![Screenshot of compilation errors on Visual Studio](./media/example-migration-core/winforms-compilation-errors.png) @@ -225,13 +241,13 @@ First, you must update the *.csproj* file to the new SDK style used by .NET Core In this case, delete all the content of the *.csproj* file and replace it with the following code: ```xml - - - WinExe - netcoreapp3.1 - true - false - + + + WinExe + net5.0-windows + true + false + ``` @@ -251,7 +267,7 @@ You can also let Visual Studio help you by right-clicking on the **Dependencies* ![Screenshot of the Reference Manager dialog with the eShop.SqlProvider project selected](./media/example-migration-core/reference-manager.png) -Once you add the missing project reference, the application compiles and runs as expected on .NET Core. +Once you add the missing project reference, the application compiles and runs as expected on .NET. >[!div class="step-by-step"] >[Previous](windows-migration.md) diff --git a/docs/architecture/modernize-desktop/index.md b/docs/architecture/modernize-desktop/index.md index 4fb21bdf26237..afde2265789f6 100644 --- a/docs/architecture/modernize-desktop/index.md +++ b/docs/architecture/modernize-desktop/index.md @@ -1,12 +1,16 @@ --- -title: Modernizing Desktop Apps on Windows 10 with .NET Core 3.1 -description: Learn how to modernize existing desktop apps with .NET Core 3.1 -ms.date: 05/12/2020 +title: Modernizing Desktop Apps on Windows 10 with .NET 5 +description: Learn how to modernize existing desktop apps with .NET 5 +ms.date: 01/06/2021 --- -# Modernizing Desktop Apps on Windows 10 with .NET Core 3.1 +# Modernizing Desktop Apps on Windows 10 with .NET 5 ![Screenshot that shows the modernize desktop apps e-book cover.](./media/modernizing-existing-desktop-apps-ebook-cover.png) +**EDITION v1.0.1** - Updated to .NET 5 + +Refer [changelog](https://aka.ms/desktop-ebook-changelog) for the book updates and community contributions. + PUBLISHED BY Microsoft Developer Division, .NET, and Visual Studio product teams @@ -17,11 +21,11 @@ One Microsoft Way Redmond, Washington 98052-6399 -Copyright © 2020 by Microsoft Corporation +Copyright © 2021 by Microsoft Corporation All rights reserved. No part of the contents of this book may be reproduced or transmitted in any form or by any means without the written permission of the publisher. -This book is provided "as-is" and expresses the author's views and opinions. The views, opinions and information expressed in this book, including URL and other Internet website references, may change without notice. +This book is provided "as-is" and expresses the author's views and opinions. The views, opinions, and information expressed in this book, including URL and other Internet website references, may change without notice. Some examples depicted herein are provided for illustration only and are fictitious. No real association or connection is intended or should be inferred. @@ -69,13 +73,13 @@ Microsoft's approach to modernizing existing applications is to give you the fle ## Who should use the book -We wrote this book for developers and solution architects who want to modernize existing Windows Forms and WPF desktop applications to leverage the benefits of .NET Core and Windows 10. +This book for developers and solution architects who want to modernize existing Windows Forms and WPF desktop applications to leverage the benefits of .NET and Windows 10. You might also find this book useful if you're a technical decision maker, such as an enterprise architect or a development lead or director who wants an overview of the benefits of updating existing desktop applications. ## How to use the book -This book addresses the "why"—why you might want to modernize your existing applications, and the specific benefits you get from using NET Core 3.1 and MSIX to modernize your desktop apps. The content of the book is designed for architects and technical decision makers who want an overview, but who don't need to focus on implementation and technical, step-by-step details. +This book addresses the "why"—why you might want to modernize your existing applications, and the specific benefits you get from using NET and MSIX to modernize your desktop apps. The content of the book is designed for architects and technical decision makers who want an overview, but who don't need to focus on implementation and technical, step-by-step details. Along the different chapters, sample implementation code snippets and screenshots are provided, with chapter 5 devoted to showcase a complete migration process for sample applications. @@ -83,11 +87,11 @@ Along the different chapters, sample implementation code snippets and screenshot This book covers a specific subset of scenarios that are focused on lift-and-shift scenarios, outlining the way to gain the benefits of modernizing without the effort of rewriting code. -This book isn't about developing modern applications with .NET Core from scratch or about getting started with Windows Forms and WPF. It focuses on how you can update existing desktop applications with the latest technologies for desktop development. +This book isn't about developing modern applications with .NET from scratch or about getting started with Windows Forms and WPF. It focuses on how you can update existing desktop applications with the latest technologies for desktop development. ## Samples used in this book -To highlight the necessary steps to perform a modernization, we'll be using a sample application called `eShopModernizing`. This application has two flavors, Windows Forms and WPF, and we'll show a step-by-step process on how to perform the modernization on both of them to .NET Core. +To highlight the necessary steps to perform a modernization, we'll be using a sample application called `eShopModernizing`. This application has two flavors, Windows Forms and WPF, and we'll show a step-by-step process on how to perform the modernization on both of them to .NET. Also, on the GitHub repository for this book, you'll find the results of the process, which you can consult with if you decide to follow the step-by-step tutorial. diff --git a/docs/architecture/modernize-desktop/media/modernizing-existing-desktop-apps-ebook-cover.png b/docs/architecture/modernize-desktop/media/modernizing-existing-desktop-apps-ebook-cover.png index 32a672655c697..f65074a44dd4d 100644 Binary files a/docs/architecture/modernize-desktop/media/modernizing-existing-desktop-apps-ebook-cover.png and b/docs/architecture/modernize-desktop/media/modernizing-existing-desktop-apps-ebook-cover.png differ diff --git a/docs/architecture/modernize-desktop/migrate-modern-applications.md b/docs/architecture/modernize-desktop/migrate-modern-applications.md index 565513dc8f5ad..be63f30e7b9ef 100644 --- a/docs/architecture/modernize-desktop/migrate-modern-applications.md +++ b/docs/architecture/modernize-desktop/migrate-modern-applications.md @@ -1,25 +1,21 @@ --- title: Migrating Modern Desktop applications description: Everything you need to know about the migration process for modern desktop applications. -ms.date: 05/12/2020 +ms.date: 01/19/2021 --- # Migrating Modern Desktop applications -In this chapter, we're exploring the most common issues and challenges you can face when migrating an existing application from .NET Framework to .NET Core. +In this chapter, we're exploring the most common issues and challenges you can face when migrating an existing application from .NET Framework to .NET. A complex desktop application doesn't work in isolation and needs some kind of interaction with subsystems that may reside on the local machine or on a remote server. It will probably need some kind of database to connect as a persistence -storage either locally or remotely. With the raise of Internet and service-oriented architectures, it's common to have your application connected to some sort of service residing on a remote server or in the cloud. You may need to access the machine file system to implement some functionality. Alternatively, maybe you're using a piece of functionality that resides inside -a COM object outside your application, which is a common scenario if, for example, you're integrating Office assemblies in your app. +storage either locally or remotely. With the raise of Internet and service-oriented architectures, it's common to have your application connected to some sort of service residing on a remote server or in the cloud. You may need to access the machine file system to implement some functionality. Alternatively, maybe you're using a piece of functionality that resides inside a COM object outside your application, which is a common scenario if, for example, you're integrating Office assemblies in your app. -Besides, there are differences in the API surface that is exposed by .NET Framework and .NET Core, and some features that are available on .NET Framework aren't available on .NET Core. So, it's important for you to know and take them -into account when planning a migration. +Besides, there are differences in the API surface that is exposed by .NET Framework and .NET, and some features that are available on .NET Framework aren't available on .NET. So, it's important for you to know and take them into account when planning a migration. ## Configuration files -Configuration files offer the possibility to store sets of properties that are read at run time and affect the behavior of our apps, such as where to locate a database or how many times to execute a loop. The beauty of this technique is -that you can modify some aspects of the application without the need to recode and recompile. This comes in handy when, for example, the same app code runs on a development environment with a certain set of configuration values and in -production with a different one. +Configuration files offer the possibility to store sets of properties that are read at run time and affect the behavior of our apps, such as where to locate a database or how many times to execute a loop. The beauty of this technique is that you can modify some aspects of the application without the need to recode and recompile. This comes in handy when, for example, the same app code runs on a development environment with a certain set of configuration values and in production with a different one. ### Configuration on .NET Framework @@ -28,9 +24,9 @@ If you have a working .NET Framework desktop application, chances are you have a Within the .NET Framework infrastructure, there's a hierarchy of configuration files that inherit properties from its parents. You can find a *machine.config* file that defines many properties and configuration sections that can be used or overridden in any descendant configuration file. -### Configuration on .NET Core +### Configuration on .NET -In the .NET Core world, there's no *machine.config* file. And even though you can continue to use the old fashioned namespace, you may consider switching to the modern , which offers a good number of enhancements. +In the .NET world, there's no *machine.config* file. And even though you can continue to use the old fashioned namespace, you may consider switching to the modern , which offers a good number of enhancements. The configuration API supports the concept of configuration provider, which defines the data source to be used to load the configuration. There are different kinds of built-in providers, such as: @@ -50,13 +46,13 @@ The object lets y ### Migrating Configuration files -You can continue to use your existing app.config XML file. However, you could take this opportunity to migrate your configuration to benefit from the several enhancements made on .NET Core. +You can continue to use your existing app.config XML file. However, you could take this opportunity to migrate your configuration to benefit from the several enhancements made on .NET. To migrate from an old-style *app.config* to a new configuration file, you should choose between an XML format and a JSON format. -If you choose XML, the conversion is straightforward. Since the content is the same, just rename the *app.config* file to a file with XML extension. Then, change the code that references AppSettings to use the `ConfigurationBuilder` class. This change should be easy. +If you choose XML, the conversion is straightforward. Since the content is the same, just save the *app.config* file with XML as type. Then, change the code that references AppSettings to use the `ConfigurationBuilder` class. This change should be easy. -If you want to use a JSON format and you don't want to migrate by hand, there's a tool called [dotnet-config2json](https://www.nuget.org/packages/dotnet-config2json/) available on .NET Core that can convert an *app.config* file to a JSON configuration file. +If you want to use a JSON format and you don't want to migrate by hand, there's a tool called [dotnet-config2json](https://www.nuget.org/packages/dotnet-config2json/) available on .NET that can convert an *app.config* file to a JSON configuration file. You may also come across some issues when using configuration sections that were defined in the *machine.config* file. For example, consider the following configuration: @@ -79,9 +75,9 @@ You may also come across some issues when using configuration sections that were ``` -If you take this configuration to a .NET Core, you'll get an exception: +If you take this configuration to a .NET, you'll get an exception: -Unrecognized configuration section system.diagnostics +> Unrecognized configuration section System.Diagnostics This exception occurs because that section and the assembly responsible for handling that section was defined in the *machine.config* file, which now doesn't exist. @@ -105,15 +101,15 @@ The most common examples of database you can find when talking about Windows Des ### ODBC -You can continue to use ODBC on .NET Core since Microsoft is providing the `System.Data.Odbc` library compatible with .NET Standard 2.0. +You can continue to use ODBC on .NET since Microsoft is providing the `System.Data.Odbc` library compatible with .NET Standard 2.0. ### OLE DB -[OLE DB](/previous-versions/windows/desktop/ms722784(v=vs.85)) has been a great way to access various data sources in a uniform manner. But it was based on COM, which is a Windows-only technology, and as such wasn't the best fit for a cross-platform technology such as .NET Core. It's also unsupported in SQL Server versions 2014 and later. For those reasons, OLE DB won't be supported by .NET Core. +[OLE DB](/previous-versions/windows/desktop/ms722784(v=vs.85)) has been a great way to access various data sources in a uniform manner. But it was based on COM, which is a Windows-only technology, and as such wasn't the best fit for a cross-platform technology such as .NET. It's also unsupported in SQL Server versions 2014 and later. For those reasons, OLE DB won't be supported by .NET. ### ADO.NET -You can still use ADO.NET from your existing desktop code on .NET Core. You just need to update some NuGet packages. +You can still use ADO.NET from your existing desktop code on .NET. You just need to update some NuGet packages. ### EF Core vs. EF6 @@ -121,9 +117,9 @@ There are two currently supported versions of Entity Framework (EF), Entity Fram The latest technology released as part of the .NET Framework world is Entity Framework, with 6.4 being the latest version. With the launch of .NET Core, Microsoft also released a new data access stack based on Entity Framework and called Entity Framework Core. -You can use EF 6.4 and EF Core from both .NET Framework and .NET Core. So, what are the decision drivers to help to decide between the two? +You can use EF 6.4 and EF Core from both .NET Framework and .NET. So, what are the decision drivers to help to decide between the two? -EF 6.3 is the first version of EF6 that can run on .NET Core and work cross-platform. In fact, the main goal of this release was to make it easier to migrate existing applications that use EF6 to .NET Core. +EF 6.3 is the first version of EF6 that can run on .NET and work cross-platform. In fact, the main goal of this release was to make it easier to migrate existing applications that use EF6 to .NET. EF Core was designed to provide a developer experience similar to EF6. Most of the top-level APIs remain the same, so EF Core will feel familiar to developers who have used EF6. @@ -132,7 +128,7 @@ For more information, see [Compare EF Core & EF6](/ef/efcore-and-ef6/). The recommendation is to use EF Core if: -* The app needs the capabilities of .NET Core. +* The app needs the capabilities of .NET. * EF Core supports all of the features that the app requires. Consider using EF6 if both of the following conditions are true: @@ -146,7 +142,7 @@ Consider using EF6 if both of the following conditions are true: SQL Server has been one of the databases of choice if you were developing for the desktop some years ago. With the use of in .NET Framework, you could access versions of SQL Server, which encapsulates database-specific protocols. -In .NET Core, you can find a new `SqlClient` class, fully compatible with the one existing in the .NET Framework but located in the library. You just have to add a reference to the [Microsoft.Data.SqlClient](https://www.nuget.org/packages/Microsoft.Data.SqlClient/) NuGet package and do some renaming for the namespaces and everything should work as expected. +In .NET, you can find a new `SqlClient` class, fully compatible with the one existing in the .NET Framework but located in the library. You just have to add a reference to the [Microsoft.Data.SqlClient](https://www.nuget.org/packages/Microsoft.Data.SqlClient/) NuGet package and do some renaming for the namespaces and everything should work as expected. #### Microsoft Access @@ -157,19 +153,19 @@ to Microsoft Access using the library. With the raise of service-oriented architectures, desktop applications began to evolve from a client-server model to the three-layer approach. In the client-server approach, a direct database connection is established from the client holding the business logic usually inside a single EXE file. On the other hand, the three-layer approach establishes an intermediate service layer implementing business logic and database access allowing for better security, scalability, and reusability. Instead of working directly with datasets of data, the layer approach relies in a set of services implementing contracts and types objects as a way to implement data transfer. -If you have a desktop application using a WCF service and you want to migrate it to .NET Core, there are some things to consider. +If you have a desktop application using a WCF service and you want to migrate it to .NET, there are some things to consider. -The first thing is how to resolve the configuration to access the service. Because the configuration is different on .NET Core, you'll need to make some updates in your configuration file. +The first thing is how to resolve the configuration to access the service. Because the configuration is different on .NET, you'll need to make some updates in your configuration file. Second, you'll need to regenerate the service client with the new tools present on Visual Studio 2019. In this step, you must consider activating the generation of the synchronous operations to make the client compatible with your existing code. -After the migration, if you find that there are libraries you need that aren't present on .NET Core, you can add a reference to the [Microsoft.Windows.Compatibility](https://www.nuget.org/packages/Microsoft.Windows.Compatibility) NuGet package and see if the missing functions are there. +After the migration, if you find that there are libraries you need that aren't present on .NET, you can add a reference to the [Microsoft.Windows.Compatibility](https://www.nuget.org/packages/Microsoft.Windows.Compatibility) NuGet package and see if the missing functions are there. -If you're using the class to perform web service calls, you may find some differences on .NET Core. The recommendation is to use the System.Net.Http.HttpClient instead. +If you're using the class to perform web service calls, you may find some differences on .NET. The recommendation is to use the System.Net.Http.HttpClient instead. ## Consuming a COM Object -Currently, there's no way to add a reference to a COM object from Visual Studio 2019 to use with .NET Core. So, you have to manually modify the project file. +Currently, there's no way to add a reference to a COM object from Visual Studio 2019 to use with .NET. So, you have to manually modify the project file. Insert a `COMReference` structure inside the project file like in the following example: @@ -188,7 +184,7 @@ Insert a `COMReference` structure inside the project file like in the following ## More things to consider -Several technologies available to .NET Framework libraries aren't available for .NET Core. If your code relies on some of these technologies, consider the alternative approaches outlined in this section. +Several technologies available to .NET Framework libraries aren't available for .NET Core or .NET 5. If your code relies on some of these technologies, consider the alternative approaches outlined in this section. The [Windows Compatibility Pack](../../core/porting/windows-compat-pack.md) provides access to APIs that were previously available only for .NET Framework. It can be used on .NET Core and .NET Standard projects. @@ -199,11 +195,11 @@ For more information on API compatibility, you can find documentation about brea Application domains (AppDomains) isolate apps from one another. AppDomains require runtime support and are expensive. Creating additional app domains isn't supported. For code isolation, we recommend separate processes or using containers as an alternative. For the dynamic loading of assemblies, we recommend the new  class. -To make code migration from .NET Framework easier, .NET Core exposes some of the AppDomain API surface. Some of the APIs function normally (for example, ), some members do nothing (for example, ), and some of them throw (for example, ). +To make code migration from .NET Framework easier, .NET exposes some of the `AppDomain` API surface. Some of the APIs function normally (for example, ), some members do nothing (for example, ), and some of them throw (for example, ). ### Remoting -.NET Remoting was used for cross-AppDomain communication, which is no longer supported. Also, Remoting requires runtime support, which is expensive to maintain. For these reasons, .NET Remoting isn't supported on .NET Core. +.NET Remoting was used for cross-AppDomain communication, which is no longer supported. Also, Remoting requires runtime support, which is expensive to maintain. For these reasons, .NET Remoting isn't supported on .NET. For communication across processes, you should consider inter-process communication (IPC) mechanisms as an alternative to Remoting, such as the or the class. @@ -211,7 +207,7 @@ Across machines, use a network-based solution as an alternative. Preferably, use ### Code Access Security (CAS) -Sandboxing, which relies on the runtime or the framework to constrain which resources a managed application or library uses or runs, isn't supported on .NET Core. +Sandboxing, which relies on the runtime or the framework to constrain which resources a managed application or library uses or runs, isn't supported on .NET. Use security boundaries that are provided by the operating system, such as virtualization, containers, or user accounts for running processes with the minimum set of privileges. @@ -222,5 +218,5 @@ Similar to CAS, Security Transparency separates sandboxed code from security cri Use security boundaries that are provided by the operating system, such as virtualization, containers, or user accounts for running processes with the least set of privileges. >[!div class="step-by-step"] ->[Previous](whats-new-dotnet-core.md ) +>[Previous](whats-new-dotnet.md ) >[Next](windows-migration.md) diff --git a/docs/architecture/modernize-desktop/toc.yml b/docs/architecture/modernize-desktop/toc.yml index 196687dede070..4ae5cdfad2e0a 100644 --- a/docs/architecture/modernize-desktop/toc.yml +++ b/docs/architecture/modernize-desktop/toc.yml @@ -1,15 +1,15 @@ -- name: Modernizing desktop apps on Windows 10 with .NET Core 3.1 +- name: Modernizing desktop apps on Windows 10 with .NET 5 href: index.md items: - name: Why modern desktop applications href: why-modern-applications.md - - name: "What's new with .NET Core for Desktop?" - href: whats-new-dotnet-core.md + - name: "What's new with .NET for Desktop?" + href: whats-new-dotnet.md - name: Migrating Modern Desktop Applications href: migrate-modern-applications.md - name: Windows 10 Migration href: windows-migration.md - - name: Example of migrating to .NET Core 3.1 - href: example-migration-core.md + - name: Example of migrating to .NET 5 + href: example-migration.md - name: Deploying Modern Desktop Applications href: deploy-modern-applications.md diff --git a/docs/architecture/modernize-desktop/whats-new-dotnet-core.md b/docs/architecture/modernize-desktop/whats-new-dotnet.md similarity index 79% rename from docs/architecture/modernize-desktop/whats-new-dotnet-core.md rename to docs/architecture/modernize-desktop/whats-new-dotnet.md index ca58b224b50bf..e7aee1e0a6906 100644 --- a/docs/architecture/modernize-desktop/whats-new-dotnet-core.md +++ b/docs/architecture/modernize-desktop/whats-new-dotnet.md @@ -1,12 +1,12 @@ --- -title: What's new with .NET Core for Desktop? -description: Learn about .NET Core, differences between .NET Core and .NET Framework, and the new features that were added. -ms.date: 05/12/2020 +title: What's new with .NET for Desktop? +description: Learn about .NET, differences between .NET and .NET Framework, and the new features that were added. +ms.date: 12/29/2020 --- -# What's new with .NET Core for Desktop? +# What's new with .NET for Desktop? -Starting with .NET Core 3.0, .NET Core supports Windows Forms and WPF. So, now you have a choice between .NET Framework and .NET Core for your desktop applications. This chapter will describe what is .NET Core and what are its benefits for desktop applications. +Starting with .NET Core 3.0, .NET supports Windows Forms and WPF. So, now you have a choice between .NET Framework and .NET for your desktop applications. This chapter will describe what is .NET and what are its benefits for desktop applications. ## The motivation behind .NET Core @@ -50,11 +50,21 @@ The benefits of .NET Core come from these three characteristics: Starting with .NET Core 3.0, besides the existing support for web and cloud, there's also support for desktop, IoT, and AI domains. The goal for this framework is impressive: to target every type of .NET development present and future. Microsoft plans to complete this vision with .NET 5 at the end of 2020. The "Core" name was removed to reinforce its uniqueness in the .NET world. +## .NET 5 is .NET Core vNext + +.NET 5 is the next step forward with .NET Core. The .NET 5.0 aims to improve .NET in a few key ways: + +- Produce a single .NET runtime and framework that can be used everywhere and that has uniform runtime behaviors and developer experiences. +- Expand the capabilities of .NET by taking the best of .NET Core, .NET Framework, Xamarin and Mono. +- Build that product out of a single code-base that developers (Microsoft and the community) can work on and expand together and that improves all scenarios. + +This new release and direction are a game-changer for .NET. With .NET 5, your code and project files will look and feel the same no matter which type of app you're building. You’ll have access to the same runtime, APIs, and language capabilities with each app. This includes new [performance improvements](https://devblogs.microsoft.com/dotnet/performance-improvements-in-net-5/) that get committed to the runtime, practically daily. For more details refer [What's new in .NET 5](https://docs.microsoft.com/dotnet/core/dotnet-five). + ![All domains of .NET 5](./media/whats-new-dotnet-core/all-domains-of-dotnet5.png) -## .NET Framework vs. .NET Core +## .NET Framework vs. .NET 5 -So now that you understand the relevance of .NET Core inside the Microsoft strategy for .NET, you might be wondering what happens with .NET Framework. You could be asking questions like: do you have to abandon it? Is it going to disappear? What are my choices to modernize the applications I have on .NET Framework? +So now that you understand the relevance of .NET, you might be wondering what happens with .NET Framework. You could be asking questions like: do you have to abandon it? Is it going to disappear? What are my choices to modernize the applications I have on .NET Framework? In 2019 the last version of the **.NET Framework - 4.8** was released. It included three major improvements for desktop applications: @@ -64,15 +74,15 @@ In 2019 the last version of the **.NET Framework - 4.8** was released. It includ Since .NET Framework is installed on millions of machines, Microsoft will continue to support it but won't add new features. -.NET Core is the open-source, cross-platform, and fast-moving version of .NET. Because of its side-by-side nature, it can take changes without the fear of breaking any application. This means that .NET Core will get new APIs and language features over time that .NET Framework won't. Also, **.NET Core** already has features that were impossible for .NET Framework, such as: +.NET 5 is the open-source, cross-platform, and fast-moving version of .NET family. Because of its side-by-side nature, it can take changes without the fear of breaking any application. This means that .NET will get new APIs and language features over time that .NET Framework won't. Also, **.NET** already has features that were impossible for .NET Framework, such as: -- **Side-by-side versions of .NET supporting Windows Forms and WPF**: This solves the problem of side effects when updating the machine's framework version. Multiple versions of .NET Core can be installed on the same machine and each application specifies which version of .NET Core it should use. Even more, now you can develop and run Windows Forms and WPF on top of .NET Core. -- **Embed .NET directly into an application**: You can deploy .NET Core as part of your application package. This enables you to take advantage of the latest version, features, and APIs without having to wait for a specific version to be installed on the machine. -- **Take advantage of .NET Core features**: .NET Core is the fast-moving, open-source version of .NET. Its side-by-side nature enables fast introduction of new innovative APIs and Base Class Libraries (BCL) improvements without the risk of breaking compatibility. Now Windows Forms and WPF applications can take advantage of the latest .NET Core features, which also includes more fundamental fixes for runtime performance, high-DPI support, and so on. +- **Side-by-side versions of .NET supporting Windows Forms and WPF**: This solves the problem of side effects when updating the machine's framework version. Multiple versions of .NET can be installed on the same machine and each application specifies which version of .NET it should use. Even more, now you can develop and run Windows Forms and WPF on top of .NET. +- **Embed .NET directly into an application**: You can deploy .NET as part of your application package. This enables you to take advantage of the latest version, features, and APIs without having to wait for a specific version to be installed on the machine. +- **Take advantage of .NET features**: .NET Core is the fast-moving, open-source version of .NET. Its side-by-side nature enables fast introduction of new innovative APIs and Base Class Libraries (BCL) improvements without the risk of breaking compatibility. Now Windows Forms and WPF applications can take advantage of the latest .NET features, which also includes more fundamental fixes for runtime performance, high-DPI support, and so on. -An essential part of the roadmap for Microsoft was to ease developers to move applications to .NET Core and in future to .NET 5. But if you have existing .NET Framework applications, you shouldn't feel pressured to move to .NET Core. .NET Framework will be fully supported and will always be a part of Windows. However, if you want to use the newest language features and APIs in the future, you'll need to move your applications to .NET Core. +An essential part of the roadmap for Microsoft was to ease developers to move applications to .NET Core and in later to .NET 5. But if you have existing .NET Framework applications, you shouldn't feel pressured to move to .NET 5. .NET Framework will be fully supported and will always be a part of Windows. However, if you want to use the newest language features and APIs in the future, you'll need to move your applications to .NET. -For your brand-new desktop applications, we recommend starting directly on .NET Core. It's lightweight and cross platform, runs side by side, has high performance, and fits perfectly on containers and microservices architectures. +For your brand-new desktop applications, we recommend starting directly on .NET 5. It's lightweight and cross platform, runs side by side, has high performance, and fits perfectly on containers and microservices architectures. ![You can update your .NET Framework applications using the latest .NET Framework version or port your applications to .NET Core](./media/whats-new-dotnet-core/framework-vs-core.png) diff --git a/docs/architecture/modernize-desktop/why-modern-applications.md b/docs/architecture/modernize-desktop/why-modern-applications.md index 31fc40fe565da..7931d6de58200 100644 --- a/docs/architecture/modernize-desktop/why-modern-applications.md +++ b/docs/architecture/modernize-desktop/why-modern-applications.md @@ -1,7 +1,7 @@ --- title: Why modern desktop applications description: Learn about desktop technologies such as Windows Forms, WPF, and UWP in the modern world. -ms.date: 09/16/2019 +ms.date: 12/29/2020 --- # Why modern desktop applications @@ -9,7 +9,7 @@ ms.date: 09/16/2019 ### A story of one company -Back in early 2000s, one multinational company started developing a distributed desktop solution to exchange information between different branches of the company and execute optimized operations on centralized units. They have chosen a brand-new framework called Windows Forms (also known as WinForms) for their application development. Over the years, the project evolved into a mature, well tested, and time-proven application with hundreds of thousands of lines of code. Time passed and .NET Framework 2.0 is no longer the hot new technology. The developers who are working on this application are facing a dilemma. They'd like to use the latest stack of technologies in their development and have their application look and "feel" modern. At the same time, they don't want to throw away the great product they have built over 15 years and rewrite the entire application from scratch. +Back in the early 2000s, one multinational company started developing a distributed desktop solution to exchange information between different branches of the company and execute optimized operations on centralized units. They have chosen a brand-new framework called Windows Forms (also known as WinForms) for their application development. Over the years, the project evolved into a mature, well tested, and time-proven application with hundreds of thousands of lines of code. Time passed and .NET Framework 2.0 is no longer the hot new technology. The developers who are working on this application are facing a dilemma. They'd like to use the latest stack of technologies in their development and have their application look and "feel" modern. At the same time, they don't want to throw away the great product they have built over 15 years and rewrite the entire application from scratch. ### Your story @@ -19,19 +19,19 @@ You might find yourself in the same boat, where you have mature Windows Forms or Before the raise of the Internet, desktop applications were the main approach to build software systems. Developers could choose any programming language, such as COBOL, Fortran, VB6, or C++. But where they developed small tools or complex distributed architectures, they were all desktop applications. -Then, Internet technologies started shocking the development world and winning over more and more engineers with advantages like easy deployment and simplified distribution processes. The fact that once a web application was deployed to production all users got automatic updates made a huge impact on the software agility. +Then, Internet technologies started shocking the development world and winning over more engineers with advantages like easy deployment and simplified distribution processes. The fact that once a web application was deployed to production all users got automatic updates made a huge impact on the software agility. -However, the Internet infrastructure, underlying protocols, and standards like HTTP and HTML weren't designed for building complex applications. In fact, the major development effort back then was aiming just one goal: to give web applications same capabilities that desktop applications have, such as fast data input and state management. +However, the Internet infrastructure, underlying protocols, and standards like HTTP and HTML weren't designed for building complex applications. In fact, the major development effort back then was aiming just one goal: to give web applications the same capabilities that desktop applications have, such as fast data input and state management. Even though web and mobile applications have grown at an incredible pace, for certain tasks desktop applications still hold the number one place in terms of efficiency and performance. That explains why there are millions of developers who are building their projects with WPF and WinForms and the amount of those applications is constantly growing. Here are some reasons for choosing desktop applications in your development: -- Desktop apps have better interaction with user's PC. -- The performance of desktop applications for complex calculations is much higher than performance of web applications. -- Running custom logic on the client side is possible but much harder with a web application. +- Desktop apps have better interaction with the user's PC. +- The performance of desktop applications for complex calculations is much higher than the performance of web applications. +- Running custom logic on the client-side is possible but much harder with a web application. - Using multithreading is easier and more efficient in a desktop application. -- The learning curve for designing user interfaces (UIs) isn't steep. And for WinForms, it's completely intuitive with drag-and-drop experience of the Windows Forms designer. +- The learning curve for designing user interfaces (UIs) isn't steep. And for WinForms, it's intuitive with the drag-and-drop experience of the Windows Forms designer. - It's easy to start coding and testing your algorithms without the need to set up a server infrastructure or to care about connectivity problems, firewalls, and browser compatibility. - Debugging is powerful as compared to web debugging. - Access to hardware devices, such as camera, Bluetooth, or card readers, is easy. @@ -96,7 +96,7 @@ UWP contains a presentation framework that is XAML-based, like WPF, but it has s ## A tale of two platforms -In the last 20 years, while UI desktop technologies were growing and following the path from Windows Forms to UWP, the hardware was also evolving from heavy weight PC units with small CRT monitors to high-DPI monitors and lightweight tablets and phones with different data input techniques like Touch and Ink. These changes resulted in creating two different concepts: a Desktop Application and a Modern Application. A Modern Application is one that considers different device form factors, various input and output methods, and leverages modern desktop features while running on a sandboxed execution model. The (traditional) Desktop Application, on the other hand, is an application that needs a solid UI with high density of controls that is best operated with a mouse and a keyboard. +In the last 20 years, while UI desktop technologies were growing and following the path from Windows Forms to UWP, the hardware was also evolving from heavy weight PC units with small CRT monitors to high-DPI monitors and lightweight tablets and phones with different data input techniques like Touch and Ink. These changes resulted in creating two different concepts: a Desktop Application and a Modern Application. A Modern Application is one that considers different device form factors, various input and output methods, and leverages modern desktop features while running on a sandboxed execution model. The (traditional) Desktop Application, on the other hand, is an application that needs a solid UI with a high density of controls that is best operated with a mouse and a keyboard. The following table describes the differences between the two concepts: @@ -137,14 +137,14 @@ This path will show you how you can leverage modern desktop features into your e Modern development cycles have stressed out to provide agility on how new versions of applications are deployed to every single user. Since Windows Forms and WPF applications are based on a particular version of the .NET Framework that must be present on the machine, they can't take advantage of new .NET Framework version features without the intervention of the IT people with the risk of having side effects for other apps running on the same machine. It has limited the innovation pace for developers forcing them to stay on outdated versions of the .NET Framework. -Since the launch of .NET Core 3.0, you can leverage a new approach of deploying multiple versions of .NET Core side by side and specifying which version of .NET Core each application should target. This way, you can use newest features in one application while being confident you aren't going to break any other applications. +Since the launch of .NET Core 3.0, you can leverage a new approach of deploying multiple versions of .NET side by side and specifying which version of .NET each application should target. This way, you can use the newest features in one application while being confident you aren't going to break any other applications. ### Installation -Desktop applications always rely on some sort of installation process before the user can start using them. This fact brought into the game a set of technologies, from MSI and ClickOnce to custom installers or even XCOPY deployment. Any of these methods deals with delicate problems because applications need a way to access shared resources on the machine. Sometimes installation needs to access the Registry to insert or update new Key Values, sometimes to update shared DLLs referenced by the main application. This causes a continuous headache for users, creating this perception that once you install some application, your computer will never be the same, even if you uninstall it afterwards. +Desktop applications always rely on some sort of installation process before the user can start using them. This fact brought into the game a set of technologies, from MSI and ClickOnce to custom installers or even XCOPY deployment. Any of these methods deals with delicate problems because applications need a way to access shared resources on the machine. Sometimes installation needs to access the Registry to insert or update new Key Values, sometimes to update shared DLLs referenced by the main application. This behavior causes a continuous headache for users, creating this perception that once you install some application, your computer will never be the same, even if you uninstall it afterwards. -In this book, we'll introduce a new way of installing applications with MSIX that solves the problem described earlier. You'll learn how you can easily set up a packaging, installation, and updates for your application. +In this book, we'll introduce a new way of installing applications with MSIX that solves the problem described earlier. You'll learn how you can easily set up packaging, installation, and updates for your application. >[!div class="step-by-step"] >[Previous](index.md) ->[Next](whats-new-dotnet-core.md) +>[Next](whats-new-dotnet.md) diff --git a/docs/architecture/modernize-desktop/windows-migration.md b/docs/architecture/modernize-desktop/windows-migration.md index 2bd8813dcc83e..427bd32c23bf0 100644 --- a/docs/architecture/modernize-desktop/windows-migration.md +++ b/docs/architecture/modernize-desktop/windows-migration.md @@ -1,7 +1,7 @@ --- title: Windows 10 migration description: Deep dive in Windows 10 features such as packaging and XAML Islands. -ms.date: 09/16/2019 +ms.date: 12/29/2020 --- # Windows 10 migration @@ -14,9 +14,9 @@ With the release of Windows 10, Microsoft introduced many innovations to support - Use a pen to draw or handwrite text that is automatically recognized and digitalized. - Run locally customized AI models built on the cloud using WinML. -All these features are enabled for Windows developers through Windows Runtime (WinRT) libraries. You can take advantage of these features in your existing desktop apps because the libraries are exposed to both the .NET Framework and .NET Core as well. You can even modernize your UI with the use of XAML Islands and improve the visuals and behavior of your apps according to the times. +All these features are enabled for Windows developers through Windows Runtime (WinRT) libraries. You can take advantage of these features in your existing desktop apps because the libraries are exposed to both the .NET Framework and .NET as well. You can even modernize your UI with the use of XAML Islands and improve the visuals and behavior of your apps according to the times. -One important thing to note here is that you don't need to abandon .NET Framework technology to follow this modernization path. You can safely stay on there and have all the benefits of Windows 10 without the pressure to migrate to .NET Core. So, you get both the power and the flexibility to choose your modernization path. +One important thing to note here is that you don't need to abandon .NET Framework technology to follow this modernization path. You can safely stay on there and have all the benefits of Windows 10 without the pressure to migrate to .NET. So, you get both the power and the flexibility to choose your modernization path. ## WinRT APIs @@ -272,7 +272,7 @@ To see a walkthrough about how to use XAML Islands, see: A XAML custom control is a control (or user control) created by you or by third parties (including WinUI 2.x controls). To host a custom UWP control in a Windows Forms or WPF app, you'll need: -- To use the `WindowsXamlHost` UWP control in your .NET Core 3.x app. +- To use the `WindowsXamlHost` UWP control in your .NET app. - To create a UWP app project that defines a `XamlApplication` object. Your WPF or Windows Forms project must have access to an instance of the `Microsoft.Toolkit.Win32.UI.XamlHost.XamlApplication` class provided by the Windows Community Toolkit. This object acts as a root metadata provider for loading metadata for custom UWP XAML types in assemblies in the current directory of your application. The recommended way to do this is to add a Blank @@ -326,7 +326,7 @@ WinUI 3 will address this critical feedback adding **WinUI in desktop apps**. Th Within this aggregation, WinUI 3 will let developers easily mix and match the right combination of: * App model: UWP, Win32 -* Platform: .NET Core or Native +* Platform: .NET or Native * Language: .NET (C\#, Visual Basic), standard C++ * Packaging: MSIX, AppX for the Microsoft Store, unpackaged * Interop: use WinUI 3 to extend existing WPF, WinForms, and MFC apps using WinUI XAML Islands. @@ -335,4 +335,4 @@ If you want to know more details, Microsoft is sharing this roadmap in [!div class="step-by-step"] >[Previous](migrate-modern-applications.md) ->[Next](example-migration-core.md) +>[Next](example-migration.md) diff --git a/docs/architecture/toc.yml b/docs/architecture/toc.yml index 50577b22ab94a..0304995a7e05b 100644 --- a/docs/architecture/toc.yml +++ b/docs/architecture/toc.yml @@ -15,7 +15,7 @@ href: containerized-lifecycle/ - name: Modernize existing .NET applications with Azure cloud and Windows Containers href: modernize-with-azure-containers/ - - name: "Modernizing desktop apps on Windows 10 with .NET Core 3.1" + - name: "Modernizing desktop apps on Windows 10 with .NET 5" href: modernize-desktop/ - name: ".NET Microservices: Architecture for containerized .NET applications" href: microservices/