Personalizzare JavaScript per Azure Pipelines

È possibile usare Azure Pipelines per creare app JavaScript senza dover configurare un'infrastruttura personalizzata. Gli strumenti comunemente usati per compilare, testare ed eseguire app JavaScript, ad esempio npm, Node, Yarn e Gulp, vengono preinstallati negli agenti ospitati da Microsoft in Azure Pipelines.

Per la versione di Node.js e npm preinstallata, vedere Agenti ospitati da Microsoft. Per installare una versione specifica di questi strumenti negli agenti ospitati da Microsoft, aggiungere l'attività Programma di installazione strumenti Node all'inizio del processo. È anche possibile usare un agente self-hosted .

Per creare la prima pipeline con JavaScript, vedere la guida introduttiva a JavaScript.

Usare una versione specifica di Node.js

Se è necessaria una versione di Node.js e npm che non è già installata nell'agente ospitato da Microsoft, usare l'attività di installazione dello strumento Node. Aggiungere il frammento di codice seguente al azure-pipelines.yml file.

Nota

Gli agenti ospitati vengono aggiornati regolarmente e la configurazione di questa attività comporta la spesa di tempo significativo per l'aggiornamento a una versione secondaria più recente ogni volta che viene eseguita la pipeline. Usare questa attività solo quando è necessaria una versione specifica di Node nella pipeline.

- task: UseNode@1
  inputs:
    version: '16.x' # replace this value with the version that you need for your project

Per aggiornare solo lo strumento npm, eseguire il npm i -g npm@version-number comando nel processo di compilazione.

Usare più versioni dei nodi

È possibile compilare e testare l'app in più versioni di Node con l'attività di installazione dello strumento Node.

pool:
  vmImage: 'ubuntu-latest'
strategy:
  matrix:
    node_16_x:
      node_version: 16.x
    node_13_x:
      node_version: 18.x

steps:
- task: UseNode@1
  inputs:
    version: $(node_version)

- script: npm install

Installare gli strumenti nell'agente di compilazione

Se si dispone di strumenti che sono dipendenze di sviluppo nel progetto package.json o package-lock.json nel file, installare gli strumenti e le dipendenze tramite npm. La versione esatta degli strumenti viene definita nel progetto, isolata da altre versioni esistenti nell'agente di compilazione.

Usare uno script o l'attività npm.

Usare uno script per l'installazione con package.json

- script: npm install --only=dev

Usare l'attività npm per l'installazione con package.json

- task: Npm@1
  inputs:
     command: 'install'

Eseguire gli strumenti installati in questo modo usando lo strumento di esecuzione del pacchetto npm npx , che rileva gli strumenti installati in questo modo nella risoluzione del percorso. L'esempio seguente chiama il mocha test runner, ma cerca la versione installata come dipendenza di sviluppo prima di usare una versione installata a livello globale (tramite npm install -g) .

- script: npx mocha

Per installare gli strumenti necessari per il progetto, ma che non sono impostati come dipendenze di sviluppo in package.json, chiamare npm install -g da una fase di script nella pipeline.

Nell'esempio seguente viene installata la versione più recente dell'interfaccia della riga di comando di Angular usando npm. Il resto della pipeline può quindi usare lo ng strumento da altre script fasi.

Nota

Negli agenti Linux ospitati da Microsoft anteporre al comando sudo, ad esempio sudo npm install -g.

- script: npm install -g @angular/cli

Suggerimento

Queste attività vengono eseguite ogni volta che viene eseguita la pipeline, quindi tenere presente l'impatto che l'installazione degli strumenti ha sui tempi di compilazione. Valutare la possibilità di configurare agenti self-hosted con la versione degli strumenti necessari se il sovraccarico diventa un grave impatto sulle prestazioni di compilazione.

Gestire le dipendenze

Nella compilazione usare Yarn o Azure Artifacts per scaricare i pacchetti dal registro npm pubblico. Questo registro è un tipo di registro npm privato specificato nel .npmrc file.

Usare npm

È possibile usare npm nei modi seguenti per scaricare i pacchetti per la compilazione:

• npm install Eseguire direttamente nella pipeline, perché è il modo più semplice per scaricare i pacchetti da un registro senza autenticazione. Se la compilazione non richiede dipendenze di sviluppo dall'agente da eseguire, è possibile velocizzare i tempi di compilazione con l'opzione --only=prod .npm install
• Usare un'attività npm. Questa attività è utile quando si usa un registro autenticato.
• Usare un'attività di autenticazione npm. Questa attività è utile quando si esegue npm install dall'interno degli strumenti di esecuzione attività: Gulp, Grunt o Maven.

Se si vuole specificare un registro npm, inserire gli URL in un .npmrc file nel repository. Se il feed viene autenticato, creare una connessione al servizio npm nella scheda Servizi in Impostazioni progetto per gestire le credenziali.

Per installare pacchetti npm con uno script nella pipeline, aggiungere il frammento di codice seguente a azure-pipelines.yml.

- script: npm install

Per usare un registro privato specificato nel .npmrc file, aggiungere il frammento di codice seguente a azure-pipelines.yml.

- task: Npm@1
  inputs:
    customEndpoint: <Name of npm service connection>

Per passare le credenziali del Registro di sistema ai comandi npm tramite strumenti di esecuzione attività, ad esempio Gulp, aggiungere l'attività seguente a azure-pipelines.yml prima di chiamare lo strumento di esecuzione attività.

- task: npmAuthenticate@0
  inputs:
    customEndpoint: <Name of npm service connection>

Se le compilazioni hanno occasionalmente esito negativo a causa di problemi di connessione quando si ripristinano pacchetti dal registro npm, è possibile usare Azure Artifacts con origini upstream e memorizzare nella cache i pacchetti. Le credenziali della pipeline vengono usate automaticamente quando ci si connette ad Azure Artifacts. Queste credenziali vengono in genere derivate dall'account del servizio di compilazione raccolta progetti.

Se si usano agenti ospitati da Microsoft, si ottiene un nuovo computer ogni volta che si esegue una compilazione, ovvero il ripristino delle dipendenze ogni volta, che può richiedere una quantità significativa di tempo. Per attenuare il problema, è possibile usare Azure Artifacts o un agente self-hosted, quindi si ottiene il vantaggio di usare la cache dei pacchetti.

Usare Yarn

Usare una fase di script per richiamare Yarn per ripristinare le dipendenze. Yarn viene preinstallato in alcuni agenti ospitati da Microsoft. È possibile installarlo e configurarlo in agenti self-hosted come qualsiasi altro strumento.

- script: yarn install

Eseguire compilatori JavaScript

Usare compilatori come Babel e il compilatore TypeScripttsc per convertire il codice sorgente in versioni utilizzabili dal runtime Node.js o nei Web browser.

Se nel file di progetto package.json è configurato un oggetto script che esegue il compilatore, richiamarlo nella pipeline usando un'attività script.

- script: npm run compile

È possibile chiamare i compilatori direttamente dalla pipeline usando l'attività script. Questi comandi vengono eseguiti dalla radice del repository del codice sorgente clonato.

- script: tsc --target ES6 --strict true --project tsconfigs/production.json

Esecuzione di unit test

Configurare le pipeline per eseguire i test JavaScript in modo che producano risultati formattati nel formato XML JUnit. È quindi possibile pubblicare i risultati usando l'attività predefinita pubblica risultati dei test.

Se il framework di test non supporta l'output JUnit, aggiungere il supporto tramite un modulo di creazione di report partner, ad esempio mocha-junit-reporter. È possibile aggiornare lo script di test per usare il reporter JUnit o se il reporter supporta le opzioni della riga di comando, passare tali opzioni nella definizione dell'attività.

Nella tabella seguente sono elencati i testrunner più comunemente usati e i reporter che possono essere usati per produrre risultati XML:

Test Runner	Reporter per produrre report XML
Mocha	mocha-junit-reporter cioeca-multi-reporter
Gelsomino	reporter di gelosomini
jest	jest-junit jest-junit-reporter
Karma	karma-junit-reporter
Ava	tap-xunit

Nell'esempio seguente viene usato mocha-junit-reporter e viene richiamato mocha test direttamente usando uno script. Questo script genera l'output XML JUnit nel percorso predefinito di ./test-results.xml.

- script: mocha test --reporter mocha-junit-reporter

Se è stato definito uno test script nel file package.json del progetto, è possibile richiamarlo usando npm test.

- script: npm test

Pubblica risultati dei test

Per pubblicare i risultati, usare l'attività Pubblica risultati test.

- task: PublishTestResults@2
  condition: succeededOrFailed()
  inputs:
    testRunner: JUnit
    testResultsFiles: '**/test-results.xml'

Pubblicare i risultati del code coverage

Se gli script di test eseguono uno strumento di code coverage, ad esempio Istanbul, aggiungere l'attività Pubblica risultati code coverage. In questo caso, è possibile trovare le metriche di copertura nel riepilogo della compilazione e scaricare i report HTML per ulteriori analisi. L'attività prevede l'output di creazione di report Cobertura o JaCoCo, quindi assicurarsi che lo strumento di code coverage venga eseguito con le opzioni necessarie per generare l'output corretto. Ad esempio: --report cobertura.

L'esempio seguente usa nyc, l'interfaccia della riga di comando di Istanbul, insieme a mocha-junit-reporter e richiama il npm test comando .

- script: |
    nyc --reporter=cobertura --reporter=html \
    npm test -- --reporter mocha-junit-reporter --reporter-options mochaFile=./test-results.xml
  displayName: 'Build code coverage report'

- task: PublishCodeCoverageResults@2
  inputs: 
    summaryFileLocation: '$(System.DefaultWorkingDirectory)/**/*coverage.xml'

Testare il browser end-to-end

Eseguire test nei browser headless come parte della pipeline con strumenti come Protractor o Karma. Pubblicare quindi i risultati per la compilazione in Azure DevOps seguendo questa procedura:

1. Installare un driver di test del browser headless, ad esempio Chrome headless o Firefox, o uno strumento di simulazione del browser, ad esempio PhantomJS, nell'agente di compilazione.
2. Configurare il framework di test per usare l'opzione headless browser/driver preferita in base alla documentazione dello strumento.
3. Configurare il framework di test (in genere con un plug-in o una configurazione del reporter) per restituire i risultati dei test in formato JUnit.
4. Configurare un'attività script per eseguire tutti i comandi dell'interfaccia della riga di comando necessari per avviare le istanze del browser headless.
5. Eseguire i test end-to-end nelle fasi della pipeline insieme agli unit test.
6. Pubblicare i risultati usando la stessa attività Pubblica risultati test insieme agli unit test.

Creare un pacchetto di app Web

Creare un pacchetto di applicazioni per aggregare tutti i moduli dell'applicazione con output intermedi e dipendenze in asset statici pronti per la distribuzione. Aggiungere una fase della pipeline dopo la compilazione e i test per eseguire uno strumento come webpack o compilazione usando l'interfaccia della riga di comando di Angular.

Il primo esempio chiama webpack. Per eseguire questa operazione, assicurarsi che webpack sia configurata come dipendenza di sviluppo nel file di progetto package.json. Questa operazione viene eseguita webpack con la configurazione predefinita, a meno che non si disponga di un webpack.config.js file nella cartella radice del progetto.

- script: webpack

Nell'esempio seguente viene usata l'attività npm per chiamare npm run build l'oggetto build script definito nel file package.json del progetto. L'uso di oggetti script nel progetto sposta la logica per la compilazione nel codice sorgente e all'esterno della pipeline.

- script: npm run build

Implementare framework JavaScript

Angular

Per le app Angular, è possibile includere comandi specifici di Angular, ad esempio test di ng, compilazione e ng e2e. Per usare i comandi dell'interfaccia della riga di comando di Angular nella pipeline, installare il pacchetto npm angular/cli nell'agente di compilazione.

Nota

Negli agenti Linux ospitati da Microsoft anteporre al comando sudo, ad esempio sudo npm install -g.

- script: |
    npm install -g @angular/cli
    npm install
    ng build --prod

Per i test nella pipeline che richiedono l'esecuzione di un browser, ad esempio il comando ng test nell'app starter, che esegue Karma, usare un browser headless anziché un browser standard. Nell'app di avvio Angular:

1. Modificare la browsers voce nel file di progetto karma.conf.js da browsers: ['Chrome'] a browsers: ['ChromeHeadless'].

2. Modificare la singleRun voce nel file di progetto karma.conf.js da un valore di false a true. Questa modifica consente di assicurarsi che il processo Karma si arresti dopo l'esecuzione.

React e Vue

Tutte le dipendenze per le app React e Vue vengono acquisite nel file package.json . Il file azure-pipelines.yml contiene lo script Node.js standard:

- script: |
    npm install
  displayName: 'npm install'

- script: |
    npm run build
  displayName: 'npm build'

I file di compilazione si trovano in una nuova cartella, dist (per Vue) o build (per React). Questo frammento compila un artefatto, www pronto per il rilascio. Usa le attività Programma di installazione del nodo, Copia filee Pubblica artefatti di compilazione .

trigger:
- main

pool:
  vmImage: 'ubuntu-latest'

steps:
- task: UseNode@1
  inputs:
    version: '16.x'
  displayName: 'Install Node.js'

- script: |
    npm install
  displayName: 'npm install'

- script: |
    npm run build
  displayName: 'npm build'

- task: CopyFiles@2
  inputs:
    Contents: 'build/**' # Pull the build directory (React)
    TargetFolder: '$(Build.ArtifactStagingDirectory)'

- task: PublishBuildArtifacts@1
  inputs: 
    PathtoPublish: $(Build.ArtifactStagingDirectory) # dist or build files
    ArtifactName: 'www' # output artifact named www

Per rilasciare, puntare l'attività di rilascio all'elemento dist o build e usare l'attività Distribuzione app Web di Azure.

Webpack

È possibile usare un file di configurazione webpack per specificare un compilatore, ad esempio Babel o TypeScript, per transpile JSX o TypeScript in JavaScript normale e per aggregare l'app.

- script: |
    npm install webpack webpack-cli --save-dev
    npx webpack --config webpack.config.js

Strumenti di esecuzione attività di compilazione

È comune usare Gulp o Grunt come strumento di esecuzione attività per compilare e testare un'app JavaScript.

Gulp

Gulp viene preinstallato sugli agenti ospitati da Microsoft. Eseguire il gulp comando nel file YAML:

- script: gulp                       # include any additional options that are needed

Se i passaggi nel file gulpfile.js richiedono l'autenticazione con un registro npm:

- task: npmAuthenticate@0
  inputs:
    customEndpoint: <Name of npm service connection>

- script: gulp                       # include any additional options that are needed

Aggiungere l'attività Pubblica risultati test per pubblicare i risultati del test JUnit o xUnit nel server.

- task: PublishTestResults@2
  inputs:
    testResultsFiles: '**/TEST-RESULTS.xml'
    testRunTitle: 'Test results for JavaScript using gulp'

Aggiungere l'attività Pubblica risultati code coverage per pubblicare i risultati del code coverage nel server. È possibile trovare le metriche di copertura nel riepilogo della compilazione ed è possibile scaricare i report HTML per ulteriori analisi.

- task: PublishCodeCoverageResults@1
  inputs: 
    codeCoverageTool: Cobertura
    summaryFileLocation: '$(System.DefaultWorkingDirectory)/**/*coverage.xml'
    reportDirectory: '$(System.DefaultWorkingDirectory)/**/coverage'

Grunt

Grunt viene preinstallato sugli agenti ospitati da Microsoft. Per eseguire il comando grunt nel file YAML:

- script: grunt                      # include any additional options that are needed

Se i passaggi nel Gruntfile.js file richiedono l'autenticazione con un registro npm:

- task: npmAuthenticate@0
  inputs:
    customEndpoint: <Name of npm service connection>

- script: grunt                      # include any additional options that are needed

Creare un pacchetto e recapitare il codice

Dopo aver compilato e testato l'app, è possibile caricare l'output di compilazione in Azure Pipelines, creare e pubblicare un pacchetto npm o Maven oppure creare un pacchetto dell'output di compilazione in un file ZIP per la distribuzione in un'applicazione Web.

Pubblicare file in Azure Pipelines

Per caricare l'intera directory di lavoro dei file, usare l'attività Pubblica elementi di compilazione e aggiungere quanto segue al azure-pipelines.yml file.

- task: PublishBuildArtifacts@1
  inputs:
    PathtoPublish: '$(System.DefaultWorkingDirectory)'

Per caricare un subset di file, copiare prima i file necessari dalla directory di lavoro in una directory di staging con l'attività Copia file e quindi usare l'attività Pubblica artefatti di compilazione.

- task: CopyFiles@2
  inputs:
    SourceFolder: '$(System.DefaultWorkingDirectory)'
    Contents: |
      **\*.js
      package.json
    TargetFolder: '$(Build.ArtifactStagingDirectory)'

- task: PublishBuildArtifacts@1

Pubblicare un modulo in un registro npm

Se l'output del progetto è un npm modulo da usare da altri progetti e non da un'applicazione Web, usare l'attività npm per pubblicare il modulo in un registro locale o nel registro npm pubblico. Specificare una combinazione di nome/versione univoca ogni volta che si pubblica.

Esempi

Il primo esempio presuppone che le informazioni sulla versione (ad esempio tramite una versione npm) vengano gestite tramite le modifiche apportate al package.json file nel controllo della versione. Nell'esempio seguente viene usata l'attività script per pubblicare nel Registro di sistema pubblico.

- script: npm publish

Nell'esempio seguente viene pubblicato in un registro personalizzato definito nel file del .npmrc repository. Configurare una connessione al servizio npm per inserire le credenziali di autenticazione nella connessione durante l'esecuzione della compilazione.

- task: Npm@1
  inputs:
     command: publish
     publishRegistry: useExternalRegistry
     publishEndpoint: https://my.npmregistry.com

L'esempio finale pubblica il modulo in un feed di gestione pacchetti di Azure DevOps Services.

- task: Npm@1
  inputs:
     command: publish
     publishRegistry: useFeed
     publishFeed: https://my.npmregistry.com

Per altre informazioni sul controllo delle versioni e sulla pubblicazione di pacchetti npm, vedere Pubblicare pacchetti npm e Come è possibile eseguire la versione dei pacchetti npm come parte del processo di compilazione?

Distribuire un'app Web

Per creare un archivio di file ZIP pronto per la pubblicazione in un'app Web, usare l'attività Archivia file :

- task: ArchiveFiles@2
  inputs:
    rootFolderOrFile: '$(System.DefaultWorkingDirectory)'
    includeRootFolder: false

Per pubblicare questo archivio in un'app Web, vedere Distribuzione di app Web di Azure.

Creare ed eseguire il push di un'immagine nel registro contenitori

Dopo aver compilato correttamente il codice sorgente e aver completato correttamente gli unit test, è anche possibile compilare un'immagine ed eseguirne il push in un registro contenitori.

Risoluzione dei problemi

Se è possibile compilare il progetto nel computer di sviluppo ma si verificano problemi durante la compilazione in Azure Pipelines, esplorare le possibili cause e le azioni correttive seguenti:

• Verificare che le versioni di Node.js e dello strumento di esecuzione delle attività nel computer di sviluppo corrispondano a quelle dell'agente. È possibile includere script della riga di comando, ad node --version esempio nella pipeline, per verificare cosa è installato nell'agente. Usare il programma di installazione dello strumento node (come illustrato in questa guida) per distribuire la stessa versione nell'agente oppure eseguire npm install i comandi per aggiornare gli strumenti alle versioni desiderate.

• Se le compilazioni hanno esito negativo in modo intermittente durante il ripristino dei pacchetti, il registro npm presenta problemi o si verificano problemi di rete tra il data center di Azure e il Registro di sistema. Non possiamo controllare questi fattori. Scoprire se l'uso di Azure Artifacts con un registro npm come origine upstream migliora l'affidabilità delle compilazioni.

• Se si usa nvm per gestire versioni diverse di Node.js, è consigliabile passare all'attività Programma di installazione dello strumento node. (nvm viene installato per motivi cronologici nell'immagine macOS. nvm gestisce più versioni node.js aggiungendo alias della shell e modificando PATH, che interagisce in modo non corretto con il modo in cui Azure Pipelines esegue ogni attività in un nuovo processo.

  L'attività Programma di installazione dello strumento node gestisce correttamente questo modello. Tuttavia, se il lavoro richiede l'uso di nvm, è possibile aggiungere lo script seguente all'inizio di ogni pipeline:

  steps:
  - bash: |
      NODE_VERSION=16  # or whatever your preferred version is
      npm config delete prefix  # avoid a warning
      . ${NVM_DIR}/nvm.sh
      nvm use ${NODE_VERSION}
      nvm alias default ${NODE_VERSION}
      VERSION_PATH="$(nvm_version_path ${NODE_VERSION})"
      echo "##vso[task.prependPath]$VERSION_PATH"
  

  Quindi, node e altri strumenti da riga di comando funzionano per il resto del processo della pipeline. In ogni passaggio in cui si usa il nvm comando avviare lo script con il codice seguente:

  - bash: |
      . ${NVM_DIR}/nvm.sh
      nvm <command>
  

Domande frequenti

D: Dove è possibile ottenere altre informazioni su Azure Artifacts e sul servizio Gestione pacchetti?

R: Gestione pacchetti in Azure Artifacts

D: Dove è possibile ottenere altre informazioni sulle attività?

R: Attività di compilazione, rilascio e test

D: Ricerca per categorie correggere un errore della pipeline con il messaggio "ERRORE IRREVERSIBILE: CALL_AND_RETRY_LAST allocazione non riuscita - Heap JavaScript in memoria insufficiente"?

R: Questo tipo di errore si verifica quando il pacchetto Node.js supera il limite di utilizzo della memoria. Per risolvere il problema, aggiungere una variabile come NODE_OPTIONS e assegnargli un valore --max_old_space_size=16384.

D: Come è possibile eseguire la versione dei pacchetti npm come parte del processo di compilazione?

R: Un'opzione consiste nell'usare una combinazione di controllo della versione e versione npm. Al termine di un'esecuzione della pipeline, è possibile aggiornare il repository con la nuova versione. In questo YAML è presente un repository GitHub e il pacchetto viene distribuito in npmjs. La compilazione ha esito negativo se si verifica una mancata corrispondenza tra la versione del pacchetto in npmjs e il package.json file.

variables:
    MAP_NPMTOKEN: $(NPMTOKEN) # Mapping secret var

trigger:
- none

pool:
  vmImage: 'ubuntu-latest'

steps: # Checking out connected repo
- checkout: self
  persistCredentials: true
  clean: true
    
- task: npmAuthenticate@0
  inputs:
    workingFile: .npmrc
    customEndpoint: 'my-npm-connection'
    
- task: UseNode@1
  inputs:
    version: '16.x'
  displayName: 'Install Node.js'

- script: |
    npm install
  displayName: 'npm install'

- script: |
    npm pack
  displayName: 'Package for release'

- bash: | # Grab the package version
    v=`node -p "const p = require('./package.json'); p.version;"`
    echo "##vso[task.setvariable variable=packageVersion]$v"

- task: CopyFiles@2
  inputs:
      contents: '*.tgz'
      targetFolder: $(Build.ArtifactStagingDirectory)/npm
  displayName: 'Copy archives to artifacts staging directory'

- task: CopyFiles@2
  inputs:
    sourceFolder: '$(Build.SourcesDirectory)'
    contents: 'package.json' 
    targetFolder: $(Build.ArtifactStagingDirectory)/npm
  displayName: 'Copy package.json'

- task: PublishBuildArtifacts@1 
  inputs:
    PathtoPublish: '$(Build.ArtifactStagingDirectory)/npm'
    artifactName: npm
  displayName: 'Publish npm artifact'

- script: |  # Config can be set in .npmrc
    npm config set //registry.npmjs.org/:_authToken=$(MAP_NPMTOKEN) 
    npm config set scope "@myscope"
    # npm config list
    # npm --version
    npm version patch --force
    npm publish --access public

- task: CmdLine@2 # Push changes to GitHub (substitute your repo)
  inputs:
    script: |
      git config --global user.email "username@contoso.com"
      git config --global user.name "Azure Pipeline"
      git add package.json
      git commit -a -m "Test Commit from Azure DevOps"
      git push -u origin HEAD:main