Update the basics of the Upgrade Assistant (#42885)

* Handle articles

* Handle images

* housekeeping

* Lots of little things; alt-text

* Last little bits of warnings

* Fixed bad link

* Final edits

.openpublishing.redirection.core.json

@@ -877,6 +877,14 @@
             "source_path_from_root": "/docs/core/porting/upgrade-assistant-aspnetmvc.md",
             "redirect_url": "/aspnet/core/migration/mvc"
         },
+        {
+            "source_path_from_root": "/docs/core/porting/upgrade-assistant-install-legacy.md",
+            "redirect_url": "/dotnet/core/porting/upgrade-assistant-wcf"
+        },
+        {
+            "source_path_from_root": "/docs/core/porting/upgrade-assistant-uwp-framework.md",
+            "redirect_url": "/windows/apps/windows-app-sdk/migrate-to-windows-app-sdk/upgrade-assistant"
+        },
         {
             "source_path_from_root": "/docs/core/porting/upgrade-assistant-winforms-framework.md",
             "redirect_url": "/dotnet/desktop/winforms/migration/"
@@ -1345,10 +1353,6 @@
         {
             "source_path_from_root": "/docs/fundamentals/networking/tcp/tcp-overview.md",
             "redirect_url": "/dotnet/fundamentals/networking/sockets/tcp-classes"
-        },
-        {
-            "source_path_from_root": "/docs/core/porting/upgrade-assistant-uwp-framework.md",
-            "redirect_url": "/windows/apps/windows-app-sdk/migrate-to-windows-app-sdk/upgrade-assistant"
         }
     ]
 }

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

@@ -95,7 +95,7 @@ The .NET Team would like to know which libraries are the most important to suppo
 
 ## Analyze non-NuGet dependencies
 
-You might have a dependency that isn't a NuGet package, such as a DLL in the file system. You can determine the portability of that dependency with the CLI version of the [.NET Upgrade Assistant](upgrade-assistant-overview.md#upgrade-with-the-cli-tool) tool.
+You might have a dependency that isn't a NuGet package, such as a DLL in the file system. You can determine the portability of that dependency with the [.NET Upgrade Assistant](upgrade-assistant-overview.md) tool.
 
 ## Next steps
 

docs/core/porting/upgrade-assistant-analyze-overview.md

@@ -0,0 +1,115 @@
+---
+title: .NET Upgrade Assistant code analysis overview
+description: "Describes how the code analysis function of .NET Upgrade Assistant works. The analysis generates a report that lists what aspects of your project will be upgraded, and if any manual work is involved."
+author: adegeo
+ms.author: adegeo
+ms.topic: overview
+ms.date: 10/08/2024
+
+#customer intent: As a developer, I need to understand what the analyze function of .NET Upgrade Assistant does.
+
+---
+
+# What is code analysis with .NET Upgrade Assistant?
+
+This article provides an overview of the code analysis function of .NET Upgrade Assistant. Code analysis generates a report based on your project configuration, dependencies, and code. The report contains information about potential issues and problems you might encounter during the upgrade, and what steps you could take to remediate those problems.
+
+## Types of analysis
+
+There are two types of analysis you can perform on your code:
+
+- Source code and settings
+
+  Analyzes your source code, configuration, and settings.
+
+- Binary dependencies
+
+  Analyzes the external binary dependencies (such as NuGet packages) for your projects.
+
+<!--
+
+Cutting this out until the extension docs are written
+
+## Custom configuration
+
+You can use a configuration file for the code analysis engine to control how the analysis is performed.
+
+-->
+
+## Reports
+
+A dashboard report is generated after the analysis completes. This report breaks down the results by project, file, incident, and [story points](#incident-story-points). An aggregate view is also available, to group like-issues together regardless of what project they were detected in.
+
+> [!TIP]
+> Story points are an Agile concept that helps estimate complexity and effort required to fix a problem. For more information, see the [Incident story points](#incident-story-points) section.
+
+Each issue in the report is categorized by [severity](#incident-severity) to assist you in prioritizing any fixes you need to make. Issues are either mandatory or optional. Mandatory issues block the upgrade. Optional issues provide an opportunity to upgrade to a newer feature, library, or code enhancement.
+
+The following sections describe areas of the report in detail.
+
+### Dashboard
+
+The **Dashboard** page provides a view of the incidents detected by the scan, grouped into panels:
+
+:::image type="content" source="./media/upgrade-assistant-analyze-overview/dashboard.png" alt-text="The .NET Upgrade Assistant Analyze results, showing the dashboard's starting page.":::
+
+- **Summary**
+
+  - **Projects**
+
+    This is the number of projects where an incident was detected.
+
+  - **Issues**
+
+    The number of unique rules that triggered during the scan. Each issue has its own severity and story point, along with each detected instance (incident).
+
+  - **Incidents**
+
+    An incident is an instance of a detected issue at a specific location, such as a piece of code or binary file. Each incident contains the contextual information that triggered the issue.
+
+  - **Story Points**
+
+    The total number of story points required to complete the upgrade. For more information about what a story point is, see the [Incident story points](#incident-story-points) section.
+
+- **Severity** and **Categories**
+
+  These two panels show charts that group the incidents by severity and category. For more information about severity, see the [Incident severity](#incident-severity) section.
+
+### Projects
+
+The **Projects** page breaks down the issues, incidents, and story points, by project. Each project is a link that opens a drill-down report filtered to that project.
+
+:::image type="content" source="./media/upgrade-assistant-analyze-overview/projects.png" alt-text="The .NET Upgrade Assistant Analyze results, showing the dashboard's 'Projects' page.":::
+
+### Aggregate issues
+
+The **Aggregate issues** page details each issue that was triggered. Each issue can be expanded to list every incident of that issue. The **State** column helps you track which issues you've fixed or deemed not applicable.
+
+:::image type="content" source="./media/upgrade-assistant-analyze-overview/aggregate-issues.png" alt-text="The .NET Upgrade Assistant Analyze results, showing the dashboard's 'Aggregate issues' page.":::
+
+## Incident severity
+
+Each issue incident has an associated severity, which might block the upgrade. The severity helps you understand what must be updated for the upgrade to succeed.
+
+| Severity | Description |
+| --- | --- |
+| Mandatory | Must be addressed. The upgrade process might handle these issues for you, such as updating the target framework runtime (TFM). |
+| Optional | These shouldn't pose a problem with upgrading, but you might want to consider addressing them before or after the upgrade. |
+| Potential | Problems that might cause issue after upgrading, if you don't address them now. |
+| Information | Extra information related to the upgrade. |
+
+## Incident story points
+
+Each issue incident has an associated story point. A story point is a unit of measure to gauge the complexity of an incident, which helps estimate the time involved to resolve that incident. .NET Upgrade Assistant defines story point values by the following table:
+
+| Story Points | Size           |
+|--------------|----------------|
+| 1            | Trivial        |
+| 3            | Complex        |
+| 5            | Redesign       |
+| 7            | Rearchitecture |
+| 13           | Unknown        |
+
+## Related content
+
+- [Analyze projects with .NET Upgrade Assistant](upgrade-assistant-how-to-analyze.md)

docs/core/porting/upgrade-assistant-how-to-analyze.md

@@ -0,0 +1,84 @@
+---
+title: How to analyze a project with .NET Upgrade Assistant
+description: "Learn how to analyze one or more projects with .NET Upgrade Assistant. Before upgrading, it's a good idea to perform code analysis on your projects so that you understand if extra effort is required after upgrading."
+author: adegeo
+ms.author: adegeo
+ms.topic: how-to
+ms.date: 10/08/2024
+
+#customer intent: As a developer, I want to analyze my project before upgrading to identify any issues before performing an upgrade.
+
+---
+
+# Analyze projects with .NET Upgrade Assistant
+
+This article teaches you how to perform code analysis on your projects with .NET Upgrade Assistant, using Visual Studio or the terminal. The analysis generates a report that you can browse to get more information about the upgrade.
+
+## Prerequisites
+
+- For Visual Studio, see [Install .NET Upgrade Assistant - Visual Studio extension](upgrade-assistant-install.md#visual-studio-extension)
+- For the .NET Global Tool, see [Install .NET Upgrade Assistant - .NET Global Tool](upgrade-assistant-install.md#net-global-tool)
+
+## Create a report in Visual Studio
+
+Follow these steps to analyze a project in Visual Studio.
+
+1. Open Visual Studio.
+1. Open a project or solution.
+1. In the **Solution Explorer** window, right-click on the **solution** > **Upgrade**.
+
+   :::image type="content" source="./media/upgrade-assistant-how-to-analyze/vs-upgrade-analyze-right-click.png" alt-text="The Solution Explorer window in Visual Studio, showing the right-click menu of the solution. The Upgrade menu item is highlighted.":::
+
+1. In the **Upgrade Assistant: Home** tab, select **New Report**.
+
+   :::image type="content" source="./media/upgrade-assistant-how-to-analyze/vs-upgrade-analyze-new-report.png" alt-text="The .NET Upgrade Assistant Analyze wizard's welcome page in Visual Studio. The 'New Report' link is highlighted.":::
+
+1. Select one or more projects to analyze, then select **Next**.
+
+   :::image type="content" source="./media/upgrade-assistant-how-to-analyze/vs-upgrade-analyze-select-projs.png" alt-text="The .NET Upgrade Assistant Analyze wizard's 'Select projects' page in Visual Studio. The list of projects is highlighted along with the 'Next' button.":::
+
+1. Select the target framework, for example .NET 8.0. Then, select **Next**.
+
+   :::image type="content" source="./media/upgrade-assistant-how-to-analyze/vs-upgrade-analyze-target-framework.png" alt-text="The .NET Upgrade Assistant Analyze wizard's 'Target framework' page in Visual Studio. The '.NET 8.0' item is highlighted along with the 'Next' button.":::
+
+1. Select the components to analyze and then select **Next**.
+
+   :::image type="content" source="./media/upgrade-assistant-how-to-analyze/vs-upgrade-analyze-select-components.png" alt-text="The .NET Upgrade Assistant Analyze wizard's 'Analysis settings' page in Visual Studio. The 'Source code and settings' option is selected. The 'Next' button is highlighted.":::
+
+1. A progress indicator is displayed for each project that's being analyzed.
+
+   :::image type="content" source="./media/upgrade-assistant-how-to-analyze/vs-upgrade-analyze-progress.png" alt-text="The .NET Upgrade Assistant Analyze wizard running the analysis.":::
+
+1. Once the analysis is complete, the report dashboard is shown. For more information about the dashboard, see [Reports](upgrade-assistant-analyze-overview.md#reports).
+
+   :::image type="content" source="./media/upgrade-assistant-how-to-analyze/vs-upgrade-analyze-finished.png" alt-text="The .NET Upgrade Assistant Analyze wizard showing a report dashboard that contains the results from the analysis.":::
+
+## Create a report from the CLI
+
+Follow these steps to analyze a project using the terminal. The .NET Global Tool is an interactive tool that guides you through the analysis options. Use the <kbd>Up arrow</kbd> and <kbd>Down arrow</kbd> keys to change the highlighted option, and <kbd>Enter</kbd> to run the select the option. Each screen presents you options on how you want to configure the report.
+
+1. Open a terminal and navigate to the folder containing the solution or project you want to analyze.
+1. To start the tool, run the `upgrade-assistant analyze` command.
+1. You're asked about what you want to analyze. For this example, choose **Application sources** and press <kbd>Enter</kbd>.
+
+   :::image type="content" source="./media/upgrade-assistant-how-to-analyze/cli-upgrade-start.png" alt-text="A terminal showing the initial screen of options for .NET Upgrade Assistant Global Tool. The question 'What do you want to analyze' is being asked.":::
+
+1. Choose a target framework, such as **.NET 8.0**, and press <kbd>Enter</kbd>.
+1. Select the types of items you want to scan. Use <kbd>Spacebar</kbd> to toggle the options, and then press <kbd>Enter</kbd>.
+1. On the **Config file** screen, press <kbd>n</kbd>, unless you have a ruleset config file to apply.
+1. Choose the format of the generated report. For the purposes of this example, select **Save as HTML**.
+1. Enter the name **MyReport** and press <kbd>Enter</kbd>.
+1. Select the appropriate privacy mode, such as **Restricted** and press <kbd>Enter</kbd>.
+1. The final prompt is a confirmation, displaying all of the options you selected. Press <kbd>Enter</kbd> to run the analysis and generate the report.
+
+   :::image type="content" source="./media/upgrade-assistant-how-to-analyze/cli-upgrade-options-end.png" alt-text="A terminal showing the summary screen of options for .NET Upgrade Assistant Global Tool. The user is asked to continue.":::
+
+1. Once the report finishes, a summary of the report is displayed. The results of the report are saved to the folder of the project or solution that was analyzed.
+
+   :::image type="content" source="./media/upgrade-assistant-how-to-analyze/cli-upgrade-end.png" alt-text="A terminal showing the results of the analysis command when using the .NET Upgrade Assistant Global Tool.":::
+
+## Related content
+
+- [What is code analysis with .NET Upgrade Assistant?](upgrade-assistant-analyze-overview.md)
+- [What is .NET Upgrade Assistant?](upgrade-assistant-overview.md)
+- [Install .NET Upgrade Assistant](upgrade-assistant-install.md)