Solución de problemas de modernización de GitHub Copilot

En este artículo se abordan los problemas comunes que pueden surgir al usar la modernización de .NET con GitHub Copilot, organizados por categoría. Cada entrada sigue un problema, causa y formato de solución para que pueda encontrar y resolver problemas rápidamente.

Problemas de flujo de trabajo

Estos problemas se relacionan con la detección de escenarios, la reanudación del trabajo y el estado de la tarea.

El agente dice "no se encontraron escenarios"

Cause: El agente no reconoce el área de trabajo como un proyecto de .NET.

Solution:

1. Compruebe que la raíz del área de trabajo contiene un archivo .sln, .csproj o .vbproj.
2. Pregunte al agente: "¿Qué solución o archivo de proyecto está usando?"
3. Si el archivo de solución o proyecto está en un subdirectorio, abra ese directorio como raíz del área de trabajo o apunte el agente al archivo explícitamente.

El agente no puede reanudar el trabajo anterior

Causa: La .github/upgrades/ carpeta, donde el agente almacena todo su estado, falta o está dañada.

Solution:

1. Compruebe si la carpeta existe en la .github/upgrades/ raíz del repositorio.
2. Si eliminó accidentalmente la carpeta, inicie el escenario nuevo. El agente no se puede recuperar sin sus archivos de estado.
3. Si la carpeta existe pero los archivos parecen estar corruptos, pida al agente que "evalúe nuevamente y replanee" para regenerarlos.

Tareas bloqueadas en curso

Causa: La sesión anterior finalizó mientras el agente estaba a mitad de una tarea.

Solution:

1. El agente detecta automáticamente tareas obsoletas en la mayoría de los casos. Indique al agente "reanudar" o "reiniciar la tarea actual".
2. Si el estado bloqueado persiste, indique al agente "marcar la tarea actual como pendiente y reiniciarla" o "reassess y continuar desde el último paso completado".
3. Compruebe el archivo correspondiente progress-details.md para comprender dónde se detuvo la sesión anterior.

El agente sigue sugiriendo el escenario incorrecto

Causa: El análisis del agente ha recogido características inesperadas del proyecto e infiere un escenario diferente al previsto.

Solution:

Sé explícito sobre lo que quieres. En lugar de "actualizar mi proyecto", diga:

• "Quiero actualizar a .NET 10."
• "Quiero actualizar de Newtonsoft.Json a System.Text.Json."
• "Convertir mi proyecto en formato de estilo SDK".

Agregue preferencias de escenario a scenario-instructions.md para evitar errores de coincidencia futuros.

Problemas de construcción y compilación

Estos problemas se relacionan con errores de compilación, problemas de restauración de NuGet y errores de generación de código.

La compilación falla tras los cambios del agente

Causa: Las actualizaciones pueden introducir cambios importantes en la API, paquetes que faltan o patrones de código incompatibles.

Solution:

1. Informe al agente sobre el error. El agente analiza los errores automáticamente.
2. Si el agente no puede resolver el problema, revierta la última confirmación (git revert HEAD) y pida al agente que pruebe otro enfoque.
3. En el caso de errores complejos, compruebe execution-log.md para entender qué cambió el agente y en qué orden.

Error en la restauración de NuGet

Causa: Incompatibilidad de paquetes con el marco de destino o errores de autenticación con fuentes privadas de NuGet.

Solution:

• Para fuentes privadas: Autentíquese en la fuente antes de iniciar la actualización.
• Para paquetes incompatibles: Indique al agente qué paquete es problemático. El agente puede buscar versiones compatibles o sugerir paquetes alternativos.
• Para problemas de conectividad de fuentes: Compruebe que puede ejecutar dotnet restore manualmente. Corrija primero los problemas de fuente y, a continuación, deje que el agente vuelva a intentarlo.

El agente genera código que no se compila

Causa: El código generado por ia puede contener errores, especialmente en casos perimetrales o con patrones de API poco comunes.

Solution:

1. El agente detecta automáticamente errores de compilación. Si el agente tiene dificultades, proporcione instrucciones o corrija el código manualmente e indique al agente que continúe.
2. Si el agente tiene problemas con una corrección específica después de varios intentos, edite el código manualmente e indique al agente: "He corregido el error de compilación en MyClass.cs, marque esta tarea completa".
3. El agente aprende de la corrección manual y aplica patrones similares cuando el mismo problema aparece en otro lugar.

Problemas de Git

El agente no puede crear una rama

Causa: Cambios sin confirmar en el árbol de trabajo, un conflicto de nombres de ramas o Git no está inicializado en el espacio de trabajo.

Solution:

1. Confirme o guarde los cambios pendientes antes de iniciar un escenario.
2. Compruebe que Git se inicializa mediante la ejecución git status en la raíz del área de trabajo.
3. Si ya existe una rama con el nombre previsto del agente, elimine la rama existente o pida al agente que use otro nombre de rama.

Deshacer todos los cambios realizados por el agente

Causa: La actualización no fue según lo planeado y quieres empezar de nuevo.

Solution:

1. Vuelva a la rama original con git checkout main (o la rama base).
2. La rama de trabajo del agente contiene todos los cambios aislados de su rama principal.
3. Para eliminar la sucursal del agente por completo, ejecute git branch -D <agent-branch-name>.
4. Para conservar algunos cambios, seleccione commits específicos con git cherry-pick <commit-hash>.

Problemas de rendimiento

Estos problemas se relacionan con la velocidad de actualización y la duración de la evaluación.

El agente es lento o tarda mucho tiempo

Causa: Las soluciones grandes con muchos proyectos, gráficos de dependencias complejos o numerosos cambios importantes tardan naturalmente más tiempo.

Solution:

En el caso de soluciones grandes (más de 50 proyectos), considere la posibilidad de actualizar en lotes. Agrupar proyectos relacionados y actualizarlos juntos.

La evaluación tarda mucho tiempo

Causa: La evaluación analiza las dependencias, los paquetes NuGet, los marcos de destino y los cambios incompatibles aplicables de cada proyecto. En el caso de soluciones grandes, la evaluación tarda más tiempo.

Solution:

1. Los tiempos de evaluación largos son normales para soluciones grandes. No se requiere ninguna acción.
2. Supervise el progreso en el panel Output (seleccione AppModernizationExtension en la lista desplegable de Visual Studio).
3. La evaluación solo se ejecuta una vez por escenario. Las fases posteriores usan los resultados almacenados en caché.

Problemas de personalización

Estos problemas se relacionan con las habilidades personalizadas y los archivos de instrucciones para escenarios.

No se reconoce la habilidad personalizada

Causa: El archivo de aptitud está en la ubicación incorrecta, tiene metadatos que faltan o no son válidos, o tiene un formato incorrecto.

Solution:

1. Verifique que el archivo de habilidad se encuentra en una de las ubicaciones admitidas:
   • .github/skills/ (nivel de repositorio, en todo el equipo)
   • .github/upgrades/skills/ (nivel de escenario)
   • %UserProfile%/.copilot/skills/ (nivel de usuario, personal)
2. Compruebe que los metadatos de la habilidad incluyen al menos los campos name y description.
3. Confirme que el discovery campo (si se establece) es uno de: lazy, preloado scenario.
4. Compruebe que la aptitud description coincide con el tipo de tarea a la que espera que se aplique. El agente usa la coincidencia de descripciones para seleccionar habilidades.

Los cambios en scenario-instructions.md no surten efecto

Causa: Es posible que el agente no vuelva a leer el archivo midsession o las modificaciones se encuentren en la sección incorrecta.

Solution:

1. Pida al agente que "vuelva a cargar instrucciones" o inicie una nueva sesión de chat para forzar una nueva lectura.
2. Compruebe que las modificaciones están en las secciones correctas del archivo:
   • Preferencias de usuario: Para las preferencias y restricciones generales.
   • Decisiones clave: Para registrar decisiones importantes tomadas durante la actualización.
   • Instrucciones personalizadas: Para anulaciones de comportamiento específicas.
3. Compruebe que el archivo se ha guardado y está en la ruta esperada: .github/upgrades/{scenarioId}/scenario-instructions.md.

Obtención de ayuda

Cuando algo no funciona según lo esperado:

1. Pregunte al agente: Pregunte "¿Qué ha ido mal con la última tarea?" El agente a menudo puede explicar lo que ha ocurrido y sugerir los pasos siguientes.
2. Revise el registro de ejecución: Abra execution-log.md en .github/upgrades/{scenarioId}/. El registro muestra un registro cronológico de lo que hizo el agente, incluidos los errores detectados.
3. Informe de un problema: Si ha encontrado un error o el agente falla constantemente en algo, informe un problema en el repositorio de GitHub @modernize-dotnet.

Contenido relacionado

• ¿Qué es la modernización de GitHub Copilot?
• procedimientos recomendados
• Conceptos básicos
• Preguntas más frecuentes sobre modernización de GitHub Copilot