Merge pull request #47469 from dotnet/main

Docs - GitHub Copilot App Modernization for .NET (#47083)

Author: BillWagner

docs/azure/migration/appmod/faq.md

@@ -0,0 +1,157 @@
+---
+title: GitHub Copilot app modernization for .NET (Preview) FAQ 
+description: Discover answers to common questions about GitHub Copilot app modernization for .NET 
+ms.topic: concept-article
+ms.custom: devx-track-dotnet
+ms.date: 7/15/2025
+author: alexwolfmsft
+ms.author: alexwolf
+---
+
+# Frequently Asked Questions for GitHub Copilot app modernization for .NET (Preview)
+
+This page answers common questions about [GitHub Copilot app modernization for .NET (Preview)](overview.md).
+
+## Which version of Visual Studio should I use?
+
+Upgrade to Visual Studio 2022 version 17.14.7 or later for the best experience with both GitHub Copilot and App Modernization for .NET (Preview).
+
+## Which model should I use in GitHub Copilot agent mode?
+
+Based on our experience, GitHub Copilot and App Modernization for .NET work best with Claude Sonnet 3.7 and Claude Sonnet 4.0.
+
+## What is the MCP Server, and why is there sometimes an initial delay when running a command?
+
+The GitHub Copilot app modernization for .NET (Preview) 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 should not see that startup delay again.
+
+- **Using MCP tools in the VS Copilot Agent (outside the 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 if configuring the MCP Server fails?
+
+If the MCP Server doesn't start correctly, try the following steps:
+
+1. Retry the **Configure MCP Server** command.
+2. If it still fails, manually restart the MCP Server:
+   1. Switch GitHub Copilot to **Agent** mode.
+   2. Click the **Tools** icon in the pane.
+   3. Expand the **appModernization** section by clicking the arrow icon next to it.
+   4. Click **Restart** to relaunch the MCP Server.
+
+## Why is there an error in the "appModernization" group under Tools in GitHub Copilot Agent mode after uninstalling the extension, and how can I fix it?
+
+When the extension is installed, it adds a configuration entry to `%USERPROFILE%\.mcp.json` to register the `appModernization` tool with GitHub Copilot Agent in Visual Studio. This enables the `Tools → appModernization` group within Copilot Agent mode.
+After the extension is uninstalled, this configuration remains. Since the associated command no longer exists, GitHub Copilot Agent mode displays a red error indicator next to the `appModernization` group.
+
+To resolve this:
+
+- **Edit `%USERPROFILE%\.mcp.json`**
+
+   Open the file in a text editor and remove the `"appModernization"` entry from the `"servers"` section.
+   Save the file after removing this block.
+- **Or delete the file entirely**
+
+   If `.mcp.json` contains no other important configuration, you may simply delete the file.
+
+Once cleaned up, the error in the `Tools → appModernization` group will no longer appear.
+
+## How can I monitor 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.
+2. In the Output window, find the **Show output from:** dropdown.
+3. Select **AppModernizationExtension** from the dropdown list.
+4. 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. Open a command prompt or PowerShell as Administrator.
+2. Run the appropriate command based on your shell:
+
+   **For Command Prompt:**
+
+   ```cmd
+   dotnet tool install dotnet-appcat --tool-path "%LOCALAPPDATA%\Microsoft\VisualStudio\AppModernizationExtension\Tools"
+   ```
+
+   **For PowerShell:**
+
+   ```powershell
+   dotnet tool install dotnet-appcat --tool-path "$env:LOCALAPPDATA\Microsoft\VisualStudio\AppModernizationExtension\Tools"
+   ```
+
+3. After successful installation, run the assessment again.
+
+> [!IMPORTANT]
+> Installing this tool may fail if you've configured additional NuGet feed sources. Use the `--ignore-failed-sources` parameter to treat those failures as warnings instead of errors.
+
+### What should I do if Visual Studio fails to upgrade AppCAT?
+
+If Visual Studio fails to automatically upgrade AppCAT when a new version is available, you can upgrade it manually:
+
+1. Open a command prompt or PowerShell as Administrator.
+2. Run the appropriate command based on your shell:
+
+   **For Command Prompt:**
+
+   ```cmd
+   dotnet tool update dotnet-appcat --tool-path "%LOCALAPPDATA%\Microsoft\VisualStudio\AppModernizationExtension\Tools"
+   ```
+
+   **For PowerShell:**
+
+   ```powershell
+   dotnet tool update dotnet-appcat --tool-path "$env:LOCALAPPDATA\Microsoft\VisualStudio\AppModernizationExtension\Tools"
+   ```
+
+3. After successful upgrade, run the assessment again.
+
+## What should I do if I see "Command failed: No .NET SDKs were found" errors?
+
+This error occurs when AppCAT cannot find a compatible .NET SDK, even if you have other .NET SDKs installed. AppCAT requires the .NET 8.0 SDK to run properly.
+
+To fix this error:
+
+1. Download and install the .NET 8 SDK from <https://dotnet.microsoft.com/download/dotnet/8.0>.
+2. Restart Visual Studio.
+3. 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, and 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).
+
+## What are the intended uses of GitHub Copilot app modernization for .NET (Preview)?
+
+GitHub Copilot app modernization for .NET (Preview) is designed to help enterprises migrate their .NET applications to Azure. It assesses application code issues that need to be addressed for migration and provides code remediation patterns that can be applied with AI.
+
+## How was GitHub Copilot app modernization for .NET (Preview) evaluated? What metrics are used to measure performance?
+
+GitHub Copilot app modernization for .NET (Preview) was evaluated through extensive manual and automated testing. Additional evaluation was performed using custom datasets for offensive and malicious prompts (user questions) and responses. The tool is also continuously evaluated with user feedback.
+
+## What are the limitations of GitHub Copilot app modernization for .NET (Preview)?
+
+GitHub Copilot app modernization for .NET (Preview) can be used on application source code written in .NET Framework or .NET Core. Applications in other languages are not supported.
+
+## What operational factors and settings allow for effective and responsible use of GitHub Copilot app modernization for .NET (Preview)?
+
+You can choose the model to make code changes at the bottom of the GitHub Copilot chat box. Different models may produce different results and have varying token consumption. For more information, see [Manage Copilot usage and models](/visualstudio/ide/copilot-usage-and-models).
+
+## How do I provide feedback on GitHub Copilot app modernization for .NET (Preview)?
+
+We value your feedback—share [your thoughts here](https://aka.ms/AM4DFeedback) to help us continue improving the product.

docs/azure/migration/appmod/media/extension-start-assessment.png

@@ -0,0 +1,86 @@
+---
+title: Overview of GitHub Copilot app modernization for .NET (Preview)
+description: Learn about essential concepts for GitHub Copilot app modernization for .NET 
+ms.topic: concept-article
+ms.custom: devx-track-dotnet
+ms.date: 7/15/2025
+author: alexwolfmsft
+ms.author: alexwolf
+---
+
+# GitHub Copilot app modernization for .NET (Preview) overview
+
+[GitHub Copilot app modernization for .NET (Preview)](https://marketplace.visualstudio.com/items?itemName=vscjava.appmod-dotnet) helps you migrate .NET applications to Azure quickly and confidently by guiding you through assessment, solution recommendations, code fixes, and validation - all in one tool.
+
+With this assistant, you can:
+
+- Assess your application's code, configuration, and dependencies.
+- Plan and set up the right Azure resource
+- Fix issues and apply best practices for cloud migration
+- Validate that your app builds and tests successfully
+
+This process streamlines modernization and boosts developer productivity and confidence. App Modernization for .NET is an all-in-one migration assistant that uses AI to improve developer velocity, quality, and results.
+
+App Modernization for .NET is provided as a Visual Studio extension and relies on the following tools to be installed and configured for the full experience:
+
+- [A GitHub account with GitHub Copilot enabled](https://github.com/features/copilot) (Pro, Pro+, Business, or Enterprise plan required)
+- [The GitHub Copilot extension](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot) for Visual Studio (latest version recommended)
+- [Azure Migrate application and code assessment for .NET](../appcat/install.md) for assessment features
+
+For a complete walkthrough of setting up and using GitHub Copilot app modernization for .NET, see [Quickstart: Assessing an application and applying code changes](quickstart.md).
+
+## Key Concepts
+
+GitHub Copilot app modernization for .NET supports end-to-end migration to Azure, including assessment, planning, code remediation, build fixes, and unit test fixes. It uses GitHub Copilot AI capabilities to help you migrate and run your applications on Azure with confidence, accelerating the entire modernization lifecycle.
+
+The tool also relies on [Azure Migrate application and code assessment (AppCAT)](../appcat/app-code-assessment-toolkit.md) to analyze your code and identify modernization opportunities. You can use GitHub Copilot app modernization for .NET to get an overview of cloud readiness migration issues, including:
+
+- Best practice recommendations
+- Suggestions for changing your application code
+
+When code changes are needed, the tool guides you through remediation using predefined tasks for common issues, such as:
+
+- Switching from password-based authentication to managed identities
+- Moving from AWS S3 to Azure Blob Storage
+
+For more information, see [Predefined tasks](predefined-tasks.md).
+
+## Common Use Cases
+
+App Modernization for .NET (Preview) supports the following scenarios:
+
+- **Assessment of modernization issue**  
+
+    Evaluates your application's readiness for Azure migration in Visual Studio, powered by [AppCAT for .NET](../appcat/install.md).
+
+![Assessment](media/overview_assessment.png)
+
+- **Solution recommendations**  
+
+    Recommends target Azure services for your application's resource dependencies, tailored to each category of assessed issues.
+
+![Solution](media/overview_solution.png)
+
+- **Code remediation for common issues**
+
+    Accelerates code changes for [common modernization issues](predefined-tasks.md) by applying predefined tasks that represent expert best practices.
+
+![Apply Task](media/overview_remediation.png)
+
+- **Automatic fixes for compilation errors:**  
+
+    Automatically discovers and fixes compilation errors introduced by code changes.
+
+## Feedback and Privacy
+
+- **Feedback:** We value your feedback—share [your thoughts here](https://aka.ms/AM4DFeedback) to help us improve the product.
+- **License:** This extension is licensed under the [GitHub Copilot Product Specific Terms](https://github.com/customer-terms/github-copilot-product-specific-terms).
+- **Trademarks:** This project might 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 is subject to those third parties' policies.
+- **Privacy:** App Modernization for .NET (Preview) uses GitHub Copilot in the same way you use it to modify code, and doesn't retain code snippets beyond the immediate session. Telemetry metrics are collected and analyzed to track feature usage and effectiveness. Review the [Microsoft Privacy Statement](https://go.microsoft.com/fwlink/?LinkId=521839) for more information.
+- **Transparency:** App Modernization for .NET (Preview) uses GitHub Copilot to make code changes, and AI might sometimes make mistakes. Carefully review and test any code changes made by the tool before using them in your production environment.
+
+## Next Steps
+
+- [Quickstart: Assessing an application and applying code changes](quickstart.md)
+- [Common modernization issues with predefined tasks](predefined-tasks.md)
+- [Frequently Asked Questions](faq.md)

docs/azure/migration/appmod/media/overview_assessment.png

@@ -0,0 +1,56 @@
+---
+title: Predefined tasks for GitHub Copilot app modernization for .NET (Preview)
+description: Learn about the predefined tasks that are available for GitHub Copilot app modernization for .NET
+ms.topic: concept-article
+ms.custom: devx-track-dotnet
+ms.date: 7/15/2025
+author: alexwolfmsft
+ms.author: alexwolf
+---
+
+# Predefined tasks for GitHub Copilot app modernization for .NET (Preview)
+
+This article describes the predefined tasks available for GitHub Copilot app modernization for .NET (Preview).
+
+Predefined tasks capture industry best practices for using Azure services. Currently, App Modernization for .NET (Preview) 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
+
+App Modernization for .NET currently supports the following predefined tasks:
+
+- **Migrate to Managed Identity based Database on Azure, including Azure SQL DB and Azure PostgreSQL**
+  
+  Modernize your data layer by migrating from on-premises or legacy databases (such as DB2, Oracle DB, or SQL Server) to Azure SQL DB or Azure PostgreSQL, using secure managed identity authentication.
+
+- **Migrate to Azure File Storage**
+  
+  Move file I/O operations from the local file system to Azure File Storage for scalable, cloud-based file management.
+
+- **Migrate to Azure Blob Storage**
+  
+  Replace on-premises or cross-cloud object storage, or local file system file I/O, with Azure Blob Storage for unstructured data.
+
+- **Migrate to Microsoft Entra ID**
+  
+  Transition authentication and authorization from Windows Active Directory to Microsoft Entra ID (formerly Azure AD) for modern identity management.
+
+- **Migrate to secured credentials with Managed Identity and Azure Key Vault**
+  
+  Replace plaintext credentials in configuration or code with secure, managed identities and Azure Key Vault for secrets management.
+
+- **Migrate to Azure Service Bus**
+  
+  Move from legacy or third-party message queues (such as MSMQ or RabbitMQ) to Azure Service Bus for reliable, cloud-based messaging.
+
+- **Migrate to Azure Communication Service email**
+  
+  Replace direct SMTP email sending with Azure Communication Service for scalable, secure email delivery.
+
+- **Migrate to Confluent Cloud/Azure Event Hub for Apache Kafka**
+  
+  Transition from local or on-premises Kafka to managed event streaming with Confluent Cloud or Azure Event Hubs.