Compartilhar via

Depurar código original de forma segura ao publicar mapas de origem no servidor de símbolos dos Artefactos do Azure

  • Artigo

Para ver e trabalhar de forma segura com o código fonte de desenvolvimento original em DevTools em vez do código de produção compilado, minificado e agrupado devolvido pelo servidor Web, utilize mapas de origem servidos pelo servidor de símbolos dos Artefactos do Azure.

Publicar os mapas de origem diretamente no servidor Web tornaria o seu código fonte original publicamente visível. Para evitar tornar o código fonte original publicamente visível, publique os mapas de origem no servidor de símbolos dos Artefactos do Azure. Esta abordagem permite utilizar os mapas de origem no DevTools, ao depurar o site de produção, sem publicar os mapas de origem no servidor Web.

Os mapas de origem mapeiam o código de produção compilado para os seus ficheiros de origem de desenvolvimento originais. Em DevTools, pode ver e trabalhar com os seus ficheiros de origem de desenvolvimento familiares, em vez do código compilado. Para saber mais sobre o mapeamento de origem e a utilização de mapas de origem no DevTools, consulte Mapear o código processado para o código fonte original para depuração.

Conceitos

Tem de indexar os mapas de origem no servidor de símbolos dos Artefactos do Azure, para que os mapas de origem estejam disponíveis para DevTools quando depurar o site de produção.

Para tal, adicione a propriedade cadeia aos mapas de origem x_microsoft_symbol_client_key no momento da compilação. Esta propriedade contém o valor hexadecimal em minúsculas do hash SHA-2 de 256 bits do ficheiro de origem original correspondente.

Em seguida, o DevTools é capaz de calcular este hash para cada um dos seus ficheiros compilados e utilizar o hash para obter o mapa de origem correto do servidor de símbolos dos Artefactos do Azure. Para obter os mapas de origem de forma segura, o DevTools utiliza um Token de Acesso Pessoal fornecido por si, para ligar ao servidor de símbolos dos Artefactos do Azure.

Passo 1: Gerar um Token de Acesso Pessoal para o Azure DevOps

A publicação de mapas de origem no servidor de símbolos dos Artefactos do Azure requer um Token de Acesso Pessoal (ou PAT). Este PAT será utilizado pelo seu sistema de compilação ao compilar código e publicar mapas de origem.

Para gerar um PAT no Azure DevOps:

  1. Inicie sessão na sua organização do Azure DevOps ao aceder a https://dev.azure.com/{yourorganization}.

  2. No Azure DevOps, aceda a Definições do utilizador Tokens> deacesso pessoal:

    O menu

    É apresentada a página Tokens de Acesso Pessoal :

    A página

  3. Clique em Novo Token. É aberta a caixa de diálogo Criar um novo token de acesso pessoal :

    A caixa de diálogo

  4. Na caixa de texto Nome , introduza um nome para o PAT, como "publicar mapas de origem".

  5. Na secção Expiração , introduza uma data de expiração para o PAT.

  6. Na secção Âmbitos , clique em Mostrar todos os âmbitos para expandir a secção.

  7. Desloque-se para baixo até à secção Símbolos e, em seguida, selecione a caixa de verificação Ler & escrever .

  8. Clique no botão Criar . A caixa de diálogo Êxito! é apresentada:

    A caixa de diálogo 'Êxito!' com o PAT a copiar

  9. Clique no botão Copiar para a área de transferência para copiar o PAT. Certifique-se de que copia o token e o armazena numa localização segura. Para sua segurança, não será apresentado novamente.

Para saber mais sobre o PAT, consulte Utilizar tokens de acesso pessoal.

Passo 2: calcular o hash SHA-256 do script e anexá-lo aos mapas de origem

No passo final do processo de compilação da sua aplicação, para cada mapa de origem que pretende publicar, deve calcular o hash SHA-256 do ficheiro JavaScript ao qual o Mapa de Origem corresponde e anexá-lo ao mapa de origem através da propriedade da x_microsoft_symbol_client_key cadeia.

Os sistemas de compilação variam de aplicação para aplicação, pelo que não existe uma forma clara de o aplicar. No entanto, eis um plug-in webpack 5 de exemplo, que pode ser adicionado à configuração do Webpack se estiver a utilizá-lo:

// 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,
        };
      });
    });
  }
};

Em seguida, pode adicionar o plug-in à plugins secção no ficheiro webpack.config.js de configuração:

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(),
    ]
  };
};

Passo 3: publicar mapas de origem no servidor de símbolos dos Artefactos do Azure

Para publicar mapas de origem no servidor de símbolos dos Artefactos do Azure, utilize uma das seguintes abordagens:

Estas abordagens são descritas abaixo.

Publicar mapas de origem com os Pipelines do Azure DevOps

O Azure DevOps inclui a tarefa de compilação do PublishSymbols@2 pipeline. Esta tarefa pode ser utilizada para publicar os mapas de origem no servidor de símbolos dos Artefactos do Azure.

Ao configurar esta tarefa, defina o indexableFileFormats parâmetro como All ou SourceMap.

Publicar mapas de origem com symbol.exe

A equipa do Servidor de Símbolos publica uma aplicação .NET Core, symbol.exe, que pode ser transferida automaticamente. Para transferir symbol.exeprogramaticamente , utilize o GET método do Client ponto final na API REST do Serviço de Símbolos, conforme descrito em Cliente – Obter. Em seguida, execute o seguinte comando para publicar os mapas de origem no servidor de símbolos dos Artefactos do Azure:

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

O -n parâmetro tem de ser exclusivo. Os nomes dos trabalhos repetidos serão rejeitados, incluindo os nomes dos trabalhos que falharam.

Confira também