Opplæring: Konfigurere et byggforløp hver natt for finans- og driftsapper ved hjelp av Azure DevOps

Kunder som utvikler X++-tilpassinger for økonomi- og driftsapper, trenger et automatisert samlebånd som kompilerer koden, oppretter en distribuerbar pakke og gjør den tilgjengelig for utgivelse. Ved hjelp av enhetlige miljøer i administrasjonssenteret for Power Platform er kompileringsutdataene en enhetlig Power Platform-pakke som kan inkludere dataverse løsninger sammen med X++-kompilerte utdata, som alle kan distribueres gjennom én enkelt pac package deploy kommando.

I denne opplæringen lærer du hvordan du kan gjøre følgende:

  • Konfigurere NuGet-pakkefeeder med de nødvendige byggereferansepakkene
  • Opprett packages.config og nuget.config filer for versjonsbehandling
  • Bygg et Azure DevOps YAML-datasamlebånd som kompilerer X++ og produserer en enhetlig pakke etter en tidsplan hver natt
  • Du kan eventuelt inkludere én eller flere Dataverse-løsninger i den enhetlige pakken

Som et eksempel på dette scenarioet har en kunde X++-tilpasninger for Dynamics 365 Finance som kjører på et enhetlig miljø. De vil ha en nattlig bygg som kompilerer koden, pakker den sammen med sine Dataverse-løsninger og publiserer artefaktene for utgivelsessamlebåndet som skal distribueres.

Før du starter

Trinn 1: Få referansepakkene for NuGet-bygget

Byggeprosessen X++ krever NuGet-pakker som inneholder kompilatorverktøyene og referansesamlingene for plattformen og programmodulene. Et fullstendig bygg krever fem pakker.

Notat

På grunn av stor størrelse for Azure DevOps er programmodulen delt inn i to separate pakker.

NuGet-pakke Formål Navn på delt ressursbibliotek for LCS
Microsoft.Dynamics.AX.Platform.CompilerPackage X++-kompilator (xppc.exe) og relaterte byggverktøy PUXX/10.X.XX – Kompilatorverktøy
Microsoft.Dynamics.AX.Platform.DevALM.BuildXpp Kompilerte plattformmodulreferanser optimalisert for bygging PUXX/10.X.XX – referanse for plattformbygg
Microsoft.Dynamics.AX.Application1.DevALM.BuildXpp Kompilerte programmodulreferanser (del 1) PUXX/10.X.XX – byggreferanse for program 1
Microsoft.Dynamics.AX.Application2.DevALM.BuildXpp Kompilerte programmodulreferanser (del 2) PUXX/10.X.XX – byggreferanse for program 2
Microsoft.Dynamics.AX.ApplicationSuite.DevALM.BuildXpp Kompilerte application suite-modulreferanser PUXX/10.X.XX – byggreferanse for programserie

Viktig!

Du kan for øyeblikket laste ned disse NuGet-pakkene fra Biblioteket for delte aktiva i Microsoft Dynamics Lifecycle Services (LCS). Alle miljøer som opererer enhetlige miljøer i administrasjonssenteret for Power Platform, kan få tilgang til biblioteket for delte aktiva i LCS for å laste ned disse ressursene. En erstatningsdistribusjonsmekanisme som ikke krever LCS, kommer snart. Vi planlegger å oppdatere denne opplæringen når denne funksjonen er tilgjengelig.

Notat

NuGet-pakkene inneholder versjonsdetaljer som må være lik eller lavere enn versjonen av målfinansierings- og driftsmiljøet. Når du bruker en kvalitetsoppdatering for miljøet, kan du laste ned de tilsvarende NuGet-pakkeversjonene for å holde bygget justert. Hvis du bare utvider plattformen (ingen application suite-tilpassinger), trenger CompilerPackage du kanskje bare pakkene og Platform.DevALM.BuildXpp pakkene. De fleste kunder som utvider programfunksjonaliteten, trenger imidlertid alle fem.

Publiser pakker i en Azure Artifacts-feed

  1. Gå til Opprett feed for artefakter> i Azure DevOps-prosjektet. Gi feeden navn (for eksempel FinOpsNuGet) og velg Opprett.

  2. Last ned NuGet-pakkene fra LCS Shared Asset Library som samsvarer med målmiljøversjonen.

  3. Last ned nuget.exe og publiser hver pakke i feeden. Det kan være lurt å bruke Koble til feed-knappen i Azure DevOps for å få den fullstendige nettadressen som skal brukes i eksemplene nedenfor, da noen eldre prosjekter kan ha en annen URL-adressestruktur.

    nuget.exe push -Source "https://pkgs.dev.azure.com/<org>/<project>/_packaging/<feed>/nuget/v3/index.json" -ApiKey AZ Microsoft.Dynamics.AX.Platform.CompilerPackage.nupkg
    nuget.exe push -Source "https://pkgs.dev.azure.com/<org>/<project>/_packaging/<feed>/nuget/v3/index.json" -ApiKey AZ Microsoft.Dynamics.AX.Platform.DevALM.BuildXpp.nupkg
    nuget.exe push -Source "https://pkgs.dev.azure.com/<org>/<project>/_packaging/<feed>/nuget/v3/index.json" -ApiKey AZ Microsoft.Dynamics.AX.Application1.DevALM.BuildXpp.nupkg
    nuget.exe push -Source "https://pkgs.dev.azure.com/<org>/<project>/_packaging/<feed>/nuget/v3/index.json" -ApiKey AZ Microsoft.Dynamics.AX.Application2.DevALM.BuildXpp.nupkg
    nuget.exe push -Source "https://pkgs.dev.azure.com/<org>/<project>/_packaging/<feed>/nuget/v3/index.json" -ApiKey AZ Microsoft.Dynamics.AX.ApplicationSuite.DevALM.BuildXpp.nupkg
    
  4. Kontroller at alle fem pakkene vises i Azure DevOps Artefakter-feeden.

Trinn 2: Legge til konfigurasjonsfiler i repositoriet

To konfigurasjonsfiler kontrollerer hvilke NuGet-pakker som gjenopprettes og hvor de kommer fra. Legg til begge filene i en mappe i repositoriet, for eksempel BuildPipeline/.

nuget.config

Denne filen peker NuGet til Azure Artifacts-feeden. Erstatt plassholderverdiene med organisasjonen, prosjektet og feednavnene.

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <packageSources>
    <clear />
    <add key="FinOpsNuGet" value="https://pkgs.dev.azure.com/<org>/<project>/_packaging/<feed>/nuget/v3/index.json" />
  </packageSources>
</configuration>

packages.config

Denne filen angir de nøyaktige versjonene av hver NuGet-pakke. Oppdater versjonsnumrene slik at de samsvarer med pakkene du publiserte i feeden.

<?xml version="1.0" encoding="utf-8"?>
<packages>
    <package id="Microsoft.Dynamics.AX.Platform.CompilerPackage" version="7.0.7367.146" targetFramework="net40" />
    <package id="Microsoft.Dynamics.AX.Platform.DevALM.BuildXpp" version="7.0.7367.146" targetFramework="net40" />
    <package id="Microsoft.Dynamics.AX.Application1.DevALM.BuildXpp" version="10.0.1935.21" targetFramework="net40" />
    <package id="Microsoft.Dynamics.AX.Application2.DevALM.BuildXpp" version="10.0.1935.21" targetFramework="net40" />
    <package id="Microsoft.Dynamics.AX.ApplicationSuite.DevALM.BuildXpp" version="10.0.1935.21" targetFramework="net40" />
</packages>

Tips

Plattformpakkene (CompilerPackage og Platform.DevALM.BuildXpp) bruker et 7.0.XXXX.XX versjonsskjema, mens programpakkene (Application1, Application2og ApplicationSuite) bruker et 10.0.XXXX.XX versjonsvalg. Disse versjonene er uavhengige og oppdateres med hver kvalitetsoppdatering.

Trinn 3: Opprette byggforløpet

Opprett en fil med navnet nightly-build.yml i repositoriet ved hjelp av YAML-malen nedenfor. Dette datasamlebåndet kompilerer X++-koden, oppretter en enhetlig Power Platform-pakke og publiserer artefaktene.

  1. Klikk på Pipelines i venstre navigasjon fra Azure DevOps, og klikk deretter opprett ny datasamlebåndknappen midt på siden.
  2. Velg Azure Repos Git under «Hvor er koden din?»
  3. Velg navnet på koderepositoriet.
  4. Velg Eksisterende AZURe Pipelines YAML-fil under Konfigurer datasamlebåndet.
  5. Til slutt velger du «nightly-build.yml» som ble opprettet tidligere ved hjelp av YAML-malen nedenfor.

Pipeline-variabler

Datasamlebåndet bruker variabler for å unngå hardkoding av versjonstall og baner. Når du oppdaterer NuGet-pakker for en ny kvalitetsoppdatering, endrer du bare versjonsvariablene.

Full pipeline YAML

trigger: none

schedules:
  - cron: '0 4 * * *'  # Runs at 4:00 AM UTC every day
    displayName: 'Nightly Build'
    branches:
      include:
        - master
    always: true

pool:
  vmImage: 'windows-latest'

variables:
  # -- NuGet package versions --
  # Update these only when required if you have new Nuget package versions that you must use.  
  PlatformVersion: '7.0.7367.146'
  ApplicationVersion: '10.0.1935.21'

  # -- Paths --
  NuGetConfigPath: '$(Build.SourcesDirectory)/BuildPipeline'
  NuGetInstallDir: '$(Build.SourcesDirectory)/NuGets'
  MetadataPath: '$(Build.SourcesDirectory)/XppMetadata'
  SolutionPath: '$(Build.SourcesDirectory)/VS_Solutions/DataverseIntegration/DataverseIntegration.sln'

  # -- NuGet package folder names (using -ExcludeVersion for stable paths) --
  CompilerPackage: '$(NuGetInstallDir)/Microsoft.Dynamics.AX.Platform.CompilerPackage'
  PlatformBuildRef: '$(NuGetInstallDir)/Microsoft.Dynamics.AX.Platform.DevALM.BuildXpp'
  App1BuildRef: '$(NuGetInstallDir)/Microsoft.Dynamics.AX.Application1.DevALM.BuildXpp'
  App2BuildRef: '$(NuGetInstallDir)/Microsoft.Dynamics.AX.Application2.DevALM.BuildXpp'
  AppSuiteBuildRef: '$(NuGetInstallDir)/Microsoft.Dynamics.AX.ApplicationSuite.DevALM.BuildXpp'

  # -- Unified package output --
  UnifiedPackageOutput: '$(Build.ArtifactStagingDirectory)/UnifiedPackage'

stages:
  - stage: Build
    displayName: 'Compile X++ and Create Unified Package'
    jobs:
      - job: BuildXpp
        displayName: 'Build X++ and package'
        timeoutInMinutes: 120
        steps:
          # -------------------------------------------------------
          # Step 1: Install NuGet packages
          # -------------------------------------------------------
          - task: NuGetCommand@2
            displayName: 'Restore NuGet build packages'
            inputs:
              command: 'custom'
              arguments: >
                install "$(NuGetConfigPath)/packages.config"
                -ConfigFile "$(NuGetConfigPath)/nuget.config"
                -OutputDirectory "$(NuGetInstallDir)"
                -ExcludeVersion
                -Verbosity Detailed
                -Noninteractive

          # -------------------------------------------------------
          # Step 2: Build the X++ solution
          # -------------------------------------------------------
          - task: VSBuild@1
            displayName: 'Build X++ solution'
            inputs:
              solution: '$(SolutionPath)'
              vsVersion: '17.0'
              msbuildArgs: >
                /p:BuildTasksDirectory="$(CompilerPackage)/DevAlm"
                /p:MetadataDirectory="$(MetadataPath)"
                /p:FrameworkDirectory="$(CompilerPackage)"
                /p:ReferenceFolder="$(PlatformBuildRef)/ref/net40;$(App1BuildRef)/ref/net40;$(App2BuildRef)/ref/net40;$(AppSuiteBuildRef)/ref/net40;$(MetadataPath);$(Build.BinariesDirectory)"
                /p:ReferencePath="$(CompilerPackage)"
                /p:OutputDirectory="$(Build.BinariesDirectory)"
                /p:CompilerMetadata="$(Build.BinariesDirectory)"

          # -------------------------------------------------------
          # Step 3: Install NuGet 3.3.0 (required for packaging)
          # -------------------------------------------------------
          - task: NuGetToolInstaller@1
            displayName: 'Install NuGet 3.3.0 for packaging'
            inputs:
              versionSpec: '3.3.0'

          # -------------------------------------------------------
          # Step 4: Create the Power Platform unified package
          # -------------------------------------------------------
          - task: XppCreatePackage@3
            displayName: 'Create Power Platform unified package'
            inputs:
              XppToolsPath: '$(CompilerPackage)'
              CreateCloudPackage: true
              CloudPackagePlatVersion: '$(PlatformVersion)'
              CloudPackageAppVersion: '$(ApplicationVersion)'
              CloudPackageOutputLocation: '$(UnifiedPackageOutput)'
              DeployablePackagePath: '$(Build.ArtifactStagingDirectory)/AXDeployableRuntime.zip'

          # -------------------------------------------------------
          # Step 5 (Optional): Add Dataverse solutions to the package
          # -------------------------------------------------------
          # If you have Dataverse solutions (managed .zip files) that
          # should be deployed alongside your X++ code, add them to
          # the unified package. Each solution becomes part of the
          # same package that pac package deploy will process.

          - task: PowerPlatformToolInstaller@2
            displayName: 'Install Power Platform Build Tools'
            condition: and(succeeded(), ne(variables['DataverseSolutionsPath'], ''))

          - task: PowerShell@2
            displayName: 'Add Dataverse solutions to unified package'
            condition: and(succeeded(), ne(variables['DataverseSolutionsPath'], ''))
            inputs:
              targetType: 'inline'
              script: |
                $solutionsPath = "$(DataverseSolutionsPath)"
                $packageFolder = "$(UnifiedPackageOutput)"

                if (-not (Test-Path $solutionsPath)) {
                    Write-Host "No Dataverse solutions path specified or found. Skipping."
                    exit 0
                }

                Write-Host "Looking for Dataverse solution .zip files in: $solutionsPath"
                $solutions = Get-ChildItem -Path $solutionsPath -Filter "*.zip" -File

                if ($solutions.Count -eq 0) {
                    Write-Host "No solution .zip files found. Skipping."
                    exit 0
                }

                # The unified package uses a specific folder structure.
                # Dataverse solutions go under the PackageDeployer/solutions subfolder.
                $targetDir = Join-Path $packageFolder "PkgFolder"
                if (-not (Test-Path $targetDir)) {
                    New-Item -ItemType Directory -Path $targetDir -Force | Out-Null
                }

                foreach ($sol in $solutions) {
                    Write-Host "Adding solution: $($sol.Name)"
                    Copy-Item -Path $sol.FullName -Destination $targetDir
                }

                Write-Host "Added $($solutions.Count) Dataverse solution(s) to the unified package."

          # -------------------------------------------------------
          # Step 6: Zip the unified package
          # -------------------------------------------------------
          # PowerPlatformPackageDeploy expects a .zip file, not
          # an unzipped folder. Archive the unified package output
          # before publishing.
          - task: ArchiveFiles@2
            displayName: 'Zip unified package'
            inputs:
              rootFolderOrFile: '$(UnifiedPackageOutput)'
              includeRootFolder: false
              archiveType: 'zip'
              archiveFile: '$(Build.ArtifactStagingDirectory)/UnifiedPackage.zip'

          # -------------------------------------------------------
          # Step 7: Publish build artifacts
          # -------------------------------------------------------
          - task: PublishBuildArtifacts@1
            displayName: 'Publish unified package artifact'
            inputs:
              PathtoPublish: '$(Build.ArtifactStagingDirectory)/UnifiedPackage.zip'
              ArtifactName: 'UnifiedPackage'

          - task: PublishBuildArtifacts@1
            displayName: 'Publish deployable runtime package artifact'
            inputs:
              PathtoPublish: '$(Build.ArtifactStagingDirectory)/AXDeployableRuntime.zip'
              ArtifactName: 'LCSPackage'

Forstå pipelinen

Datasamlebåndet har sju kjernetrinn:

Trinn Oppgave Formål
1 NuGetCommand@2 Gjenoppretter kompilatoren og referansepakkene fra Azure Artifacts-feeden. Flagget -ExcludeVersion fjerner versjonsnumre fra mappenavn, slik at MSBuild-baner holder seg stabile på tvers av versjonsoppdateringer.
2 VSBuild@1 Kompilerer X++-løsningen ved hjelp av MSBuild med argumenter som peker til NuGet-pakkeplasseringene for kompilatoren, plattformreferansene og programreferansene.
3 NuGetToolInstaller@1 Installerer NuGet 3.3.0, som kreves av pakkeoppgaven. Versjon 3.4 og nyere bruker semantisk versjonskontroll som ikke er kompatibel med pakkeformatet som kan distribueres.
4 XppCreatePackage@3 Oppretter både en tradisjonell distribuerbar pakke (.zip) og en enhetlig Power Platform-pakke. Den enhetlige pakken er formatet som kreves for å distribuere til enhetlige miljøer via pac package deploy.
5 PowerShell@2 (Valgfritt) Legger til dataversløsning .zip filer i den enhetlige pakken, slik at X++-tilpasninger og Dataverse-løsninger distribueres sammen som én enkelt enhet.
6 ArchiveFiles@2 Pakker inn den enhetlige pakkemappen i en .zip fil. Oppgaven PowerPlatformPackageDeploy krever en .zip fil som inndata, ikke en upakket mappe.
7 PublishBuildArtifacts@1 Publiserer begge pakkeformatene som samlebåndartefakter for nedstrøms utgivelsessamlebånd.

Trinn 4: Inkludert dataverse løsninger (valgfritt)

En viktig fordel med enhetlige miljøer er at X++-tilpasninger og Dataverse-løsninger kan kombineres til én enkelt distribuerbar pakke. Dette betyr at utgivelsessamlebåndet bruker én pac package deploy kommando til å distribuere alt.

Slik inkluderer du Dataverse-løsninger i ditt nattlige bygg:

  1. Legg til den dataverse administrerte løsningen .zip filer i en mappe i repositoriet (for eksempel DataverseSolutions/).

  2. Angi variabelen DataverseSolutionsPath i datasamlebåndet:

    variables:
      DataverseSolutionsPath: '$(Build.SourcesDirectory)/DataverseSolutions'
    
  3. Datasamlebåndets valgfrie trinn 5 henter automatisk alle .zip filer fra denne banen, og legger dem til i den enhetlige pakken.

Når utgivelsessamlebåndet senere kjører pac package deploy, behandler den hele den enhetlige pakken, og distribuerer både X++runtime-pakken til økonomi- og driftskjøringen og dataversløsningene til dataversmiljøet.

Notat

Hvis du ikke har dataverse løsninger å inkludere, lar du variabelen stå tom eller fjerne den DataverseSolutionsPath . Trinn 5s betingelseskontroll hopper over dataverstrinnene automatisk.

Trinn 5: Oppdatere pakkeversjoner for kvalitetsoppdateringer

Når du bruker en ny kvalitetsoppdatering (PQU) på miljøene, oppdaterer du byggforløpet slik at det samsvarer:

  1. Last ned de nye NuGet-pakkene fra LCS Shared Asset Library.
  2. Publiser de nye versjonene i Azure Artifacts-feeden.
  3. Oppdater packages.config med de nye versjonsnumrene.
  4. Oppdater datasamlebåndvariablene PlatformVersion og ApplicationVersion til samsvar.

Tips

Hold versjonsnumrene packages.config synkronisert med PlatformVersion variablene og ApplicationVersion datasamlebåndvariablene. Filen packages.config kontrollerer hvilke NuGet-pakker som gjenopprettes, mens datasamlebåndvariablene forteller XppCreatePackage oppgaven hvilken plattform og programversjonsmetadata som skal stemples inn i den enhetlige pakken.

Feilsøking

Problem Løsning
Bygg mislykkes med manglende referanser Sørg for at du publiserer alle de fem NuGet-pakkene i artefaktfeeden og at versjonene samsvarer packages.config . Hvis du bare utvider plattformen, trenger Application1du fortsatt , Application2og ApplicationSuite for referanseoppløsning.
XppCreatePackage mislykkes med versjonskonflikt CloudPackagePlatVersion Og CloudPackageAppVersion verdiene må samsvare med NuGet-pakkeversjonene du gjenopprettet.
NuGet-gjenoppretting mislykkes med 401 Byggtjenestekontoen for datasamlebåndet trenger Lesertilgang til Azure Artifacts-feeden. Gå tilTillatelser for >>, og legg til build-tjenesten.
Emballasjen mislykkes med semantisk versjonsfeil Sørg for at trinn 3 installerer NuGet 3.3.0. Versjon 3.4 og nyere introduserer semantisk versjonskontroll som ikke er kompatibel med den distribuerbare pakkegenereringen.
fnomoduledefinition.json file not found Banen CloudPackageOutputLocation kan være feil, eller den XppToolsPath peker kanskje ikke til en gyldig kompileringspakke. Kontroller variable baner.

Neste trinn