From a2bb1043acb9659e0e0fe7b055b88a492fc25404 Mon Sep 17 00:00:00 2001 From: Stephen Bonikowsky Date: Thu, 10 Jun 2021 09:43:32 -0700 Subject: [PATCH 1/9] Update with the minimal changes needed to align existing content to the new TOC. --- docs/fundamentals/toc.yml | 74 +++++++++++++++++++++++---------------- 1 file changed, 44 insertions(+), 30 deletions(-) diff --git a/docs/fundamentals/toc.yml b/docs/fundamentals/toc.yml index b56846abb7045..a6eeeebd2d484 100644 --- a/docs/fundamentals/toc.yml +++ b/docs/fundamentals/toc.yml @@ -2456,34 +2456,48 @@ items: items: - name: Overview href: ../core/porting/index.md - - name: .NET Upgrade Assistant tool + - name: General Information items: - - name: Overview - href: ../core/porting/upgrade-assistant-overview.md - - name: Windows Presentation Foundation - href: ../core/porting/upgrade-assistant-wpf-framework.md - - name: Windows Forms - href: ../core/porting/upgrade-assistant-winforms-framework.md - - name: ASP.NET Core - href: ../core/porting/upgrade-assistant-aspnetmvc.md - - name: Breaking changes - displayName: app compatibility - href: ../core/compatibility/ - - name: Analyze third-party dependencies - href: ../core/porting/third-party-deps.md - - name: Port libraries - href: ../core/porting/libraries.md - - name: Organize projects for .NET - href: ../core/porting/project-structure.md - - name: Unavailable technologies - href: ../core/porting/net-framework-tech-unavailable.md?toc=/dotnet/fundamentals/toc.json&bc=/dotnet/breadcrumb/toc.json - - name: Use the Windows Compatibility Pack - href: ../core/porting/windows-compat-pack.md - - name: Port Windows Forms projects - href: /dotnet/desktop/winforms/migration/?view=netdesktop-5.0 - - name: Port WPF projects - href: /dotnet/desktop/wpf/migration/convert-project-from-net-framework?view=netdesktop-5.0 - - name: Port C++/CLI projects - href: ../core/porting/cpp-cli.md - - name: Choose between .NET 5 and .NET Framework for server apps - href: ../standard/choosing-core-framework-server.md + - name: About .NET + href: ../standard/choosing-core-framework-server.md + - name: .NET Upgrade Assistant tool + items: + - name: Overview + href: ../core/porting/upgrade-assistant-overview.md + - name: Windows Presentation Foundation + href: ../core/porting/upgrade-assistant-wpf-framework.md + - name: Windows Forms + href: ../core/porting/upgrade-assistant-winforms-framework.md + - name: ASP.NET Core + href: ../core/porting/upgrade-assistant-aspnetmvc.md + - name: Breaking changes + displayName: app compatibility + href: ../core/compatibility/ + - name: Pre-Migration + items: + - name: Analyze & Asses the portability of your project + items: + - name: Tooling Requirements + href: ../core/porting/tooling-requirements.md + - name: Unsupported Dependencies + href: ../core/porting/third-party-deps.md + - name: Use the Windows Compatibility Pack + href: ../core/porting/windows-compat-pack.md + - name: Unavailable technologies + href: ../core/porting/net-framework-tech-unavailable.md?toc=/dotnet/fundamentals/toc.json&bc=/dotnet/breadcrumb/toc.json + - name: Unsupported APIs + href: ../core/porting/unsupported-apis.md + - name: Update .NET Framework target version + href: ../core/porting/update-netfx-tfm-version.md + - name: Migration + items: + - name: Create a porting plan + href: ../core/porting/create-a-porting-plan.md + - name: Application Porting Guides + items: + - name: Windows Forms + href: /dotnet/desktop/winforms/migration/?view=netdesktop-5.0 + - name: Windows Presentation Foundation + href: /dotnet/desktop/wpf/migration/convert-project-from-net-framework?view=netdesktop-5.0 + - name: Port C++/CLI projects + href: ../core/porting/cpp-cli.md From 0d830c94d28eb44c57387e822f8b22f352608b15 Mon Sep 17 00:00:00 2001 From: Stephen Bonikowsky Date: Thu, 10 Jun 2021 10:43:34 -0700 Subject: [PATCH 2/9] Adding the new page 'tooling-requirements.md' and adding initial content to resolve #24568 --- docs/core/porting/tooling-requirements.md | 34 +++++++++++++++++++++++ 1 file changed, 34 insertions(+) create mode 100644 docs/core/porting/tooling-requirements.md diff --git a/docs/core/porting/tooling-requirements.md b/docs/core/porting/tooling-requirements.md new file mode 100644 index 0000000000000..8b8f957a4a932 --- /dev/null +++ b/docs/core/porting/tooling-requirements.md @@ -0,0 +1,34 @@ +--- +title: Tooling requirements +description: Learn about the versioning relationship between the .NET SDK and MSBuild/VS. +author: stebon +ms.date: 06/10/2021 +--- +Understanding the versioning of the SDK and how it relates to Visual Studio and MSBuild can frequently be confusing. MSBuild versions with VS but is also included in the SDK. The SDK has a minimum version of MSBuild that it works with and it won't load in a VS that is older than it supports. + +#Versioning +The first part of the SDK matches the .NET version that it includes, runs on, and targets by default. The feature band starts at 1 and increases for each quarterly VS minor release. The patch version increments with each month's servicing updates. + +For example, 5.0.203 ships with .NET 5.0, is the 2nd minor VS release since 5.0.100 first came out, and is the 3rd patch since 5.0.200 released. + +##Lifecycle +The support timeframe for the SDK typically matches the VS it's included in. + +| SDK Version | MSBuild/VS version | Minimum required MSBuild/VS Version | Ship date | Lifecycle | +|------------------|--------------------|-------------------------------------|--------------|-----------| +| 2.1.5xx | 15.9 | 15.3 | Nov ‘18 | Aug ‘21* | +| 2.1.8xx | 16.2 (No VS) | 16.0 | July ‘19 | Aug ‘21 | +| 3.1.1xx | 16.4 | 16.3 | Dec ‘19 | Dec ‘22 | +| 3.1.4xx | 16.7 | 16.7 | Aug ‘20 | Dec ‘22 | +| 5.0.1xx | 16.8 | 16.8 | November ‘20 | Mar ‘21 | +| 5.0.2xx | 16.9 | 16.8 | March 21 | Aug ‘22 | +| 5.0.3xx | 16.10 | 16.8 | May 21 | Aug ‘21 | +| 5.0.4xx | 16.11 | 16.8 | Aug 21 | Feb ‘22* | +| 6.0.100-preview4 | 16.10 (No VS) | 16.10-preview3 | 05/25/21 | N/A | +| 6.0.100-preview5 | 17.0-preview 1 | 16.10 | June | N/A | +| 6.0.100 | 17.0 | 16.10** | November | + +*MSbuild/VS supported for longer +**The goal is on .NET 6 release day to be functional with at most 16.11 (so customers aren't forced to update VS versions on day 0) + +We've tried to reduce the frequency that we make breaking changes but cannot guarantee that each new major SDK version won't require at least some upgrade of the version of VS/MSBuild so that should be expected at least once a year. From 0dd1b9f969bde111188b00efbe2ac743dbab4044 Mon Sep 17 00:00:00 2001 From: Stephen Bonikowsky Date: Thu, 10 Jun 2021 11:54:32 -0700 Subject: [PATCH 3/9] Created additional pages needed for Phase 1 modifying the TOC as needed. --- docs/core/porting/porting-approaches.md | 85 +++++++++++++++++++ .../porting/premigration-needed-changes.md | 28 ++++++ docs/core/porting/unsupported-apis.md | 10 +++ docs/fundamentals/toc.yml | 10 ++- 4 files changed, 130 insertions(+), 3 deletions(-) create mode 100644 docs/core/porting/porting-approaches.md create mode 100644 docs/core/porting/premigration-needed-changes.md create mode 100644 docs/core/porting/unsupported-apis.md diff --git a/docs/core/porting/porting-approaches.md b/docs/core/porting/porting-approaches.md new file mode 100644 index 0000000000000..e609138c3c5d4 --- /dev/null +++ b/docs/core/porting/porting-approaches.md @@ -0,0 +1,85 @@ +--- +title: Porting approaches +description: Create a porting plan that best reflects your project and context. +author: stebon +ms.date: 06/10/2021 +--- + +### Deal primarily with the compiler + +This approach works well for small projects or projects that don't use many .NET Framework APIs. The approach is simple: + +01. Optionally, run ApiPort on your project. If you run ApiPort, gain knowledge from the report on issues you'll need to address. +01. Copy all of your code over into a new .NET project. +01. While referring to the portability report (if generated), solve compiler errors until the project fully compiles. + +Although it's unstructured, this code-focused approach often resolves issues quickly. A project that contains only data models might be an ideal candidate for this approach. + +### Stay on the .NET Framework until portability issues are resolved + +This approach might be the best if you prefer to have code that compiles during the entire process. The approach is as follows: + +01. Run ApiPort on a project. +01. Address issues by using different APIs that are portable. +01. Take note of any areas where you're prevented from using a direct alternative. +01. Repeat the prior steps for all projects you're porting until you're confident each is ready to be copied over into a new .NET project. +01. Copy the code into a new .NET project. +01. Work out any issues where you noted that a direct alternative doesn't exist. + +This careful approach is more structured than simply working out compiler errors, but it's still relatively code-focused and has the benefit of always having code that compiles. The way you resolve certain issues that couldn't be addressed by just using another API varies greatly. You may find that you need to develop a more comprehensive plan for certain projects, which is covered in the next approach. + +### Develop a comprehensive plan of attack + +This approach might be best for larger and more complex projects, where restructuring code or completely rewriting certain areas of code might be necessary to support .NET. The approach is as follows: + +01. Run ApiPort on a project. +01. Understand where each non-portable type is used and how that affects overall portability. + + - Understand the nature of those types. Are they small in number but used frequently? Are they large in number but used infrequently? Is their use concentrated, or is it spread throughout your code? + - Is it easy to isolate code that isn't portable so that you can deal with it more effectively? + - Do you need to refactor your code? + - For those types that aren't portable, are there alternative APIs that accomplish the same task? For example, if you're using the class, use the class instead. + - Are there different portable APIs available to accomplish a task, even if it's not a drop-in replacement? For example, if you're using to parse XML but don't require XML schema discovery, you could use APIs and implement parsing yourself instead of relying on an API. + +01. If you have assemblies that are difficult to port, is it worth leaving them on .NET Framework for now? Here are some things to consider: + + - You may have some functionality in your library that's incompatible with .NET because it relies too heavily on .NET Framework or Windows-specific functionality. Is it worth leaving that functionality behind for now and releasing a temporary .NET version of your library with fewer features until resources are available to port the features? + - Would a refactor help? + +01. Is it reasonable to write your own implementation of an unavailable .NET Framework API? + + You could consider copying, modifying, and using code from the [.NET Framework reference source](https://github.com/Microsoft/referencesource). The reference source code is licensed under the [MIT License](https://github.com/Microsoft/referencesource/blob/master/LICENSE.txt), so you have significant freedom to use the source as a basis for your own code. Just be sure to properly attribute Microsoft in your code. + +01. Repeat this process as needed for different projects. + +The analysis phase could take some time depending on the size of your codebase. Spending time in this phase to thoroughly understand the scope of changes needed and to develop a plan usually saves you time in the end, particularly if you have a complex codebase. + +Your plan could involve making significant changes to your codebase while still targeting .NET Framework 4.7.2. This is a more structured version of the previous approach. How you go about executing your plan is dependent on your codebase. + +### Mixed approach + +It's likely that you'll mix the above approaches on a per-project basis. Do what makes the most sense to you and for your codebase. + +## Port your tests + +The best way to make sure everything works when you've ported your code is to test your code as you port it to .NET. To do this, you'll need to use a testing framework that builds and runs tests for .NET. Currently, you have three options: + +- [xUnit](https://xunit.net/) + - [Getting Started](https://xunit.net/docs/getting-started/netcore/cmdline) + - [Tool to convert an MSTest project to xUnit](https://github.com/dotnet/codeformatter/tree/main/src/XUnitConverter) +- [NUnit](https://nunit.org/) + - [Getting Started](https://github.com/nunit/docs/wiki/Installation) + - [Blog post about migrating from MSTest to NUnit](https://www.florian-rappl.de/News/Page/275/convert-mstest-to-nunit) +- [MSTest](/visualstudio/test/unit-test-basics) + +## Recommended approach + +Ultimately, the porting effort depends heavily on how your .NET Framework code is structured. A good way to port your code is to begin with the *base* of your library, which is the foundational components of your code. This might be data models or some other foundational classes and methods that everything else uses directly or indirectly. + +01. Port the test project that tests the layer of your library that you're currently porting. +01. Copy over the base of your library into a new .NET project and select the version of .NET Standard you wish to support. +01. Make any changes needed to get the code to compile. Much of this may require adding NuGet package dependencies to your *csproj* file. +01. Run the tests and make any needed adjustments. +01. Pick the next layer of code to port over and repeat the prior steps. + +If you start with the base of your library and move outward from the base and test each layer as needed, porting is a systematic process where problems are isolated to one layer of code at a time. diff --git a/docs/core/porting/premigration-needed-changes.md b/docs/core/porting/premigration-needed-changes.md new file mode 100644 index 0000000000000..d14945cd0f0bb --- /dev/null +++ b/docs/core/porting/premigration-needed-changes.md @@ -0,0 +1,28 @@ +--- +title: Needed changes before porting code +description: Make the necessary changes to build targeting .NET Core. +author: stebon +ms.date: 06/10/2021 +--- +# Overview + +# Upgrade to required tooling + +# Update .NET Framework target version + +If your code isn't targeting .NET Framework 4.7.2, we recommended that you retarget to .NET Framework 4.7.2. This ensures the availability of the latest API alternatives for cases where .NET Standard doesn't support existing APIs. + +For each of the projects you wish to port, do the following in Visual Studio: + +01. Right-click on the project and select **Properties**. +01. In the **Target Framework** dropdown, select **.NET Framework 4.7.2**. +01. Recompile the project. + +Because your projects now target .NET Framework 4.7.2, use that version of the .NET Framework as your base for porting code. + +# Change to PackageReference format + +# Update dependencies + +# Convert to SDK style project format + diff --git a/docs/core/porting/unsupported-apis.md b/docs/core/porting/unsupported-apis.md new file mode 100644 index 0000000000000..929a7e08c1dbe --- /dev/null +++ b/docs/core/porting/unsupported-apis.md @@ -0,0 +1,10 @@ +--- +title: Unsupported APIs +description: Learn about unsupported APIs and what to do about them. +author: stebon +ms.date: 06/10/2021 +--- + +The next step is to run the API Portability Analyzer (ApiPort) to generate a portability report for analysis. + +Make sure you understand the [API Portability Analyzer (ApiPort)](../../standard/analyzers/portability-analyzer.md) and how to generate portability reports for targeting .NET. How you do this likely varies based on your needs and personal tastes. The following sections detail a few different approaches. You may find yourself mixing steps of these approaches depending on how your code is structured. diff --git a/docs/fundamentals/toc.yml b/docs/fundamentals/toc.yml index a6eeeebd2d484..a42bbcc265dea 100644 --- a/docs/fundamentals/toc.yml +++ b/docs/fundamentals/toc.yml @@ -2487,12 +2487,16 @@ items: href: ../core/porting/net-framework-tech-unavailable.md?toc=/dotnet/fundamentals/toc.json&bc=/dotnet/breadcrumb/toc.json - name: Unsupported APIs href: ../core/porting/unsupported-apis.md - - name: Update .NET Framework target version - href: ../core/porting/update-netfx-tfm-version.md + - name: Needed changes before porting code + href: ../core/porting/premigration-needed-changes.md - name: Migration items: - name: Create a porting plan - href: ../core/porting/create-a-porting-plan.md + items: + - name: Approaches + href: ../core/porting/porting-approaches.md + - name: Project structure + href: ../core/porting/project-structure.md - name: Application Porting Guides items: - name: Windows Forms From f634263a431e94cf41e8b01065b86e4a45aa7016 Mon Sep 17 00:00:00 2001 From: Stephen Bonikowsky Date: Thu, 10 Jun 2021 11:54:32 -0700 Subject: [PATCH 4/9] Created additional pages needed for Phase 1 modifying the TOC as needed. --- docs/core/porting/porting-approaches.md | 85 +++++++++++++++++++ .../porting/premigration-needed-changes.md | 28 ++++++ docs/core/porting/tooling-requirements.md | 2 +- docs/core/porting/unsupported-apis.md | 10 +++ docs/fundamentals/toc.yml | 10 ++- 5 files changed, 131 insertions(+), 4 deletions(-) create mode 100644 docs/core/porting/porting-approaches.md create mode 100644 docs/core/porting/premigration-needed-changes.md create mode 100644 docs/core/porting/unsupported-apis.md diff --git a/docs/core/porting/porting-approaches.md b/docs/core/porting/porting-approaches.md new file mode 100644 index 0000000000000..80cc8aff6d95f --- /dev/null +++ b/docs/core/porting/porting-approaches.md @@ -0,0 +1,85 @@ +--- +title: Porting approaches +description: Create a porting plan that best reflects your project and context. +author: stebon +ms.date: 06/10/2021 +--- +#Need more content and modify existing content +### Deal primarily with the compiler + +This approach works well for small projects or projects that don't use many .NET Framework APIs. The approach is simple: + +01. Optionally, run ApiPort on your project. If you run ApiPort, gain knowledge from the report on issues you'll need to address. +01. Copy all of your code over into a new .NET project. +01. While referring to the portability report (if generated), solve compiler errors until the project fully compiles. + +Although it's unstructured, this code-focused approach often resolves issues quickly. A project that contains only data models might be an ideal candidate for this approach. + +### Stay on the .NET Framework until portability issues are resolved + +This approach might be the best if you prefer to have code that compiles during the entire process. The approach is as follows: + +01. Run ApiPort on a project. +01. Address issues by using different APIs that are portable. +01. Take note of any areas where you're prevented from using a direct alternative. +01. Repeat the prior steps for all projects you're porting until you're confident each is ready to be copied over into a new .NET project. +01. Copy the code into a new .NET project. +01. Work out any issues where you noted that a direct alternative doesn't exist. + +This careful approach is more structured than simply working out compiler errors, but it's still relatively code-focused and has the benefit of always having code that compiles. The way you resolve certain issues that couldn't be addressed by just using another API varies greatly. You may find that you need to develop a more comprehensive plan for certain projects, which is covered in the next approach. + +### Develop a comprehensive plan of attack + +This approach might be best for larger and more complex projects, where restructuring code or completely rewriting certain areas of code might be necessary to support .NET. The approach is as follows: + +01. Run ApiPort on a project. +01. Understand where each non-portable type is used and how that affects overall portability. + + - Understand the nature of those types. Are they small in number but used frequently? Are they large in number but used infrequently? Is their use concentrated, or is it spread throughout your code? + - Is it easy to isolate code that isn't portable so that you can deal with it more effectively? + - Do you need to refactor your code? + - For those types that aren't portable, are there alternative APIs that accomplish the same task? For example, if you're using the class, use the class instead. + - Are there different portable APIs available to accomplish a task, even if it's not a drop-in replacement? For example, if you're using to parse XML but don't require XML schema discovery, you could use APIs and implement parsing yourself instead of relying on an API. + +01. If you have assemblies that are difficult to port, is it worth leaving them on .NET Framework for now? Here are some things to consider: + + - You may have some functionality in your library that's incompatible with .NET because it relies too heavily on .NET Framework or Windows-specific functionality. Is it worth leaving that functionality behind for now and releasing a temporary .NET version of your library with fewer features until resources are available to port the features? + - Would a refactor help? + +01. Is it reasonable to write your own implementation of an unavailable .NET Framework API? + + You could consider copying, modifying, and using code from the [.NET Framework reference source](https://github.com/Microsoft/referencesource). The reference source code is licensed under the [MIT License](https://github.com/Microsoft/referencesource/blob/master/LICENSE.txt), so you have significant freedom to use the source as a basis for your own code. Just be sure to properly attribute Microsoft in your code. + +01. Repeat this process as needed for different projects. + +The analysis phase could take some time depending on the size of your codebase. Spending time in this phase to thoroughly understand the scope of changes needed and to develop a plan usually saves you time in the end, particularly if you have a complex codebase. + +Your plan could involve making significant changes to your codebase while still targeting .NET Framework 4.7.2. This is a more structured version of the previous approach. How you go about executing your plan is dependent on your codebase. + +### Mixed approach + +It's likely that you'll mix the above approaches on a per-project basis. Do what makes the most sense to you and for your codebase. + +## Port your tests + +The best way to make sure everything works when you've ported your code is to test your code as you port it to .NET. To do this, you'll need to use a testing framework that builds and runs tests for .NET. Currently, you have three options: + +- [xUnit](https://xunit.net/) + - [Getting Started](https://xunit.net/docs/getting-started/netcore/cmdline) + - [Tool to convert an MSTest project to xUnit](https://github.com/dotnet/codeformatter/tree/main/src/XUnitConverter) +- [NUnit](https://nunit.org/) + - [Getting Started](https://github.com/nunit/docs/wiki/Installation) + - [Blog post about migrating from MSTest to NUnit](https://www.florian-rappl.de/News/Page/275/convert-mstest-to-nunit) +- [MSTest](/visualstudio/test/unit-test-basics) + +## Recommended approach + +Ultimately, the porting effort depends heavily on how your .NET Framework code is structured. A good way to port your code is to begin with the *base* of your library, which is the foundational components of your code. This might be data models or some other foundational classes and methods that everything else uses directly or indirectly. + +01. Port the test project that tests the layer of your library that you're currently porting. +01. Copy over the base of your library into a new .NET project and select the version of .NET Standard you wish to support. +01. Make any changes needed to get the code to compile. Much of this may require adding NuGet package dependencies to your *csproj* file. +01. Run the tests and make any needed adjustments. +01. Pick the next layer of code to port over and repeat the prior steps. + +If you start with the base of your library and move outward from the base and test each layer as needed, porting is a systematic process where problems are isolated to one layer of code at a time. diff --git a/docs/core/porting/premigration-needed-changes.md b/docs/core/porting/premigration-needed-changes.md new file mode 100644 index 0000000000000..3419ef7afc127 --- /dev/null +++ b/docs/core/porting/premigration-needed-changes.md @@ -0,0 +1,28 @@ +--- +title: Needed changes before porting code +description: Make the necessary changes to build targeting .NET Core. +author: stebon +ms.date: 06/10/2021 +--- +# Overview +[content needed] +# Upgrade to required tooling +[content needed] +# Update .NET Framework target version + +If your code isn't targeting .NET Framework 4.7.2, we recommended that you retarget to .NET Framework 4.7.2. This ensures the availability of the latest API alternatives for cases where .NET Standard doesn't support existing APIs. + +For each of the projects you wish to port, do the following in Visual Studio: + +01. Right-click on the project and select **Properties**. +01. In the **Target Framework** dropdown, select **.NET Framework 4.7.2**. +01. Recompile the project. + +Because your projects now target .NET Framework 4.7.2, use that version of the .NET Framework as your base for porting code. + +# Change to PackageReference format +[content needed] +# Update dependencies +[content needed] +# Convert to SDK style project format +[content needed] diff --git a/docs/core/porting/tooling-requirements.md b/docs/core/porting/tooling-requirements.md index 15ed25d318e3e..d288d508f01eb 100644 --- a/docs/core/porting/tooling-requirements.md +++ b/docs/core/porting/tooling-requirements.md @@ -6,7 +6,7 @@ ms.date: 06/10/2021 --- Understanding the versioning of the SDK and how it relates to Visual Studio and MSBuild can frequently be confusing. MSBuild versions with VS but is also included in the SDK. The SDK has a minimum version of MSBuild that it works with and it won't load in a VS that is older than it supports. -# Versioning +# Versioning The first part of the SDK matches the .NET version that it includes, runs on, and targets by default. The feature band starts at 1 and increases for each quarterly VS minor release. The patch version increments with each month's servicing updates. For example, 5.0.203 ships with .NET 5.0, is the 2nd minor VS release since 5.0.100 first came out, and is the 3rd patch since 5.0.200 released. diff --git a/docs/core/porting/unsupported-apis.md b/docs/core/porting/unsupported-apis.md new file mode 100644 index 0000000000000..929a7e08c1dbe --- /dev/null +++ b/docs/core/porting/unsupported-apis.md @@ -0,0 +1,10 @@ +--- +title: Unsupported APIs +description: Learn about unsupported APIs and what to do about them. +author: stebon +ms.date: 06/10/2021 +--- + +The next step is to run the API Portability Analyzer (ApiPort) to generate a portability report for analysis. + +Make sure you understand the [API Portability Analyzer (ApiPort)](../../standard/analyzers/portability-analyzer.md) and how to generate portability reports for targeting .NET. How you do this likely varies based on your needs and personal tastes. The following sections detail a few different approaches. You may find yourself mixing steps of these approaches depending on how your code is structured. diff --git a/docs/fundamentals/toc.yml b/docs/fundamentals/toc.yml index a6eeeebd2d484..a42bbcc265dea 100644 --- a/docs/fundamentals/toc.yml +++ b/docs/fundamentals/toc.yml @@ -2487,12 +2487,16 @@ items: href: ../core/porting/net-framework-tech-unavailable.md?toc=/dotnet/fundamentals/toc.json&bc=/dotnet/breadcrumb/toc.json - name: Unsupported APIs href: ../core/porting/unsupported-apis.md - - name: Update .NET Framework target version - href: ../core/porting/update-netfx-tfm-version.md + - name: Needed changes before porting code + href: ../core/porting/premigration-needed-changes.md - name: Migration items: - name: Create a porting plan - href: ../core/porting/create-a-porting-plan.md + items: + - name: Approaches + href: ../core/porting/porting-approaches.md + - name: Project structure + href: ../core/porting/project-structure.md - name: Application Porting Guides items: - name: Windows Forms From 9174190c4d3636a18bd8a6241e6c06d89c9bb507 Mon Sep 17 00:00:00 2001 From: "Andy (Steve) De George" <67293991+adegeo@users.noreply.github.com> Date: Fri, 11 Jun 2021 11:41:46 -0700 Subject: [PATCH 5/9] Update docs/core/porting/premigration-needed-changes.md --- docs/core/porting/premigration-needed-changes.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/core/porting/premigration-needed-changes.md b/docs/core/porting/premigration-needed-changes.md index d579e1d9863b8..ed2201deed044 100644 --- a/docs/core/porting/premigration-needed-changes.md +++ b/docs/core/porting/premigration-needed-changes.md @@ -6,7 +6,7 @@ ms.date: 06/10/2021 --- # Overview [content needed] -# Upgrade to required tooling +## Upgrade to required tooling [content needed] # Update .NET Framework target version From fa12a007918377b0f70aa7e361baa326105314c3 Mon Sep 17 00:00:00 2001 From: "Andy (Steve) De George" <67293991+adegeo@users.noreply.github.com> Date: Fri, 11 Jun 2021 11:41:46 -0700 Subject: [PATCH 6/9] Update docs/core/porting/premigration-needed-changes.md --- docs/core/porting/porting-approaches.md | 3 ++- .../porting/premigration-needed-changes.md | 19 ++++++++++++++----- 2 files changed, 16 insertions(+), 6 deletions(-) diff --git a/docs/core/porting/porting-approaches.md b/docs/core/porting/porting-approaches.md index 80cc8aff6d95f..a7f1ce5042289 100644 --- a/docs/core/porting/porting-approaches.md +++ b/docs/core/porting/porting-approaches.md @@ -4,7 +4,8 @@ description: Create a porting plan that best reflects your project and context. author: stebon ms.date: 06/10/2021 --- -#Need more content and modify existing content +[Need more content and modify existing content] + ### Deal primarily with the compiler This approach works well for small projects or projects that don't use many .NET Framework APIs. The approach is simple: diff --git a/docs/core/porting/premigration-needed-changes.md b/docs/core/porting/premigration-needed-changes.md index d579e1d9863b8..18810313a993e 100644 --- a/docs/core/porting/premigration-needed-changes.md +++ b/docs/core/porting/premigration-needed-changes.md @@ -5,10 +5,14 @@ author: stebon ms.date: 06/10/2021 --- # Overview + [content needed] -# Upgrade to required tooling + +## Upgrade to required tooling + [content needed] -# Update .NET Framework target version + +## Update .NET Framework target version If your code isn't targeting .NET Framework 4.7.2, we recommended that you retarget to .NET Framework 4.7.2. This ensures the availability of the latest API alternatives for cases where .NET Standard doesn't support existing APIs. @@ -20,9 +24,14 @@ For each of the projects you wish to port, do the following in Visual Studio: Because your projects now target .NET Framework 4.7.2, use that version of the .NET Framework as your base for porting code. -# Change to PackageReference format +## Change to PackageReference format + [content needed] -# Update dependencies + +## Update dependencies + [content needed] -# Convert to SDK style project format + +## Convert to SDK style project format + [content needed] From f1fb91e0a2537766e2cb320a05549247d5506cbd Mon Sep 17 00:00:00 2001 From: Stephen Bonikowsky Date: Mon, 14 Jun 2021 10:52:51 -0700 Subject: [PATCH 7/9] Add breaking change page. --- docs/core/porting/breaking-changes.md | 15 +++++++++++++++ docs/fundamentals/toc.yml | 2 +- 2 files changed, 16 insertions(+), 1 deletion(-) create mode 100644 docs/core/porting/breaking-changes.md diff --git a/docs/core/porting/breaking-changes.md b/docs/core/porting/breaking-changes.md new file mode 100644 index 0000000000000..d4c0888980142 --- /dev/null +++ b/docs/core/porting/breaking-changes.md @@ -0,0 +1,15 @@ +--- +title: Breaking changes +description: Breaking changes between releases of .NET and how it impacts compatibility. +author: stebon +ms.date: 06/14/2021 +--- +# Breaking Changes + +Visit the following documentation to learn about and find breaking changes when moving from the .NET Framework to .NET and between releases of .NET. + +## [What are breaking changes?](../compatibility/index.md) + +## [Types of compatibility.](../compatibility/categories.md) + +## [Find breaking changes.](../compatibility/breaking-changes.md) diff --git a/docs/fundamentals/toc.yml b/docs/fundamentals/toc.yml index b215b88c532ff..b36311c7cacc2 100644 --- a/docs/fundamentals/toc.yml +++ b/docs/fundamentals/toc.yml @@ -2474,7 +2474,7 @@ items: href: ../core/porting/upgrade-assistant-aspnetmvc.md - name: Breaking changes displayName: app compatibility - href: ../core/compatibility/ + href: ../core/porting/breaking-changes.md - name: Pre-Migration items: - name: Analyze & Asses the portability of your project From 199563421c071673bf33b174e02cff00e8bd269e Mon Sep 17 00:00:00 2001 From: Stephen Bonikowsky Date: Mon, 14 Jun 2021 10:52:51 -0700 Subject: [PATCH 8/9] Add breaking change page. --- docs/core/porting/breaking-changes.md | 15 +++++++++++++++ docs/core/porting/premigration-needed-changes.md | 14 +++++++------- docs/core/porting/third-party-deps.md | 6 +++--- docs/core/porting/unsupported-apis.md | 13 ++++++++++--- docs/fundamentals/toc.yml | 2 +- 5 files changed, 36 insertions(+), 14 deletions(-) create mode 100644 docs/core/porting/breaking-changes.md diff --git a/docs/core/porting/breaking-changes.md b/docs/core/porting/breaking-changes.md new file mode 100644 index 0000000000000..d4c0888980142 --- /dev/null +++ b/docs/core/porting/breaking-changes.md @@ -0,0 +1,15 @@ +--- +title: Breaking changes +description: Breaking changes between releases of .NET and how it impacts compatibility. +author: stebon +ms.date: 06/14/2021 +--- +# Breaking Changes + +Visit the following documentation to learn about and find breaking changes when moving from the .NET Framework to .NET and between releases of .NET. + +## [What are breaking changes?](../compatibility/index.md) + +## [Types of compatibility.](../compatibility/categories.md) + +## [Find breaking changes.](../compatibility/breaking-changes.md) diff --git a/docs/core/porting/premigration-needed-changes.md b/docs/core/porting/premigration-needed-changes.md index 18810313a993e..2b51886b18d99 100644 --- a/docs/core/porting/premigration-needed-changes.md +++ b/docs/core/porting/premigration-needed-changes.md @@ -6,11 +6,11 @@ ms.date: 06/10/2021 --- # Overview -[content needed] +Make the needed changes to build and run a .NET application before beginning the work to port your code. All of these changes can be done while still building and running a .NET Framework application. ## Upgrade to required tooling -[content needed] +Upgrade to a version of MSBuild/Visual Studio that supports the version of .NET you will be targeting. See [Tooling Requirements](tooling-requirements.md) for more info. ## Update .NET Framework target version @@ -26,12 +26,12 @@ Because your projects now target .NET Framework 4.7.2, use that version of the . ## Change to PackageReference format -[content needed] +Convert all references to the [PackageReference](/nuget/consume-packages/package-references-in-project-files) format. -## Update dependencies +## Convert to SDK style project format -[content needed] +Convert your projects to the [SDK-style format](../project-sdk/overview.md). -## Convert to SDK style project format +## Update dependencies -[content needed] +Update dependencies to their latest version available, and to .NET Standard version where possible. diff --git a/docs/core/porting/third-party-deps.md b/docs/core/porting/third-party-deps.md index 8ff65bee1ccff..7a40743249da5 100644 --- a/docs/core/porting/third-party-deps.md +++ b/docs/core/porting/third-party-deps.md @@ -1,12 +1,12 @@ --- title: Analyze dependencies to port code description: Learn how to analyze external dependencies to port your project from .NET Framework to .NET. -author: cartermp -ms.date: 03/04/2021 +author: stebon +ms.date: 06/14/2021 --- # Analyze your dependencies to port code from .NET Framework to .NET -To port your code to .NET or .NET Standard, you must understand your dependencies. External dependencies are the NuGet packages or `.dll` files you reference in your project, but that you don't build yourself. +To identify the unsupported third-party dependencies in your project you must first understand your dependencies. External dependencies are the NuGet packages or `.dll` files you reference in your project, but that you don't build yourself. Porting your code to .NET Standard 2.0 or below ensures that it can be used with both .NET Framework and .NET. However, if you don't need to use the library with .NET Framework, consider targeting the latest version of .NET. diff --git a/docs/core/porting/unsupported-apis.md b/docs/core/porting/unsupported-apis.md index b06edcbe600fa..ab01d776a1d59 100644 --- a/docs/core/porting/unsupported-apis.md +++ b/docs/core/porting/unsupported-apis.md @@ -4,7 +4,14 @@ description: Learn about unsupported APIs and what to do about them. author: stebon ms.date: 06/10/2021 --- -[Content Needed] -The next step is to run the API Portability Analyzer (ApiPort) to generate a portability report for analysis. +# Find unsupported APIs in your code -Make sure you understand the [API Portability Analyzer (ApiPort)](../../standard/analyzers/portability-analyzer.md) and how to generate portability reports for targeting .NET. How you do this likely varies based on your needs and personal tastes. The following sections detail a few different approaches. You may find yourself mixing steps of these approaches depending on how your code is structured. +APIs in your .NET Framework code may not be supported in .NET for a number of reasons that range from the simple to fix, such as a namespace change; to the more challenging to fix such as an entire technology not being supported. The first step is to determine which of your APIs are no longer supported and then identify the proper fix. + +## .NET Portability Analyzer + +The .NET Portability Analyzer is a tool that analyzes assemblies and provides a detailed report on .NET APIs that are missing for the applications or libraries to be portable on your specified targeted .NET platforms. + +To use the .NET Portability Analyzer in Visual Studio, install the [extension from the marketplace](https://marketplace.visualstudio.com/items?itemName=ConnieYau.NETPortabilityAnalyzer). + +For more information, see [The .NET Portability Analyzer](../../standard/analyzers/portability-analyzer.md). diff --git a/docs/fundamentals/toc.yml b/docs/fundamentals/toc.yml index b215b88c532ff..b36311c7cacc2 100644 --- a/docs/fundamentals/toc.yml +++ b/docs/fundamentals/toc.yml @@ -2474,7 +2474,7 @@ items: href: ../core/porting/upgrade-assistant-aspnetmvc.md - name: Breaking changes displayName: app compatibility - href: ../core/compatibility/ + href: ../core/porting/breaking-changes.md - name: Pre-Migration items: - name: Analyze & Asses the portability of your project From 8d45d928512c1ec647435c1e82adc670c574c697 Mon Sep 17 00:00:00 2001 From: Stephen Bonikowsky Date: Wed, 23 Jun 2021 15:17:03 -0700 Subject: [PATCH 9/9] Update tooling requirements page based on feedback. --- docs/core/porting/tooling-requirements.md | 35 ++++++++++++++--------- 1 file changed, 22 insertions(+), 13 deletions(-) diff --git a/docs/core/porting/tooling-requirements.md b/docs/core/porting/tooling-requirements.md index d9e8744d01535..8ca781c2d0ba7 100644 --- a/docs/core/porting/tooling-requirements.md +++ b/docs/core/porting/tooling-requirements.md @@ -4,6 +4,8 @@ description: Learn about the versioning relationship between the .NET SDK and MS author: stebon ms.date: 06/10/2021 --- +# Overview + Understanding the versioning of the SDK and how it relates to Visual Studio and MSBuild can frequently be confusing. MSBuild versions with VS but is also included in the SDK. The SDK has a minimum version of MSBuild that it works with and it won't load in a VS that is older than it supports. ## Versioning @@ -18,19 +20,26 @@ The support timeframe for the SDK typically matches the VS it's included in. | SDK Version | MSBuild/VS version | Minimum required MSBuild/VS Version | Ship date | Lifecycle | |------------------|--------------------|-------------------------------------|--------------|-----------| -| 2.1.5xx | 15.9 | 15.3 | Nov �18 | Aug �21* | -| 2.1.8xx | 16.2 (No VS) | 16.0 | July �19 | Aug �21 | -| 3.1.1xx | 16.4 | 16.3 | Dec �19 | Dec �22 | -| 3.1.4xx | 16.7 | 16.7 | Aug �20 | Dec �22 | -| 5.0.1xx | 16.8 | 16.8 | November �20 | Mar �21 | -| 5.0.2xx | 16.9 | 16.8 | March 21 | Aug �22 | -| 5.0.3xx | 16.10 | 16.8 | May 21 | Aug �21 | -| 5.0.4xx | 16.11 | 16.8 | Aug 21 | Feb �22* | -| 6.0.100-preview4 | 16.10 (No VS) | 16.10-preview3 | 05/25/21 | N/A | -| 6.0.100-preview5 | 17.0-preview 1 | 16.10 | June | N/A | -| 6.0.100 | 17.0 | 16.10** | November | +| 2.1.5xx | 15.9 | 15.3 | Nov '18 | Aug '21* | +| 2.1.8xx | 16.2 (No VS) | 16.0 | July '19 | Aug '21 | +| 3.1.1xx | 16.4 | 16.3 | Dec '19 | Dec '22 | +| 3.1.4xx | 16.7 | 16.7 | Aug '20 | Dec '22 | +| 5.0.1xx | 16.8 | 16.8 | November '20 | Mar '21 | +| 5.0.2xx | 16.9 | 16.8 | March '21 | Aug '22 | +| 5.0.3xx | 16.10 | 16.8 | May '21 | Aug '21 | +| 5.0.4xx | 16.11 | 16.8 | Aug '21 | Feb '22* | +| 6.0.100-preview4 | 16.10 (No VS) | 16.10-preview3 | May '21 | N/A | +| 6.0.100-preview5 | 17.0-preview 1 | 16.10 | June '21 | N/A | +| 6.0.100 | 17.0 | 16.10** | Nov. '21 | *MSbuild/VS supported for longer -**The goal is on .NET 6 release day to be functional with at most 16.11 (so customers aren't forced to update VS versions on day 0) -We've tried to reduce the frequency that we make breaking changes but cannot guarantee that each new major SDK version won't require at least some upgrade of the version of VS/MSBuild so that should be expected at least once a year. +**Customers should not have to upgrade to 17.0 on the day .NET 6 releases, this is the current value and will likely be 16.11 by release. + +We expect breaking changes requiring new MSBuild and VS versions expected at least once a year for new SDK version bands. We do not anticipate version compat breaking changes in feature bands anymore. + +## Reference + +- [.NET Core and .NET 5 official support policy](/platform/support/policy/dotnet-core) +- [Microsoft .NET and .NET Core](/lifecycle/products/microsoft-net-and-net-core) +- [.NET Downloads (Linux, macOS, and Windows)](/download/dotnet)