Compartir a través de

Depuración segura del código original mediante la publicación de mapas de origen en el servidor de símbolos de Azure Artifacts

  • Artículo

Para ver y trabajar de forma segura con el código fuente de desarrollo original en DevTools en lugar del código de producción compilado, minificado y agrupado que devuelve el servidor web, use los mapas de origen que proporciona el servidor de símbolos de Azure Artifacts.

Publicar los mapas de origen directamente en el servidor web haría que el código fuente original fuera visible públicamente. Para evitar que el código fuente original sea visible públicamente, publique los mapas de origen en el servidor de símbolos de Azure Artifacts. Este enfoque permite usar los mapas de origen en DevTools, al depurar el sitio web de producción, sin publicar los mapas de origen en el servidor web.

El origen asigna el código de producción compilado a los archivos de origen de desarrollo originales. En DevTools, puede ver y trabajar con los archivos de origen de desarrollo conocidos, en lugar del código compilado. Para obtener más información sobre la asignación de origen y el uso de mapas de origen en DevTools, consulte Asignación del código procesado al código fuente original para la depuración.

Conceptos

Debe indexar los mapas de origen en el servidor de símbolos de Azure Artifacts para que los mapas de origen estén disponibles para DevTools al depurar el sitio web de producción.

Para ello, agregue la propiedad de cadena a los x_microsoft_symbol_client_key mapas de origen en tiempo de compilación. Esta propiedad contiene el valor hexadecimal en minúsculas del hash SHA-2 de 256 bits del archivo de origen original correspondiente.

A continuación, DevTools puede calcular este hash para cada uno de los archivos compilados y usar el hash para recuperar el mapa de origen correcto del servidor de símbolos de Azure Artifacts. Para recuperar de forma segura los mapas de origen, DevTools usa un token de acceso personal que proporciona para conectarse al servidor de símbolos de Azure Artifacts.

Paso 1: Generación de un token de acceso personal para Azure DevOps

El origen de publicación se asigna al servidor de símbolos de Azure Artifacts requiere un token de acceso personal (o PAT). El sistema de compilación usará esta PAT al compilar código y publicar mapas de origen.

Para generar una PAT en Azure DevOps:

  1. Inicie sesión en la organización de Azure DevOps en https://dev.azure.com/{yourorganization}.

  2. En Azure DevOps, vaya a Configuración de> usuarioTokens de acceso personal:

    Menú

    Aparece la página Tokens de acceso personal :

    Página

  3. Haga clic en Nuevo token. Se abre el cuadro de diálogo Crear un nuevo token de acceso personal :

    Cuadro de diálogo

  4. En el cuadro de texto Nombre , escriba un nombre para la PAT, como "publicar mapas de origen".

  5. En la sección Expiración , escriba una fecha de expiración para la PAT.

  6. En la sección Ámbitos , haga clic en Mostrar todos los ámbitos para expandir la sección.

  7. Desplácese hacia abajo hasta la sección Símbolos y, a continuación, seleccione la casilla Leer & escritura .

  8. Haga clic en el botón Crear. Aparece el cuadro de diálogo ¡Correcto! :

    Cuadro de diálogo

  9. Haga clic en el botón Copiar en el Portapapeles para copiar la PAT. Asegúrese de copiar el token y almacenarlo en una ubicación segura. Por su seguridad, no se volverá a mostrar.

Para más información sobre PAT, consulte Uso de tokens de acceso personal.

Paso 2: Calcular el hash SHA-256 del script y anexarlo a los mapas de origen

En el último paso del proceso de compilación de la aplicación, para cada mapa de origen que quiera publicar, debe calcular el hash SHA-256 del archivo JavaScript al que corresponde el mapa de origen y anexarlo al mapa de origen a través de la x_microsoft_symbol_client_key propiedad string.

Los sistemas de compilación varían de una aplicación a otra, por lo que no hay una única manera clara de aplicarlo. Pero este es un complemento webpack 5 de ejemplo, que se puede agregar a la configuración de Webpack si lo usa:

// file: webpack.plugin-symbols.js
// Copyright (C) Microsoft Corporation. All rights reserved.
// Licensed under the BSD 3-clause license.

const crypto = require('crypto');

module.exports = class PrepareSourceMapsForSymbolServerPlugin {
  /**
   * @param {import('webpack').Compiler} compiler
   * @returns {void}
   */
  apply(compiler) {
    compiler.hooks.emit.tap('PrepareSourceMapsForSymbolServerPlugin', (compilation) => {
      const files = Object.keys(compilation.assets);
      const sourceMaps = files.filter(v => v.endsWith('.map'));
      const sourceFilesAndMapsNames = sourceMaps.map(mapFileName => {
        const sourceFileName = mapFileName.substring(0, mapFileName.length - 4);
        return {
          sourceFileName,
          mapFileName,
        };
      });
      const sourceFiles = sourceFilesAndMapsNames.map(({ sourceFileName, mapFileName }) => {
        const sourceFile = compilation.assets[sourceFileName];
        const sourceFileBuffer = sourceFile.buffer();
        const hasher = crypto.createHash('sha256');
        hasher.write(sourceFileBuffer);
        const digest = hasher.digest();
        const sourceFileHash = digest.toString('hex');

        const sourceMapAsset = compilation.assets[mapFileName];
        const sourceMapSource = sourceMapAsset.source();
        const sourceMapContents = JSON.parse(sourceMapSource);
        sourceMapContents['x_microsoft_symbol_client_key'] = sourceFileHash;
        const rewrittenSourceMapContents = JSON.stringify(sourceMapContents);
        if (!sourceMapAsset.isBuffer()) {
          // Not a buffer -- write to the _value property
          sourceMapAsset._value = rewrittenSourceMapContents;
        } else {
          sourceMapAsset._valueAsBuffer = Buffer.from(rewrittenSourceMapContents, 'utf-8');
        }

        return {
          sourceFileName,
          mapFileName,
          sourceFileHash,
          sourceMapAsset,
        };
      });
    });
  }
};

A continuación, puede agregar el complemento a la plugins sección del webpack.config.js archivo de configuración:

const PrepareSourceMapsForSymbolServerPlugin = require('./webpack.plugin-symbols.js');

// ...

module.exports = (env, args) => {
  const mode = process.env.NODE_ENV || (env && env.NODE_ENV) || 'production';
  return {
    devtool: mode === 'production' ? 'hidden-source-map' : 'inline-source-map',
    resolve: {
      modules: [
        path.resolve('./node_modules'),
      ],
    },
    output: {
      publicPath: '/',
      filename: '[name].bundle.js',
      chunkFilename: '[name].chunk.js',
    },
    plugins: [
        // ... other plugins
        new PrepareSourceMapsForSymbolServerPlugin(),
    ]
  };
};

Paso 3: Publicar mapas de origen en el servidor de símbolos de Azure Artifacts

Para publicar asignaciones de origen en el servidor de símbolos de Azure Artifacts, use cualquiera de los enfoques siguientes:

Estos enfoques se describen a continuación.

Publicación de mapas de origen mediante Azure DevOps Pipelines

Azure DevOps incluye la tarea de compilación de canalización PublishSymbols@2 . Esta tarea se puede usar para publicar los mapas de origen en el servidor de símbolos de Azure Artifacts.

Al configurar esta tarea, establezca el indexableFileFormats parámetro en All o SourceMap.

Publicación de mapas de origen mediante symbol.exe

El equipo del servidor de símbolos publica una aplicación de .NET Core, symbol.exe, que se puede descargar automáticamente. Para descargar symbol.exemediante programación , use el GET método del punto de Client conexión en la API REST del servicio de símbolos, como se describe en Client - Get. A continuación, ejecute el siguiente comando para publicar los mapas de origen en el servidor de símbolos de Azure Artifacts:

symbol publish
        -d {root directory containing your source maps}
        -n {a unique name for this job}
        -s {service URL, such as https://artifacts.dev.azure.com/contoso}
        --patAuthEnvVar {name of environment variable containing a PAT}
        --indexableFileFormats SourceMap

El -n parámetro debe ser único. Los nombres de trabajo que se repiten se rechazarán, incluidos los nombres de trabajos con errores.

Vea también