Especificar símbolos (.pdb) y archivos de código fuente en el depurador de Visual Studio para C#, C++, Visual Basic, F#

Los archivos de base de datos de programa (.pdb), también denominados archivos de símbolos, asignan los identificadores y las instrucciones en el código fuente del proyecto a los identificadores y las instrucciones correspondientes en las aplicaciones compiladas. Estos archivos de asignación vinculan el depurador al código fuente, lo que permite la depuración.

Al compilar un proyecto desde el IDE de Visual Studio con la configuración de compilación de depuración estándar, el compilador crea los archivos de símbolos adecuados. En este artículo se describe cómo administrar archivos de símbolos en el IDE, por ejemplo:

• Configurar la ubicación de los archivos de símbolos
• Carga de símbolos durante la depuración
• Opciones del compilador para símbolos.

Para obtener una explicación detallada de los archivos de símbolos, consulte lo siguiente:

• Comprender los archivos de símbolos y la configuración de símbolos de Visual Studio

Funcionamiento de los archivos de símbolos

El archivo .pdb contiene información sobre el estado de la depuración y del proyecto que permite la vinculación incremental de una configuración de depuración de la aplicación. El depurador de Visual Studio usa archivos .pdb para determinar dos partes clave de la información durante la depuración:

• El nombre del archivo de origen y el número de línea que se mostrarán en el IDE de Visual Studio.
• En qué parte de la aplicación detenerse durante un punto de ruptura.

Los archivos de símbolos también muestran la ubicación de los archivos de origen y, opcionalmente, el servidor para recuperarlos.

El depurador solo carga archivos .pdb que coinciden exactamente con los archivos .pdb creados al compilar una aplicación (es decir, los archivos .pdb originales o copias). Esta duplicación exacta es necesaria porque el diseño de las aplicaciones puede cambiar incluso si el propio código no ha cambiado. Para obtener más información, vea ¿Por qué Visual Studio requiere que los archivos de símbolos del depurador coincidan exactamente con los archivos binarios con los que se compilaron?

Sugerencia

Para depurar código externo al código fuente del proyecto, por ejemplo código de Windows o de terceros que el proyecto llame, tiene que especificar la ubicación de los archivos .pdb del código externo (y, opcionalmente, de los archivos de código fuente), que deben coincidir exactamente con la versión de compilación de los archivos ejecutables.

Donde el depurador busca símbolos

Al depurar un proyecto en el IDE de Visual Studio, el depurador carga automáticamente los archivos de símbolos que puede encontrar de forma predeterminada.

Nota

Al depurar código administrado en un dispositivo remoto, todos los archivos de símbolos se deben ubicar en el equipo local o en una ubicación especificada en las opciones del depurador.

El depurador busca archivos de símbolos en las siguientes ubicaciones:

1. Carpeta del proyecto.

2. Ubicación especificada dentro del archivo DLL o ejecutable (.exe).

   De forma predeterminada, si ha compilado un archivo DLL o un archivo .exe en el equipo, el enlazador coloca la ruta de acceso completa y el nombre del archivo del archivo .pdb asociado en el archivo DLL o en el archivo .exe. El depurador comprueba si el archivo de símbolos existe en esa ubicación.

3. La misma carpeta que el archivo DLL o .exe.

4. Las ubicaciones especificadas en las opciones del depurador para los archivos de símbolos. Para agregar y habilitar ubicaciones de símbolos, consulte Configuración de ubicaciones de símbolos y opciones de carga.

   • Cualquier carpeta de caché de símbolos local.

   • Ubicaciones y servidores de red, Internet o de símbolos locales especificados, como los servidores de símbolos de Microsoft, si se seleccionan. Visual Studio puede descargar archivos de símbolos de depuración de servidores de símbolos que implementan el protocolo symsrv. Visual Studio Team Foundation Server y las Herramientas de depuración para Windows son dos herramientas que pueden usar servidores de símbolos.

     Entre los servidores de símbolos que puede usar se incluyen:

     Servidores de símbolos públicos de Microsoft: Para depurar un bloqueo que se produzca durante una llamada a un archivo DLL del sistema o a una biblioteca de terceros, generalmente necesitará archivos .pdb del sistema. Los archivos de .pdb del sistema contienen símbolos para archivos DLL de Windows, archivos .exe y controladores de dispositivo. Puede obtener símbolos para sistemas operativos Windows, MDAC, IIS, ISA y .NET desde los servidores públicos de símbolos de Microsoft.

     servidores de símbolos en una red interna o en la máquina local: su equipo o empresa puede crear servidores de símbolos para sus propios productos y como una memoria caché para símbolos de orígenes externos. Es posible que tenga un servidor de símbolos en su propia máquina.

     servidores de símbolos de terceros: los proveedores de terceros de aplicaciones y bibliotecas de Windows pueden proporcionar acceso al servidor de símbolos en Internet.

Advertencia

Si usa un servidor de símbolos distinto de los servidores públicos de símbolos de Microsoft, asegúrese de que el servidor de símbolos y su ruta de acceso sean de confianza. Dado que los archivos de símbolos pueden contener código ejecutable arbitrario, puede exponerse a amenazas de seguridad.

Configurar la ubicación de los archivos de símbolos y las opciones de carga

El depurador comprueba varias ubicaciones para los símbolos de forma predeterminada. Consulta Dónde busca símbolos el depurador.

En la página Herramientas>Opciones>Depuración>Símbolos, puede:

• Especifique y seleccione rutas de acceso de búsqueda para los archivos de símbolos.
• Especifique los servidores de símbolos para los componentes de Microsoft, Windows o de terceros.
• Especifique los módulos para los que desea o no que el depurador cargue automáticamente símbolos.
• Cambiar esta configuración mientras depura activamente. Consulte Carga de símbolos durante la depuración.

Especificar ubicaciones de símbolos y opciones de carga:

Nota

Estas opciones se actualizaron en La versión preliminar 17.12 de Visual Studio 2022.

1. En Visual Studio, abre Tools>Options>Debugging>Symbols (o Debug>Options>Symbols).

2. En Ubicaciones del archivo de símbolos (.pdb).

   • Para usar los servidores de símbolos de Microsoft o los servidores de símbolos de NuGet.org, active la casilla.

   • Para agregar una nueva ubicación del servidor de símbolos,

     1. Seleccione el símbolo + de la barra de herramientas.
     2. Escriba la dirección URL (http), el recurso compartido de red o la ruta de acceso local del servidor de símbolos o la ubicación del símbolo en el campo de texto. La finalización de instrucciones le será de ayuda para especificar el formato correcto.

   Herramientas - Opciones - Depuración - Página Símbolos

   Nota

   Solo se busca en la carpeta especificada. Debe agregar entradas para cualquier subcarpeta que desee buscar.

   • Para agregar una nueva ubicación del servidor de símbolos de Azure DevOps:

     1. Seleccione el icono de la barra de herramientas.

     2. En el cuadro de diálogo Conectar con el servidor de símbolos de Azure DevOps, elija uno de los servidores de símbolos disponibles y elija Conectar.

        Para más información, consulte Adición del servidor de símbolos de Azure Artifacts.

   • Para cambiar el orden de carga de las ubicaciones de símbolos, use Ctrl+Arriba y Ctrl+Abajo, o los iconos de flecha Arriba y Abajo.

   • Para editar una dirección URL o ruta de acceso, haga doble clic en la entrada o selecciónela y presione F2.

   • Para quitar una entrada, selecciónela y, a continuación, seleccione el icono de -.

3. (Opcional) Para mejorar el rendimiento de carga de símbolos, en Símbolos de caché de este directorio, escriba una ruta de acceso de carpeta local a la que los servidores de símbolos puedan copiar símbolos.

Nota

No coloque la caché de símbolos locales en una carpeta protegida, como C:\Windows o una subcarpeta. En su lugar, use una carpeta de lectura y escritura.

Nota

Si tiene establecida la variable de entorno _NT_SYMBOL_PATH, invalidará el valor establecido en Almacenar símbolos en caché a este directorio.

4. Especifique los módulos que quiere que el depurador cargue desde las ubicaciones del archivo de símbolos (.pdb) al iniciarse.

   • Seleccione Elegir automáticamente qué símbolos de módulo buscar (recomendado) para permitir que Visual Studio decida qué símbolos buscar y cargar. De forma predeterminada, Visual Studio carga automáticamente símbolos creados por la solución abierta y carga los símbolos adicionales necesarios para realizar operaciones de depuración comunes. Esto reduce el número de archivos que debe buscar y cargar Visual Studio, lo que mejora el rendimiento del depurador. Para forzar la carga de símbolos adicionales, haga clic en el vínculo Especificar filtros de módulo.

   • Seleccione Buscar todos los símbolos de módulo a menos que se excluyan para forzar a Visual Studio a cargar todos los símbolos en el proceso que estás depurando. Esto no se recomienda porque puede ralentizar la experiencia de depuración. Si selecciona esta opción, puede forzar a Visual Studio a omitir determinados símbolos haciendo clic en el vínculo Especificar filtros de módulo .

5. Seleccione Aceptar.

Especificar filtros de módulo

Tanto la opción Elegir automáticamente qué símbolos de módulo buscar como la opción Buscar todos los símbolos de módulo a menos que se excluyan le permiten tener un control más preciso sobre qué símbolos se buscan durante la depuración. Elija Especificar filtros de módulo para perfeccionar su experiencia.

De forma predeterminada, verá el siguiente cuadro de diálogo cuando Elegir automáticamente qué símbolos de módulo buscar está seleccionado:

Puede agregar un módulo al filtro mediante el icono "+". Los filtros de módulo admiten la coincidencia de caracteres comodín simples. Un '*' coincide con cualquier grupo de caracteres. Por ejemplo, "*myproduct*" coincidirá con archivos como "myproduct.utilities.dll" y "entrypoint.myproduct.exe", entre otros.

Hay varias opciones adicionales para personalizar aún más la experiencia:

• Cargar siempre símbolos situados junto a los módulos indica a Visual Studio que cargue archivos pdb almacenados en el sistema de archivos junto a sus archivos de .dll o .exe correspondientes. Esto puede ser útil, por ejemplo, al intentar depurar una aplicación web implementada.

• Cargar automáticamente símbolos adicionales cuando sea necesario indica a Visual Studio que busque símbolos para realizar acciones comunes de depuración, como la ejecución paso a paso, incluso si el módulo al que se va a ejecutar paso a paso no está en el proyecto o en el filtro de módulos. La forma en que la búsqueda se determina puede verse afectada por la configuración de Solo mi código.

Si ha seleccionado Buscar todos los símbolos de módulo a menos que se excluyan, el cuadro de diálogo de filtro del módulo tiene este aspecto:

En este cuadro de diálogo, puede elegir en qué módulos no desea que Visual Studio cargue los símbolos. En este escenario, Visual Studio intenta cargar símbolos para todos los módulos del proceso depurado (incluidos los módulos de terceros), a menos que agregue un filtro para excluirlos. La única otra forma en que se modificará este comportamiento es a través de la configuración de Solo mi código.

Otras opciones de símbolos para la depuración

Puede seleccionar opciones de símbolos adicionales en Tools>Options>Debugging>General (o Debug>Options>General):

• Cargar exportaciones de dll (solo nativas)

  Carga tablas de exportación de DLL para C/C++. Para consultar más detalles, vea las tablas de exportación de DLL . La lectura de información de exportación de DLL implica cierta sobrecarga, por lo que la carga de tablas de exportación está desactivada de forma predeterminada. También puede usar dumpbin /exports en una línea de comandos de compilación de C/C++.

• Habilitar la depuración de nivel de dirección y Mostrar desensamblado si el código fuente no está disponible

  Siempre muestra el desensamblaje cuando no se encuentran los archivos de código fuente o de símbolos.

  opciones de

• Habilitar la compatibilidad con el servidor de origen

  Usa el servidor de origen para ayudar a depurar una aplicación cuando no hay ningún código fuente en el equipo local o el archivo .pdb no coincide con el código fuente. El servidor de origen toma solicitudes de archivos y devuelve los archivos reales del control de código fuente. El servidor de origen se ejecuta mediante un archivo DLL denominado srcsrv.dll para leer el archivo de .pdb de la aplicación. El archivo .pdb contiene referencias al repositorio de código fuente, así como comandos usados para recuperar el código fuente.

  Puedes limitar los comandos que srcsrv.dll pueden ejecutar desde el archivo .pdb de la aplicación enumerando los comandos permitidos en un archivo denominado srcsrv.ini. Coloque el archivo srcsrv.ini en la misma carpeta que srcsrv.dll y devenv.exe.

  Importante

  Los comandos arbitrarios se pueden incrustar en el archivo .pdb de una aplicación, por lo que asegúrese de colocar solo los comandos que desea ejecutar en un archivo srcsrv.ini. Cualquier intento de ejecutar un comando que no esté en el archivo srcsvr.ini hará que aparezca un cuadro de diálogo de confirmación. Para obtener más información, consulta Security Warning: Debugger Must Execute Untrusted Command.

  No se realiza ninguna validación en los parámetros de comando, por lo que debe tener cuidado con los comandos de confianza. Por ejemplo, si ha enumerado cmd.exe en el srcsrv.ini, un usuario malicioso podría especificar parámetros en cmd.exe que podrían hacerlo peligroso.

  Seleccione este elemento y los elementos secundarios deseados. Permitir servidor de origen para ensamblados de confianza parcial (solo administrado) y Ejecutar siempre los comandos del servidor de origen que no sean de confianza sin preguntar pueden aumentar los riesgos de seguridad.

  

Opciones de símbolos del compilador

Cuando compila un proyecto mediante el IDE de Visual Studio con la configuración de compilación de depuración estándar, los compiladores administrados y de C++ crean archivos de símbolos adecuados para el código. También puede establecer las opciones del compilador en el código.

Para establecer las opciones del compilador para las configuraciones de compilación en Visual Studio, vea Establecimiento de configuraciones de depuración y versión.

Opciones de .NET

Compila con /debug para crear un archivo .pdb. Puede compilar aplicaciones con /debug:full o /debug:pdbonly. La compilación mediante /debug:full genera código depurable. La compilación mediante /debug:pdbonly genera archivos .pdb, pero no genera el atributo DebuggableAttribute que indica al compilador JIT que existe información de depuración disponible. Use /debug:pdbonly si quiere generar archivos .pdb para una compilación de versión que no quiere que sea depurable. Para obtener más información, vea /debug (opciones del compilador de C#) o /debug (Visual Basic).

Opciones de C/C++

• Archivos VC<x>.pdb y <proyecto>.pdb

  Se crea un archivo de .pdb para C/C++ al compilar con /ZI o /Zi. En Visual C++, la opción /Fd asigna un nombre al archivo .pdb que crea el compilador. Al crear un proyecto en Visual Studio mediante el IDE, la opción /Fd se establece para crear un archivo de .pdb denominado <proyecto>.pdb.

  Si compila la aplicación de C/C++ mediante un archivo Make y especifica /ZI o /Zi sin usar /Fd para especificar un nombre de archivo, el compilador crea dos archivos .pdb:

  • vc<x>.pdb, donde <x> representa la versión del compilador de Microsoft C++, por ejemplo, VC11.pdb

    El archivo VC<x>.pdb almacena toda la información de depuración de los archivos de objeto individuales y se encuentra en el mismo directorio que el makefile del proyecto. Cada vez que crea un archivo de objeto, el compilador de C/C++ combina información de depuración en VC<x>.pdb. Por lo tanto, aunque cada archivo de origen incluya archivos de encabezado comunes, como <windows.h>, las definiciones de tipo de esos encabezados se almacenan solo una vez, en lugar de en cada archivo de objeto. La información insertada incluye información de tipo, pero no incluye información de símbolos, como definiciones de función.

  • <proyecto>.pdb

    El archivo .pdb del proyecto<>almacena toda la información de depuración del archivo .exe del proyecto y reside en el subdirectorio \debug. El archivo <proyecto>.pdb contiene toda la información de depuración, incluidos los prototipos de función, y no solo la información de tipo que se encuentra en VC<x>.pdb.

  Tanto el archivo .pdb VC<x> como el archivo .pdb proyecto<> permiten actualizaciones de forma incremental. El enlazador también inserta la ruta de acceso a los archivos de .pdb en el archivo .exe o .dll que crea.

• Tablas de exportación de archivos DLL

  Use dumpbin /exports para ver los símbolos disponibles en la tabla de exportación de un archivo DLL. La información simbólica de las tablas de exportación de DLL puede ser útil para trabajar con mensajes de Windows, procedimientos de Windows (WindowProcs), objetos COM, serialización o cualquier DLL para el que no tenga símbolos. Los símbolos están disponibles para cualquier DLL del sistema de 32 bits. Las llamadas se muestran en una lista según el orden de llamada, y la función actual (la que está anidada a mayor profundidad) aparece en la parte superior.

  Al leer la salida dumpbin /exports, puedes ver los nombres de función exactos, incluidos los caracteres no alfanuméricos. Ver los nombres exactos de las funciones es útil para establecer un punto de interrupción en una función, porque los nombres de función se pueden truncar en otras partes del depurador. Para obtener más información, vea dumpbin /exports.

Aplicaciones web

Establezca el archivo web.config de la aplicación de ASP.NET en modo de depuración. El modo de depuración hace ASP.NET generar símbolos para archivos generados dinámicamente y permite que el depurador se adjunte a la aplicación ASP.NET. Visual Studio establece esto automáticamente al empezar a depurar, si creó el proyecto a partir de la plantilla de proyectos web.

Carga de símbolos durante la depuración

Puede usar las ventanas Módulos, Pila de llamadas, Variables locales, Automático o Inspección cargar símbolos o cambiar opciones de símbolo durante la depuración. Para más información, vea Familiarizarse con el modo en que el depurador se asocia a la aplicación.

Trabajar con símbolos en la ventana Módulos

Durante la depuración, la ventana de módulos muestra los módulos de código que el depurador está tratando como código de usuario, o Mi código, y el estado de carga de sus símbolos. En la ventana Módulos, también puede supervisar el estado de carga de símbolos, cargar símbolos y cambiar las opciones de símbolos.

Para supervisar o cambiar ubicaciones de símbolos u opciones de símbolo durante la depuración:

1. Para abrir la ventana Módulos mientras realiza la depuración, seleccione Depurar>Ventanas>Módulos (o bien, presione CTRL + Alt + U).
2. En la ventana Módulos, haga clic con el botón derecho en los encabezados Estado del símbolo o Archivo de símbolo o en cualquier módulo.
3. En el menú contextual, seleccione una de las siguientes opciones:

Opción	Descripción
Cargar símbolos	Aparece para los módulos con símbolos omitidos, no encontrados o no cargados. Intenta cargar símbolos de las ubicaciones especificadas en la página Opciones>Depuración>Símbolos. Si no se encuentra o no se carga el archivo de símbolos, inicia explorador de archivos para que pueda especificar una nueva ubicación para buscar.
Información de carga de símbolos	Muestra la ubicación de un archivo de símbolos cargado o las ubicaciones que se buscaron si el depurador no encuentra el archivo.
Configuración de símbolos	Abre la página Opciones>Depuración>Símbolos, donde puede editar y agregar ubicaciones de símbolos.
Cargar siempre automáticamente	Agrega el archivo de símbolos seleccionado a la lista de archivos que el depurador carga automáticamente.

Uso de las páginas No se cargaron símbolos/No se cargaron orígenes

Hay varias maneras en las que el depurador puede acceder al código que no tiene archivos de símbolos o fuente disponibles.

• Depurar código paso a paso por instrucciones.
• Interrumpir el código desde un punto de interrupción o una excepción.
• Cambie a otro hilo.
• Cambiar el marco de pila haciendo doble clic en un marco de la ventana Pila de llamadas.

Cuando esto sucede, el depurador muestra las páginas Sin símbolos cargados o Sin código fuente cargado para ayudarle a encontrar y cargar los símbolos o el código fuente necesarios.

Para usar la página de documento No se cargaron símbolos para ayudar a encontrar y cargar los símbolos que faltan:

• Para cambiar la ruta de búsqueda, seleccione una que no haya sido elegida, o elija Nueva ruta o Nueva ruta de VSTS y escriba o seleccione una nueva ruta. Seleccione Cargar para buscar de nuevo las rutas de acceso y cargar el archivo de símbolos si se encuentra.
• Para invalidar cualquier opción de símbolo y reintentar las rutas de acceso de búsqueda, seleccione Browse and find (Examinar y buscar) <nombredelejecutable>. Se carga el archivo de símbolos, si se encuentra, o se abre el Explorador de archivos para que pueda seleccionar manualmente el archivo de símbolos.
• Para abrir la página de configuración de símbolos para configurar el comportamiento, seleccione Cambiar la Configuración de Símbolos (o seleccione Opciones>Depuración>Símbolos).
• (Avanzado) Para mostrar el desensamblado en una nueva ventana una vez, seleccione ver el desensambladoo seleccione cuadro de diálogo Opciones para establecer la opción para mostrar siempre el desensamblado cuando no se encuentran los archivos de código fuente o de símbolos. Para obtener más información, consulte Ver código de desensamblaje.
• Para mostrar las ubicaciones en las que se buscó y el resultado, expanda Información de carga de símbolos.
• En el código de C#, también puede elegir descompilar el código fuente de las páginas No se cargaron símbolos o No se cargaron orígenes.

Si el depurador encuentra el archivo .pdb después de ejecutar una de las opciones y puede recuperar los archivos fuente mediante la información del archivo .pdb , muestra el archivo fuente. En caso contrario, se muestra una página No se cargaron orígenes que describe el problema, con vínculos a acciones que podrían resolver el problema.

Para agregar rutas de búsqueda de archivos de origen a una solución:

Puede especificar las ubicaciones en las que el depurador busca archivos de origen y excluir archivos específicos de la búsqueda.

1. Seleccione la solución en el Explorador de soluciones y luego elija el icono Propiedades, presione Alt+Entrar o haga clic con el botón derecho y seleccione Propiedades.

2. Seleccione Depurar archivos de código fuente.

   

3. En Directorios que contienen código fuente, escriba o seleccione las ubicaciones del código fuente que va a buscar. Use el icono nueva línea para agregar más ubicaciones, los iconos de flecha hacia arriba y hacia abajo para reordenarlos, o el icono X para eliminarlos.

   Nota

   El depurador solo busca en el directorio especificado. Debe agregar entradas para los subdirectorios que quiera buscar.

4. En No busque los siguientes archivos de código fuente, escriba los nombres de los archivos de código fuente que se van a excluir de la búsqueda.

5. Seleccione Aceptar o Aplicar.

Contenido relacionado

• Comprender los archivos de símbolos y la configuración de símbolos de Visual Studio