Update porting overview and dependencies section (#14621)

* Update porting overview and dependencies section

* Apply suggestions from code review

Co-Authored-By: Maira Wenzel <mairaw@microsoft.com>

* Changes based on feedback

* More rewording in overview to make some items clearer

* Update suggested tool to convert

* Apply suggestions from code review

Co-Authored-By: Maira Wenzel <mairaw@microsoft.com>

* Updates based on feedback

Author: cartermp

docs/core/porting/index.md

@@ -1,48 +1,46 @@
 ---
-title: Port code from .NET Framework to .NET Core
+title: Port from .NET Framework to .NET Core
 description: Understand the porting process and discover tools you may find helpful when porting a .NET Framework project to .NET Core.
 author: cartermp
-ms.date: 09/13/2019
+ms.date: 10/22/2019
 ms.custom: seodec18
 ---
-# Port your code from .NET Framework to .NET Core
+# Overview of the porting process from .NET Framework to .NET Core
 
-If you've got code that runs on the .NET Framework, you may be interested in running your code on .NET Core, too. Here's an overview of the porting process and a list of the tools you may find helpful when porting your code to .NET Core.
+You might have code that currently runs on the .NET Framework that you're interested in porting to .NET Core. This article provides:
 
-## Overview of the porting process
-
-This is the process we recommend you take when porting your project to .NET Core. Each step of the process is covered in more detail in further articles.
+* An overview of the porting process.
+* A list of the tools you may find helpful when you're porting your code to .NET Core.
 
-1. Identify and account for your third-party dependencies.
+## Overview of the porting process
 
-   This step involves understanding what your third-party dependencies are, how you depend on them, how to check if they also run on .NET Core, and steps you can take if they don't. It also covers how you can migrate your dependencies over to the [PackageReference](/nuget/consume-packages/package-references-in-project-files) format that is used in .NET Core.
+We recommend you to use the following process when porting your project to .NET Core:
 
-2. Retarget all projects you wish to port to target the .NET Framework 4.7.2 or higher.
+1. Retarget all projects you wish to port to target the .NET Framework 4.7.2 or higher.
 
    This step ensures that you can use API alternatives for .NET Framework-specific targets when .NET Core doesn't support a particular API.
 
-3. Use the [.NET Portability Analyzer](../../standard/analyzers/portability-analyzer.md) to analyze your assemblies and develop a plan to port based on its results.
+2. Use the [.NET Portability Analyzer](../../standard/analyzers/portability-analyzer.md) to analyze your assemblies and see if they're portable to .NET Core.
+
+   The API Portability Analyzer tool analyzes your compiled assemblies and generates a report. This report shows a high-level portability summary and a breakdown of each API you're using that isn't available on NET Core.
 
-   The API Portability Analyzer tool analyzes your compiled assemblies and generates a report that shows a high-level portability summary and a breakdown of each API you're using that isn't available on targeted .NET Core platform public surface. You can use this report alongside an analysis of your codebase to develop a plan for how you'll port your code over.
+3. Install the [.NET API analyzer](../../standard/analyzers/api-analyzer.md) into your projects to identify APIs throwing <xref:System.PlatformNotSupportedException> on some platforms and some other potential compatibility issues.
 
-4. Once you have your project file converted to your targeted .NET Core version, you can use Roslyn based [.NET API analyzer](../../standard/analyzers/api-analyzer.md) to identify APIs throwing <xref:System.PlatformNotSupportedException> on some platforms and some other potential compatibility issues.
+   This tool is similar to the portability analyzer, but instead of analyzing if things can build on .NET Core, it will analyze if you're using an API in a way that will throw the <xref:System.PlatformNotSupportedException> at runtime. Although this isn't common if you're moving from .NET Framework 4.7.2 or higher, it's good to check.
 
-5. Port your tests code.
+4. Convert all of your `packages.config` dependencies to the [PackageReference](/nuget/consume-packages/package-references-in-project-files) format with the [conversion tool in Visual Studio](/nuget/consume-packages/migrate-packages-config-to-package-reference).
 
-   Because porting to .NET Core is such a significant change to your codebase, it's highly recommended to get your tests ported, so that you can run tests as you port your code over. MSTest, xUnit, and NUnit all support .NET Core.
+   This step involves converting your dependencies from the legacy `packages.config` format. `packages.config` doesn't work on .NET Core, so this conversion is required if you have package dependencies.
 
-6. Execute your plan for porting!
+5. Create new projects for .NET Core and copy over source files, or attempt to convert your existing project file with a tool.
 
-The following list shows tools you might find helpful to use during the porting process:
+   .NET Core uses a simplified (and different) [project file format](../tools/csproj.md) than .NET Framework. You'll need to convert your project files into this format to continue.
 
-- .NET Portability Analyzer - [command-line tool](https://github.com/Microsoft/dotnet-apiport/releases) or [Visual Studio Extension](https://marketplace.visualstudio.com/items?itemName=ConnieYau.NETPortabilityAnalyzer), a tool that can generate a report of how portable your code is between .NET Framework and your target .NET Core platform. The report contains an assembly-by-assembly breakdown of the Type and APIs missing on the target .NET Core platform. For more information, see [.NET Portability Analyzer](../../standard/analyzers/portability-analyzer.md). It is recommended to run the .NET Portability Analyzer tool before you start porting, as it will help you identify any gaps in missing APIs in specific targeted .NET platform public surface.
-- .NET API Analyzer - A Roslyn analyzer that discovers .NET Standard API that throws <xref:System.PlatformNotSupportedException> on some platforms, detects calls to deprecated APIs, and discovers some other potential compatibility risks for C# APIs on different platforms. For more information, see [.NET API analyzer](../../standard/analyzers/api-analyzer.md). This analyzer is helpful after you already created your .NET Core project to identify runtime behavior differences on different platforms.
-- Reverse Package Search - A [useful web service](https://packagesearch.azurewebsites.net) that allows you to search for a type and find packages containing that type.
+6. Port your test code.
 
-Additionally, you can attempt to port smaller solutions or individual projects to the .NET Core project file format with the [CsprojToVs2017](https://github.com/hvanbakel/CsprojToVs2017) tool.
+   Because porting to .NET Core is such a significant change to your codebase, it's highly recommended to get your tests ported, so that you can run tests as you port your code over. MSTest, xUnit, and NUnit all work on .NET Core.
 
-> [!WARNING]
-> CsprojToVs2017 is a third-party tool. There is no guarantee that it will work for all of your projects, and it may cause subtle changes in behavior that you depend on. CsprojToVs2017 should be used as a _starting point_ that automates the basic things that can be automated. It is not a guaranteed solution to migrating project file formats.
+Additionally, you can attempt to port smaller solutions or individual projects to the .NET Core project file format with the [dotnet try-convert](https://github.com/dotnet/try-convert) tool in one operation. `dotnet try-convert` is not guaranteedto work for all your projects, and it may cause subtle changes in behavior that you may find that you depended on. It should be used as a _starting point_ that automates the basic things that can be automated. It isn't a guaranteed solution to migrating a project.
 
 >[!div class="step-by-step"]
 >[Next](net-framework-tech-unavailable.md)

docs/core/porting/third-party-deps.md

@@ -2,22 +2,34 @@
 title: Analyze dependencies to port code to .NET Core
 description: Learn how to analyze external dependencies in order to port your project from .NET Framework to .NET Core.
 author: cartermp
-ms.date: 12/07/2018
+ms.date: 10/22/2019
 ms.custom: seodec18
 ---
 # Analyze your dependencies to port code to .NET Core
 
-To port your code to .NET Core or .NET Standard, you must understand your dependencies. External dependencies are the [NuGet packages](#analyze-referenced-nuget-packages-in-your-projects) or [DLLs](#analyze-dependencies-that-arent-nuget-packages) you reference in your project, but that you don't build. Evaluate each dependency and develop a contingency plan for the ones that aren't compatible with .NET Core. Here's how to determine if a dependency is compatible with .NET Core.
+To port your code to .NET Core or .NET Standard, you must understand your dependencies. External dependencies are the NuGet packages or `.dll`s you reference in your project, but that you don't build yourself.
 
-## Analyze referenced NuGet packages in your projects
+## Migrate your NuGet packages to `PackageReference`
 
-If you reference NuGet packages in your project, you need to verify if they're compatible with .NET Core.
-There are two ways to accomplish that:
+.NET Core uses [PackageReference](/nuget/consume-packages/package-references-in-project-files) to specify package dependencies. If you're using [packages.config](/nuget/reference/packages-config) to specify your packages in your project, you need to convert it to the `PackageReference` format because `packages.config` isn't supported in .NET Core.
 
-- [Using the NuGet Package Explorer app](#analyze-nuget-packages-using-nuget-package-explorer)
-- [Using the nuget.org site](#analyze-nuget-packages-using-nugetorg)
+To learn how to migrate, see the [Migrate from packages.config to PackageReference](/nuget/reference/migrate-packages-config-to-package-reference) article.
 
-After analyzing the packages, if they're not compatible with .NET Core and only target .NET Framework, you can check if the [.NET Framework compatibility mode](#net-framework-compatibility-mode) can help with your porting process.
+## Upgrade your NuGet packages
+
+After your migrating your project to the `PackageReference` format, you need to verify if your packages are compatible with .NET Core.
+
+First, upgrade your packages to the latest version that you can. This can be done with the NuGet Package Manager UI in Visual Studio. It's likely that newer versions of your package dependencies are already compatible with .NET Core.
+
+## Analyze your package dependencies
+
+If you haven't already verified that your converted and upgraded package dependencies work on .NET Core, there are a few ways that you can achieve that:
+
+### Analyze NuGet packages using nuget.org
+
+You can see the Target Framework Monikers (TFMs) that each package supports on [nuget.org](https://www.nuget.org/) under the **Dependencies** section of the package page.
+
+Although using the site is an easier method to verify the compatibility, **Dependencies** information isn't available on the site for all packages.
 
 ### Analyze NuGet packages using NuGet Package Explorer
 
@@ -31,43 +43,17 @@ The easiest way to inspect NuGet Package folders is to use the [NuGet Package Ex
 4. Select the package name from the search results and click **open**.
 5. Expand the *lib* folder on the right-hand side and look at folder names.
 
-Look for a folder with any of the following names:
-
-```
-netstandard1.0
-netstandard1.1
-netstandard1.2
-netstandard1.3
-netstandard1.4
-netstandard1.5
-netstandard1.6
-netstandard2.0
-netcoreapp1.0
-netcoreapp1.1
-netcoreapp2.0
-netcoreapp2.1
-netcoreapp2.2
-portable-net45-win8
-portable-win8-wpa8
-portable-net451-win81
-portable-net45-win8-wpa8-wpa81
-```
+Look for a folder with names using one the following patterns: `netstandardX.Y` or `netcoreappX.Y`.
 
 These values are the [Target Framework Monikers (TFMs)](../../standard/frameworks.md) that map to versions of the [.NET Standard](../../standard/net-standard.md), .NET Core, and traditional Portable Class Library (PCL) profiles that are compatible with .NET Core.
 
 > [!IMPORTANT]
 > When looking at the TFMs that a package supports, note that `netcoreapp*`, while compatible, is for .NET Core projects only and not for .NET Standard projects.
 > A library that only targets `netcoreapp*` and not `netstandard*` can only be consumed by other .NET Core apps.
 
-### Analyze NuGet packages using nuget.org
-
-Alternatively, you can see the TFMs that each package supports on [nuget.org](https://www.nuget.org/) under the **Dependencies** section of the package page.
-
-Although using the site is an easier method to verify the compatibility, **Dependencies** information is not available on the site for all packages.
+## .NET Framework compatibility mode
 
-### .NET Framework compatibility mode
-
-After analyzing the NuGet packages, you might find that they only target the .NET Framework, as most NuGet packages do.
+After analyzing the NuGet packages, you might find that they only target the .NET Framework.
 
 Starting with .NET Standard 2.0, the .NET Framework compatibility mode was introduced. This compatibility mode allows .NET Standard and .NET Core projects to reference .NET Framework libraries. Referencing .NET Framework libraries doesn't work for all projects, such as if the library uses Windows Presentation Foundation (WPF) APIs, but it does unblock many porting scenarios.
 
@@ -87,12 +73,6 @@ To suppress the warning by editing the project file, find the `PackageReference`
 
 For more information on how to suppress compiler warnings in Visual Studio, see [Suppressing warnings for NuGet packages](/visualstudio/ide/how-to-suppress-compiler-warnings#suppress-warnings-for-nuget-packages).
 
-## Port your packages to `PackageReference`
-
-.NET Core uses [PackageReference](/nuget/consume-packages/package-references-in-project-files) to specify package dependencies. If you are using [packages.config](/nuget/reference/packages-config) to specify your packages, you will need to convert over to `PackageReference`.
-
-You can learn more at [Migrate from packages.config to PackageReference](/nuget/reference/migrate-packages-config-to-package-reference).
-
 ## What to do when your NuGet package dependency doesn't run on .NET Core
 
 There are a few things you can do if a NuGet package you depend on doesn't run on .NET Core: