Aplicar instrucciones de actualización personalizadas para actualizaciones de .NET

Las instrucciones de actualización personalizadas son archivos Markdown que guían el proceso de modernización de GitHub Copilot para aplicar transformaciones específicas durante una actualización. Cree estos archivos para automatizar los cambios repetitivos, como reemplazar una biblioteca por otra o aplicar una actualización de API específica.

En este artículo se explica cómo crear y estructurar un archivo de instrucciones de actualización personalizado, probarlo de forma aislada e integrarlo en la fase de evaluación de un flujo de trabajo de actualización.

Prerrequisitos

Configura la modernización de GitHub Copilot en tu entorno de desarrollo antes de crear instrucciones personalizadas. Para conocer los pasos de instalación, consulte Instalar la modernización de GitHub Copilot.

Descripción de las instrucciones de actualización personalizadas

La modernización de GitHub Copilot recupera las instrucciones de actualización personalizadas como archivos Markdown bajo demanda durante las fases de evaluación y planificación de una actualización. Las instrucciones de actualización personalizadas difieren de copilot-instructions.md porque son:

  • Dirigido a automatizar los cambios en el código y las dependencias.
  • Se recupera solo cuando es pertinente para la evaluación o el plan de actualización actual.
  • Reutilizable entre soluciones al ser copiado en cada repositorio.

Estructurar los archivos de instrucciones con:

  • Título corto que describe la acción. Por ejemplo, "reemplace Newtonsoft.Json por System.Text.Json".
  • Una instrucción de problema concisa o una sección de requisitos previos.
  • Lógica de paso explícita ("Si se encuentra X, haga Y"). Evite lenguaje impreciso.
  • (Recomendado) Uno o más ejemplos de diferencias en código recopilados a partir de ediciones locales reales para orientar las transformaciones.

Más allá de las instrucciones de actualización personalizadas, puede ampliar la modernización de GitHub Copilot a través del sistema estándar de aptitudes e instrucciones. Las aptitudes agregan funcionalidades al agente y los archivos de instrucciones (como copilot-instructions.md) proporcionan instrucciones globales.

Creación de una instrucción de actualización personalizada

Siga estos pasos para generar y refinar un nuevo archivo de instrucciones. Estas secciones se centran en reemplazar Newtonsoft.Json por System.Text.Json como ejemplo.

  1. En la ventana Explorador de soluciones, haga clic con el botón derecho en el solution>Modernize.

    O bien

    Abra el panel de chat de Copilot y escriba @Modernize para iniciar una conversación con el agente.

    Nota:

    Estos pasos se aplican a Visual Studio. En Visual Studio Code y otros entornos, invoque el agente de modernize-dotnet directamente desde el panel de chat de Copilot. En Visual Studio, el agente se denomina Modernize.

  2. En el chat, escriba: I want to generate a custom upgrade instruction.

  3. Cuando se le pregunte, proporcione un escenario como I want to replace Newtonsoft with System.Text.Json para que Copilot cree el archivo.

  4. Cuando Copilot crea el nuevo archivo, como replace_newtonsoft_with_system_text_json.md, revise el contenido y afinalo en el chat. Por ejemplo, pida Copilot que "aclarar los criterios de detección" o "agregue una sección de requisitos previos".

    Sugerencia

    Agregue el archivo a la solución para ver si aún no está incluido.

  5. Fortalecer la instrucción con ejemplos de diferencias reales.

    1. Realice los cambios de código deseados manualmente en un proyecto. Por ejemplo, "eliminar el Newtonsoft.Json paquete, actualizar usando directivas y reemplazar JsonConvert el código por JsonSerializer."
    2. En chat, con el archivo de instrucciones abierto, escriba: Check my git changes and add diffs as examples to my instruction file.
    3. Confirma que Copilot usó un diferencial git y añadió un bloque de diferencial cercado o ejemplo estructurado al archivo Markdown.

Sugerencias para la creación de contenido

Siga estas instrucciones para escribir instrucciones de actualización personalizadas claras y eficaces que Copilot puedan interpretar de forma confiable:

  • Use expresiones condicionales claras: If code references X, then do Y.
  • Mantener una transformación por archivo; use los requisitos previos cuando se deben ejecutar varios archivos en secuencia.
  • Proporcione al menos un ejemplo concreto, como una diferencia o un fragmento de código anterior o posterior, para mejorar la precisión de la transformación.
  • Evite verbos ambiguos como "mejorar" o "corregir"; use acciones explícitas como "replace", "remove" y "update".

Prueba de una instrucción de actualización personalizada (ejecución única)

Antes de ejecutar la instrucción durante una actualización, valide la instrucción de forma aislada. Las pruebas aisladas le ayudan a refinar la detección y comprobar los cambios de código.

  1. En la ventana Explorador de soluciones, haga clic con el botón derecho en el solution>Modernize.

    Nota:

    Estos pasos se aplican a Visual Studio. En Visual Studio Code y otros entornos, invoque el agente de modernize-dotnet directamente desde el panel de chat de Copilot.

  2. En el chat, invoque la instrucción con texto similar al nombre de archivo. Por ejemplo: replace Newtonsoft with System.Text.Json.

  3. Confirme en la ventana de chat que Copilot recuperó el archivo de instrucciones:

    > Getting instructions for 'replace Newtonsoft with System.Text.Json'.

Perfect! I've retrieved the scenario instructions for upgrading from Newtonsoft.Json to System.Text.Json. Now I'll begin the analysis following the scenario-specific instructions.

    Si Copilot no indica que encontró las instrucciones, vuelva a intentarlo con palabras clave del nombre del archivo, como las mismas combinaciones de verbos y nombres.

  4. Revise los cambios propuestos (diferencias de solución, confirmaciones pendientes o modificaciones preliminares) para confirmar que la instrucción de actualización personalizada se comporta según lo previsto.

Sugerencias de validación

Si la ejecución de pruebas no genera los resultados esperados, use estas sugerencias de solución de problemas para refinar el archivo de instrucciones:

  • Si Copilot solo actualiza las versiones del paquete en lugar de reemplazar el paquete, asegúrese de que la instrucción dice explícitamente que quite o reemplace el paquete anterior.
  • Use nombres coherentes para que la activación en lenguaje natural coincida. Por ejemplo, inicie el nombre de archivo con replace_ y comience la solicitud de chat con "Reemplazar...".
  • Durante las pruebas, agregue los patrones de código que faltan como ejemplos para mejorar la cobertura.

Aplicar instrucciones personalizadas durante una actualización

Siga estos pasos para incorporar una instrucción de actualización personalizada existente en la fase de evaluación de una actualización.

  1. En la ventana Explorador de soluciones, haga clic con el botón derecho en el solution>Modernize.

    Nota:

    Estos pasos se aplican a Visual Studio. En Visual Studio Code y otros entornos, invoque el agente de modernize-dotnet directamente desde el panel de chat de Copilot.

  2. En el chat, elija Upgrade to a newer version of .NET. Responda a las preguntas de Copilot hasta que comience la evaluación.

  3. Supervise el chat para ver si Copilot recupera automáticamente el archivo de instrucciones personalizado durante la evaluación. Busque un mensaje que indique que abrió el archivo de instrucciones markdown.

    Si Copilot no aplica automáticamente las instrucciones personalizadas, solicite explícitamente. Use palabras similares al nombre de archivo. Por ejemplo: use the custom instructions to replace Newtonsoft with System.Text.Json during the assessment.

  4. Espere a que Copilot confirme que recuperó el archivo Markdown. Si no ve una referencia al archivo de instrucciones, reformule la solicitud utilizando los verbos clave del archivo (reemplazar, actualizar, quitar) y los nombres de paquete.

  5. Revise el archivo generado assessment.md en la .github/upgrades carpeta . Confirme que la evaluación incluye los problemas y cambios que han identificado las instrucciones personalizadas.

    Por ejemplo, al reemplazar Newtonsoft, la evaluación identifica:

    • Proyectos que usan Newtonsoft.Json paquetes.
    • Patrones de código a refactorizar para System.Text.Json.
    • Dependencias que necesitan ser quitadas o reemplazadas.

  6. Si es necesario, edite el assessment.md archivo para agregar contexto o ajuste los problemas identificados antes de continuar.

  7. Indique a Copilot continuar con la fase de planeación una vez que la evaluación refleje la instrucción personalizada.

  8. Revisa el archivo plan.md que Copilot genera. Este archivo incluye estrategias para abordar los problemas de la evaluación.

  9. Continúe con la fase de ejecución indicando a Copilot que continúe. Supervisa el archivo tasks.md mientras Copilot aplica las transformaciones.

Sugerencias para una mejor activación

El nombre e invocación de instrucciones de actualización personalizadas afecta a si Copilot las obtiene automáticamente. Siga estas instrucciones para mejorar la confiabilidad de la activación:

  • Coincide con el verbo del archivo. Si el nombre de archivo usa replace, use esa expresión (no upgrade o fix).
  • Mantenga una transformación por archivo para mayor claridad y reutilización. Secuenciar varios archivos enumerando los requisitos previos en cada archivo.
  • Solicite instrucciones personalizadas durante la fase de evaluación para obtener mejores resultados, en lugar de esperar hasta la planeación o ejecución.
  • Evite solicitudes ambiguas como "mejorar la evaluación". Sea explícito: "aplique las instrucciones de replace_newtonsoft_with_system_text_json durante la evaluación".

Validar los cambios aplicados

Una vez completada la actualización:

  1. Revise el tasks.md archivo en .github/upgrades para ver el estado de las tareas relacionadas con la instrucción personalizada.
  2. Compruebe las confirmaciones de Git creadas durante la fase de ejecución para ver los cambios relacionados con la instrucción personalizada.
  3. Ejecute las pruebas para asegurarse de que el comportamiento funcional sigue siendo correcto.
  4. Opcional: Capture un ejemplo de diferencia del cambio correcto y agréguelo al archivo de instrucciones para reforzar la automatización futura.

Limpieza de recursos

Quite o consolide los archivos de instrucciones temporales para evitar transformaciones superpuestas en futuras actualizaciones.

Contenido relacionado

  • Last updated on