DOCSEARCHbyAlgolia
Submit Docs

modernize-dotnet

repository·main·Indexed 22 days ago

https://github.com/dotnet/modernize-dotnet

An AI-powered agent designed to analyze, plan, and apply upgrades to .NET applications, facilitating migrations from .NET Framework to modern .NET and upgrading projects to the latest supported versions. It features a three-step workflow of assessment, planning, and execution, and can be integrated into Visual Studio, Visual Studio Code, the GitHub Copilot CLI, and as a Model Context Protocol (MCP) server. Note: This plugin is deprecated in favor of the upgrade-agent plugin.

Tokens
5.3K
Snippets
6
Records
25
Agent score
79%

What's inside modernize-dotnet

  1. How to use `get_state()` for workflow awareness

    main

    The get_state() tool is the primary mechanism for the agent to understand the current context. Because the CLI does not inject state automatically, you must call it to learn about the environment.

    When to call get_state()

    • At the start of every session: This is the mandatory first action to detect active scenarios or existing work on disk.
    • After completing tasks: To refresh the list of available or blocked tasks.
    • When status is requested: If a user asks "where are we?" or "what is the progress?".
    • When external changes occur: If the user manually edits files or another session has run.
    • After context compaction: If the conversation history becomes too large and you lose track of the current scenario or stage.

    Interpreting the response

    get_state() returns one of three states:

    1. Active scenario: hasActiveScenario: true. Use taskProgress.availableTasks to find the next step and check staleTaskWarnings.
    2. Existing scenarios on disk: hasActiveScenario: false but existingScenarios is present. Use resume_scenario with the appropriate ID to pick up where a previous session left off.
    3. No scenarios: A fresh start. Use get_scenarios() to match the user's request to a known workflow.

  3. How to use Skills for expert guidance

    main

    Skills are tested patterns and tool selection logic used to prevent mistakes during modernization. They provide binding guidance, meaning you must follow their prescribed decomposition patterns, specific tools, and ordering/gates exactly.

    Key Workflow Skills:

    • get_instructions(kind='skill', query='scenario-initialization'): Before initializing a new scenario.
    • get_instructions(kind='skill', query='task-execution'): Before working on tasks (assess, break down, execute, complete).
    • get_instructions(kind='skill', query='plan-generation'): Before creating plans.
    • get_instructions(kind='skill', query='state-management'): For workflow state operations.
    • get_instructions(kind='skill', query='tasks-consistency'): When get_state returns tasksOutOfSync.
    • get_instructions(kind='skill', query='user-interaction'): For communication patterns.
    • get_instructions(kind='skill', query='sub-agent-delegation'): Before delegating work to a sub-agent.

    Loading Skills:

    1. From start_task: Review <task_related_skills> in the response and read the corresponding {path}/skill.md files.
    2. By Search: Use get_instructions(kind='skill', query='<topic>') for specific requests (e.g., query='asp.net core controller migration') or when encountering unexpected errors.

  4. Configure Flow Mode for the Modernization Agent

    main

    Flow mode determines how much autonomy the agent has versus how often it pauses for your review. You can set this during pre-initialization or switch modes mid-session.

    Available Modes

    ModeBehaviorDefault
    AutomaticRuns end-to-end. It surfaces assessments, plans, and progress but does not wait for approval unless it encounters a genuine block (missing info or high-consequence decisions).✅ Yes
    GuidedCautious approach. The agent pauses after every major stage (assessment, planning, complex breakdowns) for explicit user review and approval.

    Mid-Session Mode Switching

    You can change the behavior at any time by using natural language commands:

    • To switch to Guided: Use commands like "pause", "hold on", "let me review this", or "switch to guided".
    • To switch to Automatic: Use commands like "just go", "keep going without stopping", "switch to automatic", or "don't wait for me".

    When a switch is detected, the agent updates scenario-instructions.md under ## Preferences > Flow Mode immediately without requiring a restart.

  5. Follow Workflow Rules and Integrity

    main

    The workflow stages and artifact generation steps are a contract. You may apply judgment within a step, but you must not skip steps, omit required artifacts, or restructure the workflow.

    Core Workflow Rules:

    • Load scenario instructions FIRST: Use get_instructions(kind='scenario', ...) before any upgrade work.
    • Pre-initialize: Load scenario-initialization skill and gather parameters (source control, scenario-specific, flow mode) for user confirmation.
    • Source Control: Handle pending changes and switch to a working branch BEFORE calling initialize_scenario.
    • Flow Modes:
      • Automatic (default): Only pause when blocked (missing info, ambiguous decisions, errors).
      • Guided: Pause after assessment, after plan generation, and after complex breakdowns for explicit approval.
    • Artifact Visibility: Always print the full paths to key artifacts (e.g., assessment.md, plan.md, tasks.md) when created or updated.
    • State Management: Use tools for state changes; never edit tasks.md structure directly. Never create task folders or task.md files manually; use start_task or break_down_task.
    • Build Integrity: Fix all build warnings after every task. Treat warnings as errors. Never suppress warnings (e.g., #pragma warning disable) without explicit user approval.

  6. Use the modernize-dotnet agent for .NET upgrades

    main

    To use the agent, select it using the /agent command in your Copilot CLI and then provide a prompt describing your upgrade goal (e.g., upgrading to a specific .NET version).

    The agent follows a three-step workflow:

    1. Assessment: Analyzes the project to identify necessary changes.
    2. Planning: Generates a step-by-step upgrade plan.
    3. Execution: Applies changes using specialized tools.

  8. The Task Execution Flow

    main

    To ensure high-quality modernization, every task must follow a specific lifecycle. Before starting any task, load the task-execution skill: get_instructions(kind='skill', query='task-execution').

    Standard Task Lifecycle

    1. Start: Call start_task(taskId).
    2. Load Skills: Read every skill listed in <task_related_skills> from the response. If a skill covers any part of your intended work, load it immediately.
    3. Decompose (Optional): If the scope is unknown or complex, use break_down_task(taskId, subtasksJson). Note that if a loaded skill prescribes a specific breakdown pattern, that pattern is mandatory.
    4. Research (Hard Gate): Before writing code, you must enrich tasks/{taskId}/task.md with findings (affected files, dependencies, discovered patterns). No code changes should occur until this research is documented.
    5. Execute: Perform the code changes.
    6. Validate: Run builds and tests.
    7. Document Progress: Write the changes to tasks/{taskId}/progress-details.md.
    8. Complete: Call complete_task(taskId, filesModified, executionLogSummary).
    9. Next Step: Depending on the flow mode:
      • Automatic: Immediately call start_task(nextTaskId) if available.
      • Guided: Pause for user approval before the next task.

  9. Persist user preferences in scenario-instructions.md

    main

    Because CLI sessions are stateless, scenario-instructions.md acts as the persistent memory for a scenario. You must immediately save any user preference, choice, or decision to this file to ensure it is remembered in future sessions.

    What to save:

    • REMEMBER requests: Anything explicitly marked as "Remember that..." or "Keep in mind...".
    • Explicit preferences: Version choices (e.g., "Use version X"), skipping certain steps, or preferred tools.
    • Implicit preferences: User approvals of suggestions or corrections made by the user.
    • Decisions with context: Resolved trade-offs or scope clarifications.

    Where to save (Append to appropriate sections):

    • ## User Preferences > ### Technical Preferences: Package versions, framework choices.
    • ## User Preferences > ### Execution Style: Pace, risk tolerance.
    • ## User Preferences > ### Custom Instructions > #### {taskId}: Task-specific rules.
    • ## Decisions: Decisions accompanied by context.

  10. Recover context after compression or new sessions

    main

    If you suspect context compression (e.g., you remember a skill was loaded but not its instructions, or you cannot recall recent tool outputs), follow these standard recovery steps to re-establish state:

    1. Call get_state(): To learn the current scenario, task progress, and available/blocked tasks.
    2. Read scenario-instructions.md: To retrieve persistent memory (preferences, decisions, strategy, and flow mode).
    3. Read the tail of execution-log.md: To see a chronological record of the last 30-50 lines of activity.
    4. Read tasks/{taskId}/task.md: If a task is currently in progress, to recover working memory for that specific task.

    Intent Mapping:

    • Recent activity: Check the tail of execution-log.md.
    • Task-specific history: Check tasks/{taskId}/task.md.
    • Overall status: Use get_state() and tasks.md.
    • Full history: Read the entire execution-log.md.

  11. Setup modernize-dotnet in GitHub Copilot CLI

    main

    The modernize-dotnet plugin adds a modernization agent to the GitHub Copilot CLI.

    Prerequisites

    • GitHub Copilot CLI installed
    • GitHub Copilot subscription (paid or free)

    Installation Steps

    1. Add the marketplace:
      /plugin marketplace add dotnet/modernize-dotnet
    2. Install the plugin:
      /plugin install modernize-dotnet@modernize-dotnet-plugins
    3. Select the agent: Use /agent to select modernize-dotnet.
    4. Prompt the agent:
      upgrade my project to .NET 10

    Note: You may need to restart Copilot CLI after installing the plugin before the agent becomes available.

    /plugin marketplace add dotnet/modernize-dotnet
/plugin install modernize-dotnet@modernize-dotnet-plugins
/agent modernize-dotnet
upgrade my project to .NET 10

  12. Setup modernize-dotnet in Visual Studio Code

    main

    Use the modernize-dotnet agent in VS Code to analyze applications and generate upgrade plans for .NET.

    Prerequisites

    • Visual Studio Code
    • GitHub Copilot extension installed
    • GitHub Copilot subscription (paid or free)

    Installation Steps

    1. Install the GitHub Copilot modernization extension from the VS Code Marketplace.
    2. Open a workspace containing your .NET project.
    3. Open Copilot Chat and select modernize-dotnet from the Agent picker.
    4. Prompt the agent with your goal, e.g., upgrade my project to .NET 10.