Sicheres Debuggen von Originalcode durch Veröffentlichen von Quellzuordnungen auf dem Azure Artifacts-Symbolserver

  • Artikel

Um Ihren ursprünglichen Entwicklungsquellcode in DevTools anstelle des kompilierten, minimierten und gebündelten Produktionscodes, der vom Webserver zurückgegeben wird, sicher anzuzeigen und damit zu arbeiten, verwenden Sie Quellzuordnungen, die vom Azure Artifacts-Symbolserver bereitgestellt werden.

Wenn Sie Ihre Quellzuordnungen direkt auf Ihrem Webserver veröffentlichen, wird Ihr ursprünglicher Quellcode öffentlich sichtbar. Um zu vermeiden, dass Ihr ursprünglicher Quellcode öffentlich sichtbar ist, veröffentlichen Sie Ihre Quellzuordnungen auf dem Azure Artifacts-Symbolserver. Dieser Ansatz ermöglicht es, Ihre Quellzuordnungen in DevTools beim Debuggen Ihrer Produktionswebsite zu verwenden, ohne die Quellzuordnungen auf Ihrem Webserver zu veröffentlichen.

Quellzuordnungen ordnen Ihren kompilierten Produktionscode Ihren ursprünglichen Entwicklungsquelldateien zu. In DevTools können Sie dann Ihre vertrauten Entwicklungsquelldateien anstelle des kompilierten Codes anzeigen und damit arbeiten. Weitere Informationen zur Quellzuordnung und zur Verwendung von Quellzuordnungen in DevTools finden Sie unter Zuordnen des verarbeiteten Codes zum ursprünglichen Quellcode zum Debuggen.

Konzepte

Sie müssen Ihre Quellzuordnungen auf dem Azure Artifacts-Symbolserver indizieren, damit Ihre Quellzuordnungen für DevTools verfügbar sind, wenn Sie Ihre Produktionswebsite debuggen.

Fügen Sie dazu die Zeichenfolgeneigenschaft x_microsoft_symbol_client_key zur Kompilierungszeit zu Ihren Quellzuordnungen hinzu. Diese Eigenschaft enthält den Kleinbuchstaben-Hexadezimalwert des 256-Bit-SHA-2-Hashs der entsprechenden ursprünglichen Quelldatei.

DevTools ist dann in der Lage, diesen Hash für jede Ihrer kompilierten Dateien zu berechnen und den Hash zu verwenden, um die richtige Quellzuordnung vom Azure Artifacts-Symbolserver abzurufen. Um Ihre Quellzuordnungen sicher abzurufen, verwendet DevTools ein von Ihnen bereitgestelltes persönliches Zugriffstoken, um eine Verbindung mit dem Azure Artifacts-Symbolserver herzustellen.

Schritt 1: Generieren eines persönlichen Zugriffstokens für Azure DevOps

Für das Veröffentlichen von Quellzuordnungen auf dem Azure Artifacts-Symbolserver ist ein persönliches Zugriffstoken (Personal Access Token , PAT) erforderlich. Dieses PAT wird von Ihrem Buildsystem beim Kompilieren von Code und Veröffentlichen von Quellzuordnungen verwendet.

So generieren Sie ein PAT in Azure DevOps:

  1. Melden Sie sich bei Ihrer Azure DevOps-organization an, indem Sie zu https://dev.azure.com/{yourorganization}wechseln.

  2. Navigieren Sie in Azure DevOps zu Benutzereinstellungen>Persönliche Zugriffstoken:

    Das Menü

    Die Seite Persönliche Zugriffstoken wird angezeigt:

    Seite

  3. Klicken Sie auf Neues Token. Das Dialogfeld Neues persönliches Zugriffstoken erstellen wird geöffnet:

    Dialogfeld

  4. Geben Sie im Textfeld Name einen Namen für das PAT ein, z. B. "Quellzuordnungen veröffentlichen".

  5. Geben Sie im Abschnitt Ablauf ein Ablaufdatum für das PAT ein.

  6. Klicken Sie im Abschnitt Bereiche auf Alle Bereiche anzeigen , um den Abschnitt zu erweitern.

  7. Scrollen Sie nach unten zum Abschnitt Symbole , und aktivieren Sie dann das Kontrollkästchen Lesen & Schreiben .

  8. Klicken Sie auf die Schaltfläche Erstellen. Das Dialogfeld Erfolg! wird angezeigt:

    Das Dialogfeld

  9. Klicken Sie auf die Schaltfläche In Zwischenablage kopieren , um das PAT zu kopieren. Stellen Sie sicher, dass Sie das Token kopieren und an einem sicheren Ort speichern. Aus Sicherheitsgründen wird es nicht mehr angezeigt.

Weitere Informationen zu PAT finden Sie unter Verwenden von persönlichen Zugriffstoken.

Schritt 2: Berechnen des SHA-256-Hashs Ihres Skripts und Anfügen an Ihre Quellzuordnungen

Im letzten Schritt des Buildprozesses Ihrer Anwendung sollten Sie für jede Quellzuordnung, die Sie veröffentlichen möchten, den SHA-256-Hash der JavaScript-Datei berechnen, der die Quellzuordnung entspricht, und ihn über die Zeichenfolgeneigenschaft an die x_microsoft_symbol_client_key Quellzuordnung anfügen.

Buildsysteme variieren von Anwendung zu Anwendung, sodass es keine eindeutige Möglichkeit gibt, dies anzuwenden. Hier ist jedoch ein Beispiel für ein Webpack 5-Plug-In, das Ihrer Webpack-Konfiguration hinzugefügt werden kann, wenn Sie es verwenden:

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

Anschließend können Sie das Plug-In dem plugins Abschnitt in Ihrer webpack.config.js Konfigurationsdatei hinzufügen:

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

Schritt 3: Veröffentlichen von Quellzuordnungen auf dem Azure Artifacts-Symbolserver

Führen Sie eine der folgenden Optionen aus, um Quellzuordnungen zu veröffentlichen.

Veröffentlichen von Quellzuordnungen mithilfe von Azure DevOps-Pipelines

Azure DevOps enthält den PublishSymbols@2 Pipelinebuildtask. Diese Aufgabe kann verwendet werden, um Ihre Quellzuordnungen auf dem Azure Artifacts-Symbolserver zu veröffentlichen.

Stellen Sie sicher, dass Sie diese Aufgabe mit dem Parameter konfigurieren, der indexableFileFormats auf All oder SourceMapfestgelegt ist.

Veröffentlichen von Quellzuordnungen mit symbol.exe

Das SymbolServer-Team veröffentlicht eine .NET Core-Anwendung , symbol.exedie automatisch heruntergeladen werden kann . Nach dem Herunterladen symbol.exevon können Sie einen Befehl ausführen, um Ihre Quellzuordnungen auf dem Azure Artifacts-Symbolserver zu veröffentlichen:

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

Beachten Sie hier, dass der -n Parameter eindeutig sein muss. Wiederholungen von Auftragsnamen, auch bei namen fehlgeschlagenen Aufträgen, werden abgelehnt.

Siehe auch