Category Archives: Powershell

Start-AXMSBuildImport

23 Thursday Jul 2015

Posted by in Powershell

≈ 2 Comments

Tags

, , , , , , , , , , ,

This has been an extremely difficult blog post for me to write.  I have been struggling with it because I realized that I didn’t really understand the process that I was using to accomplish my VS project import.  I took an extra week to research it and hopefully write up something useful and I have actually discovered that my process may not work for a lot of people.

I am using the ImportVSProjects.proj with msbuild.exe that I found in the Dynamics AX Build Scripts.  This project is passed into msbuild.exe with parameters that allow it to loop through a TFS directory and import the found VS projects into Dynamics AX 2012.  I have since discovered that there can be issues with projects that have dependencies on AX objects or other VS projects.  I personally don’t work in an environment that has complex dependencies, so I’ve never run into any of these issues.  There are other solutions that involve using the autorun.xml to call SysTreeNodeVSProject::ImportProject and compile for a specific AOT node.  I will be exploring these in future posts but the current method is the one I use.

The Start-AXMSBuildImport function takes between 1-14 parameters:

  • ConfigPath (Client configuration for the chosen AX environment)
  • MSBuildPath (The folder location of msbuild.exe)
  • ImportVSProjectsFile (The ImportVSProjects.proj file to use)
  • ModelFileFolder (The TFS working directory location for the Model that has VS projects to import)
  • Layer (The layer to import the VS projects into)
  • LayerCode (The license code for development in the layer)
  • ModelName (The model to import the VS projects into)
  • BuildLogFolder (Specifies the log folder location.  Defaults to $env:TEMP.)
  • DetailedSummary (Parameter for msbuild.exe that creates a detailed summary in the log file.)
  • Verbosity (Parameter for msbuild.exe that allows you to set the level of logging)
  • Timeout (The value defaults to 30 minutes but can be overridden if desired)
  • SMTPServer (SMTP server to use to send the email)
  • MailMsg (Net.Mail.MailMessage object used to send the email)
  • VariablePath (Path to a file used to default the parameters/variables)

This function and the ImportVSProjects.proj can be found in Codeplex.  The steps of this function are:

  • Load the variables if a VariablePath parameter is used
  • Build the log files
  • Set up the arguments for the msbuild.exe call
  • Call msbuild.exe to import the projects
  • Send the success/fail message

I have also been cleaning up some of my PowerShell functions in preparation for putting them into a module.  I have made slight changes for uniformity and incorporated some suggestions from other AX users.  I have also incorporated my changes in the latest version of the DynamicsAXCommunity module (0.3.4).  I also have hopes that the next version will support my module with no customizations.  I will be updating past blogs posts in the near future to support my changes.

Combine-AXXPO custom PowerShell function

02 Thursday Jul 2015

Posted by in Powershell

≈ 4 Comments

Tags

, , , , , , , , ,

The Combine-AXXPO custom PowerShell function will create a single .xpo file from a directory containing .xpo files.  It is used in my build process to take the .xpos that are in TFS and combine them into a single file for import by model.

This is a fairly simple function that calls the Combine XPO tool.  As of AX 2012 R2, this tool is available in the Microsoft Dynamics AX\60\Management Utilities folder.  If you have been following my earlier posts, the path for the location is included in your profile already with .”C:\Program Files\Microsoft Dynamics AX\60\ManagementUtilities\Microsoft.Dynamics.ManagementUtilities.ps1″.  If you are using a version of AX earlier than 2012 R2, you will either have to add the tool here or include the location where it is in your profile.

This parameter takes between 2-11 parameters:

  • XpoDir (The directory holding the .xpos to be combined)
  • CombinedXpoFile (The output .xpo file)
  • SpecifiedXpoFile (A file that specifies which .xpos to combine)
  • NoDel (Allows DEL_ fields to be included for objects specified in the file)
  • utf8 (Sets the encoding of the output file to utf-8)
  • Threads (Specifies the number of threads to use for processing)
  • ExclusionsFile (A file that specifies which .xpos not to combine)
  • ViewsOnlyOnce (A parameter that can increase performance at the cost of reference errors)
  • SMTPServer (SMTP server to use to send the email)
  • MailMsg (Net.Mail.MailMessage object used to send the email)
  • VariablePath (Path to a file used to default the parameters/variables)

This function can be found in Codeplex.  The steps of this function are:

  • Load the variables if a VariablePath parameter is used
  • Generate the CombineXPOs.exe call based on the parameters passed
  • Run CombineXPOs.exe
  • Send the success/fail message

Restore-AXDatabase custom PowerShell function

18 Thursday Jun 2015

Posted by in Powershell

≈ 2 Comments

Tags

, , , , , , , , ,

I think I have officially become a bi-weekly blog.  My current schedule isn’t going to be able to support a weekly blog right now.  The Restore-AXDatabase custom PowerShell function will restore a SQL Server database from a backup file.  This is used in my custom build process to reset the build environment back to a “vanilla” instance.

A development build environment needs to be reset to an instance that is missing all of your build code before starting the new build.  It is possible to delete the build models and recompile/resync everything to get back to “vanilla” but it is significantly faster to make a database backup of the AX database and model database without your code present and then restore these.  It was taking me 5-20 minutes to delete models and 90-150 minutes to recompile and resync everything.  It generally takes me 2-5 minutes to restore the 2 databases.

The Restore-AXDatabase function takes between 2-6 parameters:

  • ServerInstance (Server and SQL instance where the DB is located.  Defaults to the local default instance.)
  • AXDBName (Name of the database to be restored.)
  • BackupFilePath (The backup file to be restored.)
  • AdditionalSQLRestore (This defaults to the values that I use for SQL 2012.  I have added it as a parameter so it could be changed if necessary.)
  • TimeOut (The value defaults to 10 minutes but can be overridden if desired)
  • SMTPServer (SMTP server to use to send the email)
  • MailMsg (Net.Mail.MailMessage object used to send the email)
  • VariablePath (Path to a file used to default the parameters/variables)

This function can be found in Codeplex.  The steps of this function are:

  • Load the variables if a VariablePath parameter is used
  • Set up the SQL command
  • Restore the DB using Invoke-SqlCmd
  • Send the success/fail message

There is some setup that needs to be done to use this function.  The first thing necessary it to load the PowerShell module that contains it.  I wrestled with adding this to the function itself but decided against it.  The reasoning is that if you are using an earlier version of SQL Server than 2012, you need to load the SQL PowerShell Snap-ins vs loading the module.

LoadSQLModule

I have added 3 lines to my profile to accomplish this.  The first and third line are added to make up for a side effect of loading the SQLPS module, it changes your location in PowerShell.  The Push-Location cmdlet pops your location onto a stack and the Pop-Location cmdlet retrieves it.  This allows you to load the SQLPS module without changing your location.

The other step that you will need to do is to get your build environment cleaned up and create backups of the AX database and the model database.  You are going to want to have only the models that aren’t part of your build installed in AX.  In my case, this would be my SYS, SYP, ISV & ISP layers.  I only have a single custom model in my VAR layer that I build.  I compile the AOT, IL and sync the database to make sure everything is ready.  I then take a backup of both my AX database and my model database.  Now I can restore both databases and use my Clean-AXArtifacts custom Powershell function to clean up all of the compiled IL and when I start my AOS back up, I have a working “vanilla” instance of AX for my build.

Sync-AXTFSWorkingFolder custom PowerShell function

04 Thursday Jun 2015

Posted by in Powershell

≈ 2 Comments

Tags

, , , , , , , ,

I apologize for missing a post last week.  The combination of a new home and a very busy work week, destroyed any possibility of getting a post out.  The Sync-AXTFSWorkingFolder function is one of 2 Team Foundation Server functions that I have for getting AX code.  This one is a lot less versatile than my other one but it is much more practical for a build process because it is light years faster.  We will explore my other function in a later post.

This function requires a little setup in your PowerShell profile.  The function needs to know the location of TF.exe and I handle this by adding it to the $env:path variable in my PowerShell profile.  There are many ways to solve this problem, this is just the one I’ve chosen.  TF.exe is available when you install Team Explorer for Visual Studio.  You should match your version of Team Explorer to the version of TFS that you are using.

The Sync-AXTFSWorkingFolder function takes between 1 and 6 parameters:

  • WorkingFolder (The working folder to sync from TFS)
  • Label (This value is used if you want to sync a label version instead of the current version)
  • SetLabel (Switch parameter that will allow you to label the current version if a unique Label parameter is passed with it)
  • LabelScope (Allows you to restrict the scope of the label in case there are multiple locations with the same label)
  • Comment (Allows you to set a comment on the label)
  • VariablePath (Path to a file used to default the parameters/variables)

This function can be found in Codeplex.  The steps of this function are:

  • Load the variables if a VariablePath parameter is used
  • Determine if a label was passed in
  • If so, set up the version and Label/LabelScope
  • Determine if the label exists in TFS
  • If so, sync the working folder with the label version
  • If not, get the current version and determine if the label needs to be set in TFS and set it
  • If no label is passed, sync the working folder with the current version
  • Send the success/fail message

This function assumes certain things.  It assumes that Visual Studio is installed with Team Explorer on the local computer.  It assumes that the user running the function has the working folder set up on the computer that the function is being run on.  It assumes that the user has permissions to read and set labels in TFS.  Lastly, it assumes that the path to TF.exe is known.  I also only run this function on my DevBuild server.  While this server has Team Explorer installed and configured with a working folder, my DevBuild AX environment is not connected to TFS.  Because of how AX natively works with TFS, I would not recommend running this function on a working folder that is used by AX as it could cause your AX instance to become out of sync with TFS.

Import-AXLabelFile custom PowerShell function

21 Thursday May 2015

Posted by in Powershell

≈ 2 Comments

Tags

, , , , , , , , ,

The Import-AXLabelFile PowerShell function allows you to import an AX label file into an environment.  While getting this function ready for the post, I realized that I had made a mistake in an earlier post.  My current build process was built to handle one layer and one model.  That was all I needed at the time and I had a limited amount of time to get it up and running.  It was always my plan to make this more generic however and to do that I needed to make my functions and build process able to work for multiple layers and models.  This required a few changes.

I needed a way to support what model is opened in AX for both this function and the Import-AXXPO function.  I have done that using the Model parameter.  Using the ConfigFile parameter to control layer and the Model file to control the model in that layer, individual calls have the ability to control the startup model versus using the “Startup model” system parameter that I had been using.  I have updated both the Start-AXAutoRun and Import-AXXPO functions to support this parameter as well as the blog posts regarding these functions.

The Start-AXAutoRun function takes between 5 and 8 parameters

  • ConfigPath (Client configuration for the chosen AX environment)
  • Model (The AX model to open in)
  • LabelFile (The label file to import)
  • Timeout (The value defaults to 10 minutes but can be overridden if desired)
  • SMTPServer (SMTP server to use to send the email)
  • MailMsg (Net.Mail.MailMessage object used to send the email)
  • AXVersion (The AX version.  It defaults to 6.)
  • VariablePath (Path to a file used to default the parameters/variables)

This function can be found in Codeplex.  The steps of this function are:

  • Load the variables if a VariablePath parameter is used
  • Validate the LabelFile parameter location
  • Start the AX client using the aldimport startup command
  • Wait for the timeout period for the AX client to exit
  • Send the success/fail message

This function is extremely similar to the Start-AXAutoRun function.  There are multiple commands to use to start AX and while AutoRun can do multiple things, it can’t import label files.  It is possible to reduce code duplication by dropping the Start-AXAutoRun function and replacing it with a very similar function that takes a command parameter for the AX -startupcmd parameter but I haven’t done that yet.  I hadn’t previously had a function for importing label files.  I was just doing this with a few lines of code in my build process.  Just one of the perils of building this weekly in my spare time.  Optimization through iteration.

Import-AXXPO custom PowerShell function

12 Tuesday May 2015

Posted by in Powershell

≈ 3 Comments

Tags

, , , , , , , ,

The Import-AXXPO custom PowerShell function allows you to automate the importing of .xpo files.  It is going to look very familiar to people who have read some of my other functions as it follows the same format as Compile-AXCIL and Sync-AXDB.

The Import-AXXPO function takes between 2 and 9 parameters:

  • ConfigPath (Client configuration for the chosen AX environment)
  • LogFile (The value defaults to the temp folder but can be overridden if desired)
  • TimeOut (The value defaults to 20 minutes but can be overridden if desired)
  • ImportFile (The .xpo file to import)
  • Model (The AX model to open in)
  • SMTPServer (SMTP server to use to send the email)
  • MailMsg (Net.Mail.MailMessage object used to send the email)
  • AXVersion (The AX version.  It defaults to 6.)
  • VariablePath (Path to a file used to default the parameters/variables)

I use the VariablePath parameter the same way that I do in the other functions I’ve posted that use it.  This function can be found in Codeplex.  The steps of this function are:

  • Load the variables if a VariablePath parameter is used
  • Validate the ImportFile parameter location
  • Get the AX environment info using Get-AXConfig
  • Get the CompileIL AX AutoRun xml using the Get-AXAutoRunXML function
  • Call the Start-AXAutoRun function to import the .xpo

Some things to consider with this function.  Where an .xpo is imported is controlled by 3 things.  The configuration file used to open AX will control what layer the .xpo is imported into.  The model is controlled by either the Model parameter or the user option “Startup model” (Tools -> Options -> Development -> Startup model).  This value is stored per user and per layer so make sure you have this value set up in every AX environment that you will be importing .xpos in if you don’t use the Model parameter.

This function should also only be run on the AOS server.  It has been tested using AX 2012 R2 CU7 but should also work for R3.

Clean-AXArtifacts custom PowerShell function

04 Monday May 2015

Posted by in Powershell

≈ 4 Comments

Tags

, , , , , ,

I apologize for missing last week’s post but I’m in the process of moving and my free time has all but gone away.  I discovered the idea for this PowerShell function from a couple of different places.  I first saw the concept of cleaning up “artifact” files in the Build and Deploy Scripts for Microsoft Dynamics AX but I found it much more detailed in the Dynamics AX Admin Utilities.  I was interested in this because I missed the “default fix” that was deleting the application object index in earlier versions of AX.  This isn’t quite the same but it does remove the files that AX generates and stores on the client and server, forcing AX to re-deploy them from code.

The Clean-AXArtifacts function takes between 0 and 3 parameters:

  • ConfigPath (Client configuration for the chosen environment)
  • CleanServer (Switch parameter used to clean artifact files on the server)
  • AllUsers (Switch parameter used to clean artifact files for all users on the client instead of just the current user)

The ConfigPath parameter is only required if the CleanServer parameter is used.  The CleanServer parameter will stop the AOS (if it’s running), delete the server artifacts and start the AOS (if it was stopped by the function earlier).  AllUsers is good for terminal server client servers.  It will allow you to delete the client artifacts for all users that log onto that terminal server.

This function can be found in Codeplex.  This function also uses 2 internal functions that I’ve created, Clean-Folder and Clean-Folders.  These functions allow me to loop through the folders and delete the files.  The steps of this function are:

  • Validate parameters
  • Check if the server needs to be cleaned
    • Get the AX environment info using Get-AXConfig
    • Stop the AOS if it’s running
    • Delete the server artifact files using Clean-Folder
    • Start the AOS if it was stopped by the function
  • Check if all users need to be cleaned
  • Use Clean-Folders for all users or Clean-Folder if not

I use this function during builds and also during pushes.  When I have an environment that has more than one AOS, I generally stop the AOS on the other AOS’s, then run Clean-AXArtifacts on the primary AOS.  While it is running, I log onto the other AOS’s and run the function there.  I also log onto the client terminal server and delete the client artifacts for all users.  When the primary AOS has started again, I start the AOS’s on the other AOS servers.  This function has become my default AOS bounce.  Instead of restarting the AOS, I call Clean-AXArtifacts.

Like all of my other functions, this must be run on the server that you are deleting files on.

Compile-AXAOT custom PowerShell function

20 Monday Apr 2015

Posted by in Powershell

≈ 1 Comment

Tags

, , , , , , , ,

The Compile-AXAOT custom PowerShell function will allow you to compile the AOT using the client compile.  I would recommend using the Start-AXBuildCompile function that uses the server compile if you are on AX 2012 R2 CU7 or higher as this function will compile much faster but this one will accomplish the same thing if you aren’t.

The Compile-AXAOT function takes between 1 and 6 parameters:

  • ConfigPath (Client configuration for the chosen AX environment)
  • TimeOut (The value defaults to 2 hours but can be overridden if desired)
  • SMTPServer (SMTP server to use to send the email)
  • MailMsg (Net.Mail.MailMessage object used to send the email)
  • AXVersion (The AX version.  It defaults to 6.)
  • VariablePath (Path to a file used to default the parameters/variables)

You might notice that this function doesn’t take a LogFile parameter.  That is because the client compile stores the log file in specific location and changing that value would not allow you to receive the compile log.  This function can be found in Codeplex.  The steps of this function are:

  • Load the variables if a VariablePath parameter is used
  • Get the AX environment info using Get-AXConfig
  • Get the CompileApplication AX AutoRun xml using the Get-AXAutoRunXML function
  • Call the Start-AXAutoRun function to compile the AOT

This function should also only be run on the AOS server.  It has been tested using AX 2012 R2 CU6 and CU7 but I would expect this to work for any version of AX 2012.

Start-AXAutoRun custom PowerShell function

20 Monday Apr 2015

Posted by in Powershell

≈ 1 Comment

Tags

, , , , , ,

This blog post is an extra this week.  In my last blog post, I discussed my desire to clean up the duplicate code in my functions that were calling the AXAutoRun process.  This function is putting that duplicate code into a single function that my other functions will call.  I will update the code and blog posts to reflect this change.  I apologize for the changes but these functions are a work in progress.  I have been using them for over a year but one of the main reasons I wanted to blog about them was so I could clean them up and package them for others.

The Start-AXAutoRun function takes between 5 and 8 parameters

  • Ax (The PSObject returned from the Get-AXConfig DynamicsAXCommunity function)
  • Model (The AX model to open in)
  • XMLFile (The xml generated from the Get-AXAutoRunXML function)
  • LogFile (The location of the log file)
  • Process (A description of the process being run that is used for notifications)
  • Timeout (The timeout value for the process in seconds)
  • SMTPServer (SMTP server to use to send the email)
  • MailMsg (Net.Mail.MailMessage object used to send the email)

This function can be found in Codeplex.  The steps of this function are:

  • Start the AX client using the AutoRun xml
  • Wait for the timeout period for the AX client to exit
  • Send the success/fail message

The first 5 parameters are required.  The last 2 are only necessary for emailing the results.  I’m not expecting that most users would be using this function as it is intended to be an internal function used by my custom functions that call AXAutoRun.  Using this in hand with Get-AXAutoRunXML would allow you to build any custom AXAutoRun functions that you would like however.

Sync-AXDB custom PowerShell function

12 Sunday Apr 2015

Posted by in Powershell

≈ 3 Comments

Tags

, , , , , , , , ,

The Sync-AXDB custom PowerShell function will allow you to synchronize the AX DataDictionary from PowerShell.  If you compare this function/post against the Compile-AXCIL function/post, you will see that they are almost identical.  I had thought of creating a single Start-AXAutoRun function but eventually scrapped that idea in favor of simplicity for the user.  I may look at creating an internal function for the AX call at some point in the future to remove the code duplication.

The Sync-AXDB function takes between 1 and 7 parameters:

  • ConfigPath (Client configuration for the chosen AX environment)
  • LogFile (The value defaults to the temp folder but can be overridden if desired)
  • TimeOut (The value defaults to 2 hours but can be overridden if desired)
  • SMTPServer (SMTP server to use to send the email)
  • MailMsg (Net.Mail.MailMessage object used to send the email)
  • AXVersion (The AX version.  It defaults to 6.)
  • VariablePath (Path to a file used to default the parameters/variables)

I use the VariablePath parameter the same way that I do in the other functions I’ve posted that use it.  This function can be found in Codeplex.  The steps of this function are:

  • Load the variables if a VariablePath parameter is used
  • Get the AX environment info using Get-AXConfig
  • Get the Synchronize AX AutoRun xml using the Get-AXAutoRunXML function
  • Call the Start-AXAutoRun function to synchronize the database

This function should also only be run on the AOS server.  It has been tested using AX 2012 R2 CU7 but should also work for R3.  I have added the Version parameter to this function but it was initially missing from the Compile-AXCIL function/post.  I have gone back and added it to the earlier post as well to reflect the code change in TFS.