Docs - GitHub Copilot App Modernization for .NET

docs/azure/migration/appmod/faq.md

@@ -0,0 +1,75 @@
+---
+title: GitHub Copilot App Modernization for .NET FAQ
+description: Frequently asked questions for the GitHub Copilot App Modernization for .NET
+ms.topic: concept-article
+ms.date: 07/03/2025
+---
+
+# Frequently asked questions
+
+This page answers some of the most common questions about the GitHub Copilot App Modernization for .NET tool.
+
+### Which Visual Studio version should I use?
+
+Please upgrade Visual Studio 2022 to the latest version (at least equal or above 17.14.7) to have better experience on both GitHub Copilot and App Modernization for .NET.
+
+### What is the MCP Server and why is there an initial delay when running a command sometimes?
+
+The GitHub Copilot App Modernization for .NET extension uses an `MCP Server` to provide Azure related knowledge bases as tools.
+
+- **Automatic setup**  
+  On the first invocation of any App Modernization command, the extension checks for a configuration file at `%USERPROFILE%\.mcp.json`. If it’s missing or the server isn’t running, the extension writes the default settings and launches the MCP Server automatically.
+
+- **First-run delay**  
+  Starting and initializing the MCP Server can take anywhere from a few milliseconds up to about 20 seconds.
+
+- **Subsequent invocations**  
+  Once the MCP Server is running locally, you shouldn’t see that startup delay again.
+
+- **Using MCP tools in the VS Copilot Agent out of extension**  
+  You can also access the same MCP-based knowledge tools inside the built-in VS Copilot Agent. Just run **Configure MCP Server**, and the full suite of MCP tools appears under the Copilot agent’s tools dropdown.
+
+### What should I do when configure MCP Server fails?
+
+If the MCP Server doesn’t start correctly, try the following:
+
+1. Retry the **Configure MCP Server** command.  
+2. If it still fails, manually restart the MCP Server:
+   1. Switch the Github Copilot to **Agent** mode.  
+   1. Click the **Tools** icon in the pane.  
+   1. Expand the **appModernization** section by clicking the arrow icon next to it.  
+   1. Click **Restart** to relaunch the MCP Server.
+
+### How can I monitor the assessment progress?
+
+While the assessment is running, you can monitor its progress by viewing the command-line output:
+
+1. In Visual Studio, go to **View** > **Output** to open the Output window.
+1. In the Output window, find the **Show output from:** dropdown.
+1. Select **AppModernizationExtension** from the dropdown list.
+1. The command-line output from the assessment tool appears here, showing real-time progress.
+
+You can also access the Output window using the keyboard shortcut **Ctrl+Alt+O**.
+
+### What should I do if Visual Studio fails to install AppCAT?
+
+If you see an AppCAT installation failure in the command-line output when the extension tries to install it automatically, you can install AppCAT manually:
+
+1. Follow the instructions in [Install the .NET global tool](/dotnet/azure/migration/appcat/install#install-the-net-global-tool).
+1. After successful installation, run the assessment again.
+
+### What should I do if I see "Command failed: No .NET SDKs were found" errors?
+
+This error occurs when AppCAT can't find a compatible .NET SDK, even if you have other .NET SDKs installed. AppCAT requires .NET 8 SDK to run properly.
+
+To fix this error:
+
+1. Download and install .NET 8 SDK from <https://dotnet.microsoft.com/download/dotnet/8.0>.
+1. Restart Visual Studio.
+1. Run the assessment again.
+
+### Does the tool store my source code?
+
+No. The tool uses GitHub Copilot in the same way you use it to modify code, which doesn't retain code snippets beyond the immediate session. Telemetry metrics are collected and analyzed to track feature usage and effectiveness.
+
+For more information, see the [Microsoft Privacy Statement](https://go.microsoft.com/fwlink/?LinkId=521839).

docs/azure/migration/appmod/overview.md

@@ -0,0 +1,62 @@
+# What is GitHub Copilot App Modernization for .NET?
+
+GitHub Copilot App Modernization for .NET aims to help enterprises migrate their .NET applications to Azure with confidence and efficiency, covering assessment, code remediation and validation, powered by the intelligence of GitHub Copilot.
+
+## Assessment of modernization issues
+
+App Modernization for .NET evaluates the readiness of developer's applications for migration to Azure, with an interactive experience on Visual Studio, powered by [AppCAT for .NET](../appcat/install.md).
+
+![Assessment](media/overview_assessment.png)
+
+## Solution recommendations
+
+App modernization for .NET recommends target Azure services for the resource dependencies of developer's application, for each category of assessed issues.
+
+![Solution](media/overview_solution.png)
+
+## Code remediation for common issues
+To accelerate code changes for [common modernization issues](predefined-tasks.md), the developer may apply predefined tasks (code change patterns) that represent best practices from experts.
+
+![Apply Task](media/overview_remediation.png)
+
+## Automatic fix for compilation errors
+
+After applying tasks, app modernization for .NET will automatically find and fix compilation errors introduced by the code changes.
+
+
+# How do I get started?
+
+To use App Modernization for .NET, you need:
+- [A GitHub account with GitHub Copilot enabled](https://github.com/features/copilot)
+    - Pro, Pro+, Business or Enterprise plan is needed
+- [The GitHub Copilot extension](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot)
+    - The latest version is recommended
+- [AppCAT for .NET](../appcat/install.md)
+    - For the assessment feature of GitHub Copilot app modernization for .NET
+
+# Feedback
+
+We value your feedback — share [your thoughts here](https://aka.ms/AM4JFeedback) to help us continue improving the product.
+
+# License
+
+This extension is licensed under [GitHub Copilot Product Specific Terms](https://github.com/customer-terms/github-copilot-product-specific-terms).
+
+# Trademarks
+
+This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft trademarks or logos is subject to and must follow [Microsoft's Trademark & Brand Guidelines](https://www.microsoft.com/en-us/legal/intellectualproperty/trademarks/usage/general). Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship. Any use of third-party trademarks or logos are subject to those third-party's policies.
+
+# Privacy statement
+
+App Modernization for .NET uses GitHub Copilot just like how you modify code with GitHub Copilot, which does not retain code snippets beyond the immediate session. Telemetry metrics are collected and analyzed to track feature usage and effectiveness. Please review the [Microsoft Privacy Statement](https://go.microsoft.com/fwlink/?LinkId=521839) if necessary.
+
+# Transparency note
+
+App Modernization for .NET uses GitHub Copilot to make code changes, and AI sometimes makes mistakes. Please carefully review and test the code changes made by the tool, before using them on your production environment.
+
+# More information
+
+Here is some documentation that may be helpful.
+* [Common modernization issues with predefined tasks](predefined-tasks.md)
+* [Quickstart on assessing an application and applying code changes](quick-start.md)
+* [Frequently Asked Questions](faq.md)

docs/azure/migration/appmod/predefined-tasks.md

@@ -0,0 +1,31 @@
+# Predefined tasks for GitHub Copilot App Modernization for .NET
+
+This article describes the predefined tasks available for GitHub Copilot App Modernization for .NET.
+
+Predefined tasks capture industry best practices for using Azure services. Currently, App Modernization for .NET offers predefined tasks that cover common migration scenarios. These tasks address the following subjects, and more:
+
+- Secret management
+- Message queue integration
+- Database migration
+- Identity management
+
+## Predefined Task list
+- Migrate to Managed Identity based Database on Azure, including Azure SQL DB and Azure PostgreSQL
+    - migrate from DB2, Oracle DB to Azure PostgreSQL
+    - migrate from local/on-prem SQL server to Azure SQL DB
+- Migrate to Azure File Storage
+    - migrate from file IO in local file system
+- Migrate to Azure Blob Storage
+    - migrate from on-prem or cross-cloud object storages
+    - migrate from file IO in local file system
+- Migrate to Microsoft Entra ID
+    - migrate from Windows AD
+- Migrate to secured crendentials with Managed Identity and Azure KeyVault
+    - migrate from plaintext credentials in configuration or code
+- Migrate to Azure Service Bus
+    - migrate from Microsoft Message Queue (MSMQ)
+    - migrate from RabbitMQ
+- Migrate to Azure Communication Service email
+    - migrate from using SMTP protocol to send emails
+- Migrate to Confluent Cloud/Azure Event Hub for Apache Kafka
+    - migrate from local/on-prem Kafka

docs/azure/migration/appmod/quick-start.md

@@ -0,0 +1,67 @@
+# Quickstart: assess and migrate a .NET project using GitHub Copilot App Modernization for .NET
+
+This quickstart shows you how to use GitHub Copilot App Modernization for .NET to assess and migrate a .NET project. In this quickstart, you install and configure the extension, then assess and migrate a sample project. 
+
+## Prerequisites
+
+- A GitHub account with [GitHub Copilot](https://github.com/features/copilot) enabled. Pro, Pro+, Business or Enterprise plan is needed.
+- The latest version of [Visual Studio 2022](https://visualstudio.microsoft.com/zh-hans/downloads/). Must be version 17.14.7 or later.
+- Enable agent mode for VS GitHub Copilot [Use Copilot agent mode](https://learn.microsoft.com/en-us/visualstudio/ide/copilot-agent-mode?view=vs-2022).
+
+## Sign in to use Copilot and then install App Modernization extension
+
+To use GitHub Copilot, sign in to your GitHub account in Visual Studio. Select the Copilot icon at the top of Visual Studio to access the GitHub Copilot pane. For more information about setting up GitHub Copilot, see [Set up GitHub Copilot in Visual Stuido](https://learn.microsoft.com/en-us/visualstudio/ide/visual-studio-github-copilot-install-and-states?view=vs-2022).
+
+Then, use the following steps to install GitHub Copilot App Modernization for .NET:
+1. In Visual Studio, navigate to `Extensions -> Manage Extensions`.
+1. Search for `Github Copilot App Modernization for .NET` in the marketplace.
+1. On the extension page, select `Install`. 
+1. There will be notification bar showing up to guide you close Visual Studio to install the extension.
+1. Launch Visual Studio after installation.
+
+For more information, see [Find, install, and manage extensions for Visual Studio](https://learn.microsoft.com/en-us/visualstudio/ide/finding-and-using-visual-studio-extensions?view=vs-2022).
+
+## Assess application readiness
+
+Use the following steps to start your migration process with assessment. This assessment helps you understand what your application readiness challenges are and how impactful they are, provides recommended solutions. A solution recommendation includes references to set up Azure resources, add configurations, and make code changes.
+
+1. Clone the [.NET migration copilot samples](https://github.com/Azure-Samples/dotnet-migration-copilot-samples) repository.
+1. In Visual Studio, open the **Contoso University** project folder in the samples repository.
+1. Three ways to start the assessment:
+    - [Option 1] Right click on the solution, navigate through `GitHub Copilot App Moderniation for .NET -> Run Assessment`![from solution menu to start assessment](media/solution-start-assessment.png)
+    - [Option 2] On the top menu, navigate through `Extensions -> GitHub Copilot App Moderniation for .NET -> Run Assessment` ![from entension menu to start assessment](media/extension-start-assessment.png)
+    - [Option 3] In the feature search panel (ctrl + shift + p), search for `Run Assessment`
+1. Then a background task will be triggered and after a while, an assessment report tab will be shown. (Note that there will be a small icon in the left bottom corner indicating the background running task on-going)
+![assessment report](media/assessment-report.png)
+
+## Start a migration
+
+ GitHub Copilot App Modernization for .NET provides predefined tasks for common migration scenarios using Microsoft's best practice.
+
+ You can start the migration with a simple click on the `Migrate` button in the `Assessment Report` generated in last step.
+
+ > If you are clear with the migration scenario you want to migrate, you can navigate through `GitHub Copilot App Moderniation for .NET -> Migration Tasks` and select the proper task to start a migration.
+
+ ### Plan and progress tracker generation
+
+ Once you started the migration, a GitHub Copilot session will be started with our pre-defined prompts sent to GitHub Copilot in agent mode. This step will create two files under folder `.appmod/.migration`:
+ - plan.md - This file acts as the plan for the overall migration
+ - progress.md - This file acts as the progress tracker of the entire migration process, GitHub Copilot will mark items when it finishes a specific task in the progress tracker file. 
+ > You can modify these two files to include your customizations before going into the next step.
+
+
+### Start code remediation
+
+If you are satisfied with the two files generated, just prompt like `The plan and progress tracker look good to me. Go ahead with the migration.`
+
+Then GitHub Copilot will start the migration process. It may ask for your approval to call knowledge base tools in the MCP server provided by the extension, please grant the permission for such operations.
+
+Basically, GitHub Copilot will follow the plan and progress tracker to do the following tasks:
+1. Dependency management
+1. Configuration changes
+1. Code changes
+1. ​​Build the entire solution, fix all compilation/configuration errors, and ensure a successful build
+
+## Next step
+[Predefined Tasks](predefined-tasks.md)
+[FAQ](faq.md)

docs/azure/migration/appmod/sample.md

@@ -0,0 +1,24 @@
+# Contoso University Management System Migration Sample for GitHub Copilot App Modernization for .NET
+
+To demonstrate GitHub Copilot App Modernization for .NET, we've provided a migration sample [Contoso University sample web app](https://github.com/Azure-Samples/dotnet-migration-copilot-samples/tree/main/ContosoUniversity).  
+
+This fictional university management system is originally built with .NET Framework 4.8 and contains functionalities such as student enrollment, course management, and instructor assignments. It uses legacy Windows-based components, including:
+
+- **SQL Server LocalDB** for database storage  
+- **Local file system** for file management  
+- **Microsoft Message Queue (MSMQ)** for notification messaging  
+
+## After Migration
+
+Using App Modernization for .NET, the sample can be updated to leverage modern, cloud-native Azure services, including:
+
+- **Azure SQL Database** replacing SQL Server LocalDB  
+- **Azure Blob Storage** replacing local file system access  
+- **Azure Service Bus** replacing MSMQ  
+- **Azure Key Vault** for secure secrets management  
+
+This migration showcases how legacy on-premises applications can be transformed into scalable, maintainable cloud-native solutions using GitHub Copilot and Azure services.
+
+## See Also
+
+- [Quickstart: assess and migrate a .NET project using GitHub Copilot App Modernization for .NET](quick-start.md)