As is sometimes the case on X++ development projects, this project had a dependency on C# code to handle some integration scenarios. Consequently, the repository structure outlined in this post reflects the unique scenario where we both needed to have source access to the C# code, and we wanted to be able to build it alongside the X++ code every time we created a new software deployable package. This guidance can still be used to set up an X++-only repository.<\/p>\n
Because we chose to focus on current trends, there are several important areas that we did not explore and are not covered by this post, namely:<\/p>\n
- \n
- Continuous Deployment (CD) \u2013 We did not need automated CD for this project – there are known patterns for setting up CD using the Microsoft-provided Azure DevOps (AZDO) extension here<\/a>.<\/li>\n
- Automated testing \u2013 Automated testing requires a dedicated build Virtual Machine (VM) and special modifications to the build pipeline definition, or the creation of a separate pipeline altogether.<\/li>\n<\/ul>\n
Prerequisites<\/h2>\n
- \n
- Basic knowledge of the X++ source file directory structure on a developer machine is required to correctly locate, move, and version the relevant models.<\/li>\n
- Basic knowledge of Git is strongly recommended, as it will add context to the setup steps outlined in this post.<\/li>\n<\/ul>\n
\nWalkthrough<\/h2>\n
Note: It is a best practice to generate deployable packages via build pipeline versus locally generating packages on dev environments. Thus, this walkthrough outlines both repo and build pipeline setup.<\/em><\/p>\n
Repository Structure<\/strong><\/h3>\n
We used the below structure for the project repository, which prioritizes high organization at the root level of the structure. This structure is not mandatory for managing X++ in Git and we mention it here for context only.<\/p>\n
<\/p>\n
![\"Repository](\"https:\/\/devblogs.microsoft.com\/cse\/wp-content\/uploads\/sites\/55\/2022\/06\/XppGitRepoStructure.png\")
<\/a><\/p>\nFigure 1: X++ Git Repository Structure<\/strong><\/p>\n
<\/p>\n
Set up the Git Repository<\/strong><\/h3>\n
- \n
- Create a new repo in AZDO.<\/strong>\n
- \n
- Identify the AZDO project where you will configure the repository, then follow the instructions here<\/a> to create a new repository. Stop at step 2 of the Clone the repo to your computer<\/em> section, as the repo cloning will require some special adjustments for the D365 F&O directory structure. Record the URL of your repo as specified in step 2 of the instructions.<\/li>\n<\/ol>\n<\/li>\n
- Identify the X++ model that will be versioned<\/strong>.\n
- \n
- If you are creating a new X++ model for this exercise, follow the instructions here<\/a> to generate the model before moving on to the next step.<\/li>\n
- Note the name of the top-level directory for the model you want to version, which can usually be found under the K:\\AosService\\PackagesLocalDirectory <\/em>location on a dev machine.<\/li>\n<\/ol>\n<\/li>\n
- Clone the repo<\/strong><\/li>\n<\/ol>\n
Note: these instructions outline Git repo setup using Visual Studio 2019. There are alternate setup options available, such as using the Git command line.<\/em><\/p>\n
![\"Visual](\"https:\/\/devblogs.microsoft.com\/cse\/wp-content\/uploads\/sites\/55\/2022\/06\/VSCloneRepo.png\")
<\/a><\/em><\/strong><\/p>\nFigure 2: Clone Repository dialog in Visual Studio<\/strong><\/p>\n
- \n
- \n
- \n
- In Visual Studio, navigate to Git > Clone.<\/em><\/li>\n
- In Path<\/em>, enter the local destination path where you want to store the model. By default Visual Studio 2019 will select a location that looks like C:\\Users\\<Your User>\\source\\repos<\/em>. Record this directory location.<\/li>\n
- In Repository location<\/em>, enter the URL of the repo you created in step 1 of these instructions. Note: if you populate the repository location after<\/strong> the path, the unique name of your repo should automatically be added to the directory path.<\/em> Ensure this is the name you want, and change it if desired.<\/li>\n
- Click Clone<\/em>.<\/li>\n<\/ol>\n<\/li>\n<\/ol>\n
- \n
- Move the source directories and set up symbolic links<\/strong>.<\/li>\n<\/ol>\n
Note: To address Git’s preference for an empty repository location while also maintaining Application Object Server (AOS) visibility to the pertinent custom source files, we employed a workaround involving a file system tool called <\/em>Symbolic Links<\/em><\/a>.\u00a0 Symbolic Links are in essence \u201cdeep shortcuts\u201d between directories. A .gitignore file excluding the system-standard models would also address this issue.<\/em><\/p>\n
- \n
- \n
- \n
- Move the model directories. <\/strong>For each of the model folders identified in step 2:\n
- \n
- Find the path to the top-level model directory. To find Model1 from the example repo structure above, we would usually search somewhere like K:\\AosService\\PackagesLocalDirectory\\Model1<\/em> .<\/li>\n
- Using either command line or File Explorer, move the model folder from K:\\AosService\\PackagesLocalDirectory <\/em>to the target folder you created and recorded in step 3. Note: if you are moving an existing model, the folder contents may be in-use. You will need to shut down the AOS and related services before you are allowed to move the entire folder contents.<\/em><\/li>\n<\/ol>\n<\/li>\n
- Set up symbolic links. <\/strong>Each moved model directory will need a symbolic link to point the D365 services to its new location. To do this, open a Command Prompt in admin mode, navigate to the PackagesLocalDirectory <\/em>folder, and then, for each folder you moved, enter the following command:<\/li>\n<\/ol>\n<\/li>\n<\/ol>\n
>mklink \/D \u201cThe exact name of the model folder\u201d \u201cThe file path to the new folder location\u201d<\/em><\/p>\n
For example, if you used all of the defaults outlined above, the command would look something like:<\/p>\n
>mklink \/D \u201cModel1\u201d \u201cC:\\Users\\<Your User>\\source\\repos\\XppGitRepo\u201d<\/em><\/p>\n
You can validate the links manually by navigating to the new locations starting at the AOS folder, either via File Explorer or command line. The model folder contents should look like they exist under the AOS folder.<\/strong><\/p>\n
\nBuild Pipeline Overview<\/strong><\/h3>\n
The X++ build pipeline we created for this project uses the Microsoft-hosted agent build approach outlined here<\/a>, and it is based on the sample build definitions available here<\/a>.<\/p>\n
The main advantage of this approach is that it does not require a dedicated build VM to generate deployable packages.\u00a0 The main disadvantage of this approach is that it does not natively support automated F&O test execution.<\/p>\n
Technically, this pipeline can be created as either a \u201cClassic\u201d (non-YAML) pipeline, or a YAML-based scripted pipeline; for improved modularity and maintainability, this walkthrough uses the latter approach.<\/p>\n
The pipeline executes two main jobs which:<\/p>\n
- \n
- Create a production-ready package which excludes test models<\/li>\n
- Create an automated test-ready package which includes all models<\/li>\n<\/ol>\n
The same build definition generates both packages to avoid any potential code or configuration drift between test-bound and production-bound packages.<\/p>\n
To uniquely identify test versus non-test models in the Visual Studio solution referenced by the build pipeline, we employed Visual Studio\u2019s native solution configuration features to map production-bound models in the \u2018release\u2019 configuration, and test-bound models in the \u2018debug\u2019 configuration. More information on solution configurations can be found here.<\/a><\/p>\n
<\/p>\n
![\"Build](\"https:\/\/devblogs.microsoft.com\/cse\/wp-content\/uploads\/sites\/55\/2022\/06\/XppGitPipelineOverview.png\")
<\/a><\/p>\nFigure 3: Simplified build pipeline diagram<\/strong><\/p>\n
\u00a0<\/strong><\/p>\n
Build Pipeline Scripts and Configuration<\/strong><\/h3>\n
Build pipelines are complex, and YAML-based pipelines are dependent on repository structure, so rather than provide a step-by-step walkthrough, we are providing detailed explanations along with the YAML file contents, in dependency order, as a starting point for you to build your own pipeline.<\/p>\n
packages.config<\/strong><\/h4>\n
Description<\/strong>: Specifies the NuGet packages and versions used to set up both the compiler tools and system-standard source files (upon which the build pipeline depends to generate compiled X++ source code).<\/p>\n
Note: As noted in <\/em>the documentation on hosted build automation<\/em><\/a>, these packages must be manually uploaded to an AZDO artifact feed in your own AZDO project before the references can be successfully retrieved by the build pipeline. Also, you will need to update the highlighted version numbers within your config file to match the application and platform versions you want to compile against.<\/em><\/p>\n
Contents:<\/strong><\/p>\n
<?xml version=\"1.0\" encoding=\"utf-8\"?>\r\n<packages>\r\n <package id=\"Microsoft.Dynamics.AX.Platform.DevALM.BuildXpp\" version=\"7.0.6253.76<\/mark>\" targetFramework=\"netstandard1.6\" \/>\r\n <package id=\"Microsoft.Dynamics.AX.Application.DevALM.BuildXpp\" version=\"10.0.1084.80<\/mark>\" targetFramework=\"netstandard1.6\" \/>\r\n <package id=\"Microsoft.Dynamics.AX.ApplicationSuite.DevALM.BuildXpp\" version=\"10.0.1084.80<\/mark>\" targetFramework=\"netstandard1.6\" \/>\r\n <package id=\"Microsoft.Dynamics.AX.Platform.CompilerPackage\" version=\"7.0.6253.76<\/mark>\" targetFramework=\"netstandard1.6\" \/>\r\n<\/packages><\/pre>\n
\u00a0<\/strong><\/p>\n
nuget.config<\/strong><\/h4>\n
Description<\/strong>: Specifies the AZDO artifact feed to be used for retrieval of the packages specified in packages.config. Note: You will need to update the target URL and optionally the key name to match your artifact feed.<\/em><\/p>\n
Contents:<\/strong><\/p>\n
<?xml version=\"1.0\" encoding=\"utf-8\"?>\r\n<configuration>\r\n <packageSources>\r\n <clear \/>\r\n <add key=\"XppBuildDependencies<\/mark>\" value=\"https:\/\/pkgs.dev.azure.com\/PROJECTCOLLECTIONNAME\/PROJECTGUID<\/mark>\/_packaging\/ARTIFACTFEEDNAME<\/mark>\/nuget\/v3\/index.json\" \/>\r\n <\/packageSources>\r\n<\/configuration>\r\n<\/pre>\n
<\/p>\n
Jobs-xpp-build.yaml<\/strong><\/h4>\n
Description<\/strong>: Sets up NuGet dependencies, generates a unique model version ID for the compiled result, performs a special execution of VSBuild using the X++ compiler tools and source files specified in packages.config, records the compile logs, and optionally generates a deployable package and publishes the package to the pipeline results.<\/p>\n
Note: we added conditions to the last two steps to separate the compilation of test models from production models. While this particular pipeline does not perform any additional steps in the test job, it serves as a structural example of how test execution and package generation could be separated and fully executed in a more advanced pipeline implementation.<\/em><\/p>\n
Contents:<\/strong><\/p>\n
parameters:\r\n jobName: 'buildxppmodel' # Overridable name for job.\r\n displayName: 'Build X++ Package' # Overridable display name for job.\r\n xppModelSolution: '' # X++ model solution to build\r\n metadataPath: '' # Location of X++ model metadata\r\n nugetConfigsPath: '' # Location of X++ model nugets config\r\n configuration: 'debug' # Build configuration\r\n package: 'false' # Whether to package the model as an artifact\r\n\r\njobs:\r\n- job: ${{ parameters.jobName }}\r\n displayName: ${{ parameters.displayName }}\r\n\r\n variables:\r\n AppPackage: 'Microsoft.Dynamics.AX.Application.DevALM.BuildXpp'\r\n AppSuitePackage: 'Microsoft.Dynamics.AX.ApplicationSuite.DevALM.BuildXpp'\r\n PlatPackage: 'Microsoft.Dynamics.AX.Platform.DevALM.BuildXpp'\r\n ToolsPackage: 'Microsoft.Dynamics.AX.Platform.CompilerPackage'\r\n NugetsPath: '$(Pipeline.Workspace)\\NuGets'\r\n\r\n steps:\r\n - task: NuGetInstaller@0\r\n displayName: NuGet Install X++ Packages\r\n inputs:\r\n solution: ${{ parameters.nugetConfigsPath }}\\packages.config\r\n nugetConfigPath: ${{ parameters.nugetConfigsPath }}\\nuget.config\r\n restoreMode: install\r\n nuGetRestoreArgs: -ExcludeVersion -OutputDirectory \"$(NugetsPath)\"\r\n\r\n - task: XppUpdateModelVersion@0\r\n displayName: Update Model Version\r\n\r\n - task: VSBuild@1\r\n displayName: Build X++ Model\r\n inputs:\r\n configuration: ${{ parameters.configuration }}\r\n solution: ${{ parameters.xppModelSolution }}\r\n msbuildArgs: \/restore \/p:BuildTasksDirectory=\"$(NugetsPath)\\$(ToolsPackage)\\DevAlm\" \/p:MetadataDirectory=\"${{ parameters.metadataPath }}\" \/p:FrameworkDirectory=\"$(NuGetsPath)\\$(ToolsPackage)\" \/p:ReferenceFolder=\"$(NuGetsPath)\\$(PlatPackage)\\ref\\net40;$(NuGetsPath)\\$(AppPackage)\\ref\\net40;$(NuGetsPath)\\$(AppSuitePackage)\\ref\\net40;${{ parameters.metadataPath }};$(Build.BinariesDirectory)\" \/p:ReferencePath=\"$(NuGetsPath)\\$(ToolsPackage)\" \/p:OutputDirectory=\"$(Build.BinariesDirectory)\"\r\n\r\n - task: CopyFiles@2\r\n displayName: 'Copy X++ Compile Log Files for Artifact Publishing'\r\n inputs:\r\n SourceFolder: $(Build.SourcesDirectory)\r\n Contents: |\r\n **\\Dynamics.AX.*.xppc.*\r\n **\\Dynamics.AX.*.labelc.*\r\n **\\Dynamics.AX.*.reportsc.*\r\n TargetFolder: $(Build.ArtifactStagingDirectory)\\Logs\\${{ parameters.configuration }}\\\r\n condition: and(succeeded(), eq('${{ parameters.package }}', 'true'))\r\n\r\n - task: XppCreatePackage@0\r\n displayName: Create Deployable Package\r\n inputs:\r\n XppToolsPath: $(NuGetsPath)\\$(ToolsPackage)\r\n XppBinariesPath: $(Build.BinariesDirectory)\r\n XppBinariesSearch: '*'\r\n DeployablePackagePath: $(Build.ArtifactStagingDirectory)\\AXDeployableRuntime_$(Build.BuildNumber)-${{ parameters.configuration }}.zip\r\n condition: and(succeeded(), eq('${{ parameters.package }}', 'true'))\r\n\r\n - task: PublishBuildArtifacts@1\r\n displayName: 'Publish Artifacts'\r\n inputs:\r\n PathtoPublish: '$(Build.ArtifactStagingDirectory)'\r\n condition: and(succeeded(), eq('${{ parameters.package }}', 'true'))\r\n<\/pre>\n<\/p>\n
Azure-pipeline-xpp.yaml<\/strong><\/h4>\n
Description<\/strong>: Triggered by changes to the target branch. Collects X++ build-relevant details such as the Visual Studio solution and the location of the X++ metadata and AZDO artifact feed. Passes these details through to a job which performs the actual model compilation and, optionally, packages the results.<\/p>\n
Contents<\/strong>:<\/p>\n
# Name must be in #.#.#.# format for X++ tasks\r\nname: $(Date:yy.MM.dd)$(Rev:.r)\r\n\r\ntrigger:\r\n- main\r\n\r\npool:\r\n name: Azure Pipelines\r\n vmImage: 'windows-2022'\r\n demands:s\r\n - msbuild\r\n - visualstudio\r\n\r\nvariables:\r\n MetadataPath: '$(Build.SourcesDirectory)\\src\\xplusplus\\Models'\r\n NugetConfigsPath: '$(Build.SourcesDirectory)\\src\\xplusplus\\XppBuild'\r\n XppModelSolution: 'src\/xplusplus\/xppBuild\/<your solution name here>.sln'\r\n\r\nstages:\r\n\r\n- stage: buildxppmodel\r\n displayName: 'Build XPP Model'\r\n dependsOn: []\r\n jobs:\r\n\r\n - template: templates\/jobs-xpp-build.yaml\r\n parameters:\r\n jobName: 'buildxppallmodels'\r\n displayName: 'Build X++ All Models'\r\n xppModelSolution: '$(XppModelSolution)'\r\n metadataPath: '$(MetadataPath)'\r\n nugetConfigsPath: '$(NugetConfigsPath)'\r\n\r\n - template: templates\/jobs-xpp-build.yaml\r\n parameters:\r\n jobName: 'buildxppdeploymentpackage'\r\n displayName: 'Build X++ Deployment Package'\r\n xppModelSolution: '$(XppModelSolution)'\r\n metadataPath: '$(MetadataPath)'\r\n nugetConfigsPath: '$(NugetConfigsPath)'\r\n configuration: 'release'\r\n package: 'true'<\/pre>\n
\nSummary<\/h2>\n
In this post we outlined the basics of setting up an X++ repository in Git as well as a YAML-based build pipeline which executes against this repository.<\/p>\n
The Team<\/h2>\n
Many thanks to Sujit D\u2019Mello<\/a> for starting this work with me, Jose Rodriguez<\/a> for helping me finish it, Joris de Gruyter<\/a> for leading the way on many of the tools and patterns we built upon for this example, and to the X++ developer community for experimenting with many of these concepts well ahead of this post\u2019s creation.<\/p>\n
<\/p>\n
<\/p>\n
<\/p>\n
<\/p>\n
<\/p>\n
<\/p>\n
<\/p>\n
<\/p>\n
<\/p>\n
<\/p>\n
<\/p>\n
<\/p>\n
<\/p>\n","protected":false},"excerpt":{"rendered":"
Overview In this post we outline the basics of setting up an X++ repository in Git as well as a YAML-based build pipeline which executes against this repository. Background Git is an increasingly popular version control system which sees broad use within the Commercial Software Engineering (CSE) organization at Microsoft. Dynamics 365 for Finance and […]<\/p>\n","protected":false},"author":93828,"featured_media":14409,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[3356,1,16],"tags":[3360,3359,3362,3361,113,151,3317,3357,3358],"class_list":["post-14381","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-business-applications","category-cse","category-devops","tag-azdo","tag-azure-devops","tag-biz-apps","tag-business-applications","tag-c","tag-devops","tag-git","tag-x","tag-xpp"],"acf":[],"blog_post_summary":"
Overview In this post we outline the basics of setting up an X++ repository in Git as well as a YAML-based build pipeline which executes against this repository. Background Git is an increasingly popular version control system which sees broad use within the Commercial Software Engineering (CSE) organization at Microsoft. Dynamics 365 for Finance and […]<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/ise\/wp-json\/wp\/v2\/posts\/14381","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/devblogs.microsoft.com\/ise\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/devblogs.microsoft.com\/ise\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/ise\/wp-json\/wp\/v2\/users\/93828"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/ise\/wp-json\/wp\/v2\/comments?post=14381"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/ise\/wp-json\/wp\/v2\/posts\/14381\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/ise\/wp-json\/wp\/v2\/media\/14409"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/ise\/wp-json\/wp\/v2\/media?parent=14381"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/ise\/wp-json\/wp\/v2\/categories?post=14381"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/ise\/wp-json\/wp\/v2\/tags?post=14381"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}
- Using either command line or File Explorer, move the model folder from K:\\AosService\\PackagesLocalDirectory <\/em>to the target folder you created and recorded in step 3. Note: if you are moving an existing model, the folder contents may be in-use. You will need to shut down the AOS and related services before you are allowed to move the entire folder contents.<\/em><\/li>\n<\/ol>\n<\/li>\n
- Find the path to the top-level model directory. To find Model1 from the example repo structure above, we would usually search somewhere like K:\\AosService\\PackagesLocalDirectory\\Model1<\/em> .<\/li>\n
- Move the model directories. <\/strong>For each of the model folders identified in step 2:\n
- \n
- In Path<\/em>, enter the local destination path where you want to store the model. By default Visual Studio 2019 will select a location that looks like C:\\Users\\<Your User>\\source\\repos<\/em>. Record this directory location.<\/li>\n
- In Visual Studio, navigate to Git > Clone.<\/em><\/li>\n
- Note the name of the top-level directory for the model you want to version, which can usually be found under the K:\\AosService\\PackagesLocalDirectory <\/em>location on a dev machine.<\/li>\n<\/ol>\n<\/li>\n
- Identify the X++ model that will be versioned<\/strong>.\n
- Identify the AZDO project where you will configure the repository, then follow the instructions here<\/a> to create a new repository. Stop at step 2 of the Clone the repo to your computer<\/em> section, as the repo cloning will require some special adjustments for the D365 F&O directory structure. Record the URL of your repo as specified in step 2 of the instructions.<\/li>\n<\/ol>\n<\/li>\n
- Create a new repo in AZDO.<\/strong>\n
- Automated testing \u2013 Automated testing requires a dedicated build Virtual Machine (VM) and special modifications to the build pipeline definition, or the creation of a separate pipeline altogether.<\/li>\n<\/ul>\n