Tuesday, November 7, 2017

Duplicating a Microsoft Dexterity window on the same form - Part 2/2

In Part 1 of this two-part article, I showed a method using Dexterity Utilities to duplicate a window on the same form. As I also explained, this method is good and, in fact, highly recommended for windows where you have a small amount of fields and window event scripts since the method calls for renaming all of these scripts to match the renamed window.

If you have a more complex window, then perhaps you will want to follow this method:

Method 2 - Manipulating Form Resource File

This method allows you to use the magic of copy/paste and search/replace to quickly duplicate a window within a form. The following steps should get you there:

1. Launch Microsoft Dexterity IDE and open your development dictionary. 

2. Highlight the form resource containing the window you want to duplicate. Highlight the form and click the Export to Text File button the Resource Explorer toolbar.


3. In the Export to Text File window, click OK to perform the export. 


NOTE: The default export path will be where your development dictionary resides.

4. Open the exported form resource file in a text editor and locate the Windows section of the file. Highlight the section corresponding to the window you want to duplicate and copy/paste into a new Notepad window.


5. In the new text editor window, find all occurrences of the window name, and replace with the new name.


Once you've replaced all window name occurrences, scroll to the very bottom of the text editor and locate the Position property. Replace this number with a value of plus 1 the number of windows on the form, i.e., if the form has 1 window, then the new Position for your duplicated window will be 2, if the form has 5 windows, then the new Position will be 6, etc.

6. Copy/paste the replaced content back to the original text editor containing the form resource definition. You will scroll to the bottom of the last Window definition in the file and paste from the clipboard. 


7. Scroll down to the ~EventScripts section, then highlight and copy all EventScripts within that section out to a new window in your text editor. 


8. Paste the copied event scripts into a new text editor window and search the old window name and replace with the window name in all scripts.


9. Copy the content from the new text editor window back into the form resource file. Locate the last EventScript entry within the ~EventScript section and paste there.


10. Finally, save and re-import the form resource file back into your development dictionary. You should now see the duplicated window in the form.

I hope you enjoyed these two methods of duplicating windows within the same form and find it useful in your future projects.

Until next post!

MG.-
Mariano Gomez, MVP

Monday, November 6, 2017

Duplicating a Microsoft Dexterity window on the same form - Part 1/2

Just today, I was trying to solve a problem that at first seemed very simple: I needed to duplicate a Microsoft Dexterity window on the same form.

Background

To provide some context, I have a Dexterity form which hosts a modal window that needs to be displayed in middle of a process - we will call this window, window B of form B. Form B implements an OpenWindow form script that serves as an API to any calling script. The OpenWindow scripts implements a parameter that allows the modal window to either wait for user input or continue processing automatically (that is, without user input), which in turn would close the modal window (and the form) upon completion of all processes executed by the OpenWindow script.

To make matters more interesting, one of the callers happen to be a script on another modal window in another form - we will call this window, window A of form A. Now, when this code (and process) is performed from the Microsoft Dynamics GP desktop client, everything occurs as expected: the field script on window A of form A executes its processes, then calls OpenWindow of form B (in background) and closes. OpenWindow of form B opens window B, executes its processes and closes form B.

When this code is executed under Microsoft Dynamics GP web client, form A with modal window A executes its processes, and although a call to OpenWindow of form B is performed, the modal window on form B never displays because the modal window A of form A never closes.

As it turns out, both the Silverlight (GP 2013/GP 2015) and HTML 5 (GP 2016 and above) web clients have a strict platform implementation for modal windows, this is, they can only be dismissed by user interaction, and not by code - the Dexterity close window button is also disabled for obvious reasons.

So what can a Dexterity developer do if they need to implement a code driven modal window for the web client? Well, you can turn to a mode-less window or a primary window, if needed.


So now the question becomes, how do you duplicate the window on the same form? There are a couple methods you can use to do this:

Method 1 - Dexterity Utilities

1. Create a copy of your development dictionary.



2. Launch the Dexterity IDE. Open the copy of the development dictionary and rename the desired window in the target form. Since I want my window type to be a Modeless Dialog, I change the name to reflect that by adding _ML at the end of the name, and update the actual Window Type property.



NOTE: Once you rename the window, you will want to update all field and window level event scripts to match the new window name.

3. Launch Dexterity Utilities. Open the copy development dictionary as your source and the primary development as your destination.



4. Click the Transfer button on the toolbar and select Window. Locate the renamed window on the desired form and click Transfer.


Enter the name for the transfer report. I strongly suggest you look at the report for any errors.


NOTE: You are *not* presented with a destination form. This is because Dexterity Utilities will transfer the window to a form of the same name in the destination dictionary.

Close Dexterity Utilities.

5. Launch Microsoft Dexterity IDE and open your primary development dictionary. Open the form and now you will see that the Modeless Dialog window is now a part of the form.


You can now compile the form (and the entire dictionary at some point) to ensure all your scripts compile properly and without any errors.

Final thoughts for this method:

1. Since all field event scripts on the window have the same code, consider moving the code in these fields to form level procedures and functions where appropriate. This will ensure any code fixes and expansion is done in one place.

2. I feel this method works well for windows with a very low amount of field scripts. If you have more complex windows to duplicate, then this method becomes a bit more involved, since renaming all field and window level event scripts could be a challenge.

3. This method works to duplicate any window of any window type on the same form.

Tomorrow, I will present a second method that may prove more effective to duplicate windows on the same form, especially for windows with a significant amount of field and window level scripts.

Until next post!

MG.-
Mariano Gomez, MVP

Tuesday, September 26, 2017

Microsoft Dynamics GP Security and Audit Field Manual

My friends, MVP Mark Polino (@mpolino) and Andy Snook (@snookgofast), both members of the Fastpath team, have just released a comprehensive security book titled, Microsoft Dynamics GP Security and Audit Field Manual.

The book can be found in printed and Kindle formats on Amazon.com and I encourage you to get a copy, read up, and put into practice as this book goes beyond the boring task of assigning security to windows and reports just to prevent someone from accessing some area of the application, and into the realms of compliance, separation of duties, and audit controls.


The book can be found in printed and Kindle formats on Amazon.com and I encourage you to get a copy, read up, and put into practice as this book goes beyond the boring task of assigning security to windows and reports just to prevent someone from accessing some area of the application, and into the realms of compliance, separation of duties, and audit controls.

Finally, I want to take the opportunity to thank both Mark and Andy for extending me an invitation to write the foreword to their book. 

Until next post!

MG.-
Mariano Gomez, MVP

#DevOps Series: Building Dexterity Applications with Visual Studio Team Services - Summary





My DevOps series has concluded, although, I believe this will not be the first or the last time I write about this subject. DevOps is here to stay and the tools and technologies to support development teams only keep getting better.

The following is a list of the topics I covered in the series and I encourage you to add your comments to the comment section of the posts that caught your attention. Let me know what you are doing today and how you plan to incorporate DevOps into your development operation processes.

July 17 - #DevOps Series: Microsoft Dexterity Source Code Control with Visual Studio Team Services

July 17 - #DevOps Series: Upgrading Microsoft Dexterity VSS and TFS repositories to Visual Studio Team Services - Part 1/2

July 19 - #DevOps Series: Upgrading Microsoft Dexterity VSS and TFS repositories to Visual Studio Team Services - Part 2/2

Aug 01 - #DevOps Series: Building Dexterity Applications with Visual Studio Team Services Part 1/3

Aug 16 - #DevOps Series: Building Dexterity Applications with Visual Studio Team Services Part 2/3

Sep 25 - #DevOps Series: Building Dexterity Applications with Visual Studio Team Services Part 3/3


I also prepared this video, which I originally intended to add to the previous article, but I am really glad I left it for the summary post. Please be sure to check it out (better viewed in full screen mode).



A link to the Helper.ps1 script containing the library of functions used by the PowerShell scripts found in the previous article can be download from my OneDrive public share, here. These scripts are being updated constantly as we evolve our Build-Engine. Check back for additional updates.

Until next post!

MG.-
Mariano Gomez, MVP

Monday, September 25, 2017

#DevOps Series: Building Dexterity Applications with Visual Studio Team Services Part 3/3

In part 2 of this series, I covered how to setup a Build Definition of for our Build-Engine project. I also began showing the steps required by the Build-Engine definition in order to take your development project from the dictionary to an actual set of extracted dictionaries and chunk files that can be delivered to your QA team.

NOTE: the same process can be used to take your dictionaries from QA to release to your download site.

The first step, as shown before, is to determine the source for the Build-Engine process. We said that we would use the Build-Engine project itself as source for the Build process, since it contains all our Dexterity (and Dexterity Utilities) files, PowerShell scripts, and macros to make it all happen.


1. Following the selection of the source, our first task is to create the necessary folders to host the various files. This tasks uses an inline PowerShell to do this:

CreateFolders (inline PS script)
$folders = @("Build", "Source", "Logs", "Generic", "Temp")  # Create these folders

foreach($item in $folders)
{
    mkdir "$(Get-Location)\$($item)\" -ErrorAction SilentlyContinue | Out-NULL
}

The task creates the following folders:

Build: stores chunk files with no source code

Source: stores the extracted dictionaries and chunk files

Logs: stores all the log files generated by Dexterity Utilities in the process of extracting and chunking dictionaries

Generic: stores the downloaded Dexterity project repository files

Temp: stores any additional component needed throughout the Build process

2. Once we have set up the needed folders, we can then proceed to retrieve our Dexterity project from the VSTS repository. For this purposes, we setup a task that will run our Get_VSTS.ps1 PowerShell script.

Get_VSTS.ps1
Param(
    [string]$SingleModule = "",
    [int]$BuildNumber,
    [string]$VSTSUser,
    [string]$VSTSUserPAToken, 
    [switch]$TestStructure
)

. "$(Get-Location)\Scripts\Helper.ps1"

$modules = Get-ModuleData -Module $SingleModule
if ($modules.Status -ne 0) { 
    Write-Host "Invalid Module : $($SingleModule)" -ForegroundColor Red
    exit 
}

$sourceModule = $modules.SourceFolder
Write-Host "Pulling Module : $($modules.Selected)" -ForegroundColor Green 

# ==============================
# Retrieve source files to pull.
# ==============================
$baseWebFolder = "$/MICR/Base/2/2015B$($BuildNumber)/"
$SourceCodeFolder = "$($baseWebFolder)/$($sourceModule)" # Where to pull from.
$genericFolder = "$(Get-Location)\Generic\" # Where to push files to.

$scopePath_Escaped = [uri]::EscapeDataString($SourceCodeFolder) # Need to have this in 'escaped' form.

Write-Host "`tfrom $($SourceCodeFolder)`n`tinto $($genericFolder)`n"

$recursion = 'Full' # OneLevel or Full
#$recursion = 'OneLevel' # or Full
 
# Base64-encodes the Personal Access Token (PAT) appropriately
$base64AuthInfo = [Convert]::ToBase64String([Text.Encoding]::ASCII.GetBytes(("{0}:{1}" -f $VSTSUser, $VSTSUserPAToken)))
 
# Construct the REST URL to obtain the MetaData for the folders / files.
$uri = "https://somedomain.visualstudio.com/DefaultCollection/_apis/tfvc/items?scopePath=$($scopePath_Escaped)&recursionLevel=$($recursion)&api-version=2.2"

# Invoke the REST call and capture the results
$result = $null
$result = Invoke-RestMethod -Uri $uri -Method Get -ContentType "application/json" -Headers @{Authorization=("Basic $($base64AuthInfo)")}

# This call returns the METADATA for the folder and files. No File contents are included.
if ($result.count -eq 0)
{
     throw "Unable to locate code at $($SourceCodeFolder)"
}
$result

# ==============================================
# Create folder structure and sort file objects.
# ==============================================
$script:startTime = Get-Date
$sortedFiles = New-Object 'System.Collections.Generic.SortedDictionary[string, string]'

$_removeLength = $baseWebFolder.Length
for($index=0; $index -lt $result.count; $index++)
{
#    $_path = $result.value[$index].path.substring($_removeLength)
    $_path = "$($genericFolder)$($result.value[$index].path.substring($_removeLength))" -replace "/", "\"
    if ($result.value[$index].isFolder -eq $true) 
    { 
        Write-Host "`t$($_path)" # -BackgroundColor Blue -ForegroundColor Yellow
        New-Item -Force -ItemType directory -Path $_path  | Out-Null
    }
    else
    {
        $sortedFiles[$_path] = $result.value[$index].url
    }
}

# =======================================================
# Create a runspace pool where $maxConcurrentJobs is the 
# maximum number of runspaces allowed to run concurrently    
# =======================================================
$script:maxConcurrentJobs = 10
$script:asyncObj = $null
$Runspace = [runspacefactory]::CreateRunspacePool(1,$script:maxConcurrentJobs)

# Open the runspace pool (very important)
$Runspace.Open()

#$script:Authorization = @{Authorization=("Basic {0}" -f $base64AuthInfo)}
$script:Authorization = @{Authorization=("Basic $($base64AuthInfo)")}
$SortedFiles.GetEnumerator() | foreach {
    # Create a new PowerShell instance and tell it to execute in our runspace pool
    $ps = [powershell]::Create()
    $ps.RunspacePool = $Runspace

    # Base command to 'BeginInvoke'
    # Invoke-RestMethod -Uri $using:remote -Method Get -ContentType "application/json" -Headers @{Authorization=("Basic {0}" -f $using:base64AuthInfo)} -OutFile $using:local 

    [void]$ps.AddCommand("Invoke-RestMethod")
    [void]$ps.AddParameter("OutFile",$_.Key)
    [void]$ps.AddParameter("Uri",$_.value)
    [void]$ps.AddParameter("Method","Get")
    [void]$ps.AddParameter("ContentType", "application/json")
    [void]$ps.AddParameter("Headers", $script:Authorization)

    # Begin execution asynchronously (returns immediately)
    $script:asyncObj = $ps.BeginInvoke() 
}

# ==========================================
## Run the parallel processes to completion.
# ==========================================
if ($script:asyncObj -eq $null) {}
else {
    Write-Host "Pulling $($SortedFiles.Count) code files..."
    while ($script:asyncObj.IsCompleted -eq $false) {}
    Write-Host "`tTime elapsed to pull code: $((Get-Date) - $($script:startTime))"
}

# ================================================
## Change MPP to MMM. Simplifies later processing.
# ================================================
Push-Location $($genericFolder) #Generic 
if (Test-Path "$($genericFolder)\MPP" -PathType Any)
{
    Remove-Item -Path "MMM" -Recurse -ErrorAction SilentlyContinue | Out-Null ## Remove any previous MMM code.
    Rename-Item -path "MPP" -NewName "MMM" 
}
Pop-Location ## Back to where the code was.

This script accepts 5 parameters: the module code (we support 5 products currently) which is validated to prevent an empty parameter from being passed. If we pass in "All", all products will be built; the repository user and personal access token, and a parameter to test the folder structure once it's created. These parameters are passed in by the actual Build definition step.

To retrieve the source files, we construct the service URI and also determine where the files are going to be deposited once retrieved. This is determined by the setting up a relative path to the Generic folder we created in step 1.

Once we connect to the service, we begin retrieving the files by using a for() control structure. There are some other steps that are only relevant to the environment for which this Build process has been designed.

3. Upon retrieving the files from the Dexterity project repository, we are now ready to setup module environment variables and compile the dictionaries, in preparation for the extraction and chunking process.

SetupModuleEnvironment.ps1
Param(
   [int] $VersionNumber,
   [int] $BuildNumber = "000",
   [int] $SubBuildNumber = "0",
   [string] $SingleModule = $null
)

. "$(Get-Location)\Scripts\Helper.ps1"

# Create the folder structures
$folders = Create-FoldersCommands -Version $VersionNumber -Module $SingleModule
Write-Host "Creating Folders:"
foreach ($item in $folders) {
    Write-Host "`t$($item.Folder)"
    mkdir $item.Folder -ErrorAction SilentlyContinue | Out-Null
}


# Copy the files, with replacement of text in text files.
# Ensure the files are saved as 'ASCII'.
$files = Copy-FilesCommands -Version $VersionNumber -Module $SingleModule -BuildNumber $BuildNumber -SubBuildNumber $SubBuildNumber
Write-Host "Copying Files:"
foreach ($item in $files) {
    Write-Host "`tFrom`t$($item.From)"
    Write-Host "`tTo`t`t$($item.To)"
 copy $($item.From) $($item.To)
    Set-ItemProperty $item.To IsReadOnly -value $false

    if ($item.Replacements -ne $null){
        $item.Replacements.psobject.properties | 
        foreach { 
            $_name = "%$($_.name)%"  # The name of the parameter is the text to be replaced, surrounded by '%'
            $_value = "$($_.value)"

            (Get-Content $item.To) -replace $_name,$_value | Set-Content $item.To -Encoding Ascii 
        }
    }
}

Of particular importance is the fact that we use a PowerShell helper script (Helper.ps1) which contains a number of functions that capitalize on the parameters passed here. The general idea, nonetheless, is to make a number of replacements within the macros that assign product information and build numbers, taking into account the version number of Microsoft Dynamics GP for which we will be creating the chunks; and create the shortcuts for Dexterity and Dexterity Utilities to compile and extract the dictionaries, using the proper dictionaries and macros that will run when the Dex platform executables are launched.

In the closing post, summarizing all the articles within this series, I will attach a copy of the Helper.ps1 script.

4. Upon making these replacements and compiling the dictionaries, we can then proceed to extract and chunk our dictionaries.

ChunkDictionaries.ps1
Param(
   [int] $VersionNumber,
   [string] $SingleModule = $null
)
. "$(Get-Location)\Scripts\Helper.ps1"

$EXEx = Create-ExecutableCommands -Version $VersionNumber -Module $SingleModule
Write-Host "Building..."
foreach ($item in $EXEx) {
    Write-Host "$($item.Version)`t$($item.Module)`t$($item.Message)`t" -NoNewline
    Write-Host "`n`t$($item.Executable) : $($item.Timeout) seconds Max.`n`t$($item.Dictionary)`n`t$($item.Macro)`t"

<##>
    # keep track of timeout event
    $timeouted = $null # reset any previously set timeout
    $proc = Start-Process -filePath $item.Executable -ArgumentList @($item.Dictionary, $item.Macro)  -PassThru
    # wait up to x seconds for normal termination
    $proc | Wait-Process -Timeout $item.Timeout -ea 0 -ev timeouted
<##>
    $msg = "Finished."

    if ($timeouted)
    {
        # terminate the process
        $msg = "Time Out!!"
        $proc | kill
    }
    elseif ($proc.ExitCode -ne 0)
    {
        # update internal error counter
        $msg = "Error: $($proc.ExitCode)."
    }
    
    Write-Host "`t$($msg)"
}

Once again, this script takes advantage of the PowerShell helper script library to extract the source code from the development dictionaries and auto-chunk the extracted dictionaries. Note that this script takes in the version of GP to determine the proper version of Dexterity and Dexterity Utilities to launch. This process is completed twice: once for chunks with source (Remove Unused Block in Dexterity Utilities Auto-Chunk option) and another for chunks without source (Total Compression). The source chunks are moved to the Source folder on the Build agent and the object chunks are moved to the Build folder on the Build agent.

NOTE: the Source and Build folders are created by the CreateFolders inline PowerShell script in task 1 above.

5. Upon finalizing the extraction and chunking process of the dictionaries, we move the chunk files with no source code (Total Compression chunks) to the Build sub-folder in the artifacts directory. The artifacts folder is where all resulting files will be stored after the process itself is complete.

Copy Build Artifacts step

6. Then we move the chunks and extracted dictionaries with source code to the Source sub-folder in the artifacts directory.

Copy Source Artifacts
The following Microsoft Docs article talks about Artifacts in Release Management in more detail.

7. Finally, since the Build Agent is volatile, you will need to move the artifacts off the agent and onto a permanent storage location, whether that's on the VSTS servers or a local folder. This is accomplished by publishing the artifacts.

Publish Build Artifacts

My final article in this series will summarize the series and provide links to all previous articles, along with providing a link to the Helper.ps1 PowerShell library.

Until next post!

MG.-
Mariano Gomez, MVP

Wednesday, August 16, 2017

#DevOps Series: Building Dexterity Applications with Visual Studio Team Services Part 2/3

I am so amped-up after my return from the Microsoft Dynamics GP Technical Conference 2017 in Fargo, ND, where I had a chance to catch up with my friends in the partner and ISV community (more on that in a later post). This year, I had a chance to introduce the topics I have been discussing here in my DevOps series and now that I am back, I want to continue writing about the subject as it gets more and more exciting.

In Part 1 of this specific chapter within the series, I talked about building the actual Build-Engine project. If you remember, I specifically said that the build templates provided by Visual Studio Team Services (VSTS) do not fit the bill for Dexterity projects. Dex projects tend to be a bit more cumbersome since we need to have the entire IDE around to compile, extract, and chunk our products. So, it's best if we can isolate these components into an altogether separate project (from that of our actual Dex product) for clarity sake and to maintain our own sanity.


Creating a Build Definition for your Build-Engine Project

Now that we have the Build-Engine project in place, we can proceed to setup a Build Definition. The Build Definition is going to encompass all of the steps required to do things like:

1. Download the resources from our Build-Engine project (Dex IDEs, clean dictionaries, PowerShell scripts, macro templates, etc.

2. Setup any folders needed to support the build process and temporarily store files, etc.

3. Pull the source code from our Dexterity project repository

4. Setup all environment variables

5. Extract dictionaries and create chunk files with (unused blocks) and without source code (total compression).

6. Copy the chunks without source code into an artifact folder

7. Copy chunks and source dictionaries for debugging into an artifact folder

8. Publish the artifact folder

To create a new build for our Build-Engine project:

1. Click on the Build & Release then click the New button.


2. Select an empty template. Dexterity projects, clearly do not conform to any of the existing, pre-defined molds.


3. Click the Apply button to continue.

4. You can now enter the name of your Build-Engine and select from a list of 4 agent queue modes. You can select from Default, Hosted, Hosted Linux Preview, or Hosted VS2017. For all intends and purposes, hosted build agents pools run in the cloud, but can run locally as well. For more information on Hosted Agents, click here. These options define the Build process itself.


The suited option for our Dexterity Build-Engine is Hosted.

5. On the left pane, we can now click on the first task, Get Sources, to identify where the resources for our Build-Engine will come from. In this case, they will come from our Build-Engine project itself, which contains the Dexterity IDEs for versions 12 (GP 2013), 14 (GP 2015), and 16 (GP 2016). All other options are defaulted and really not required to be changed.



This completes the first step (Download Resources for our Build Engine) for today. You can click on Save & Queue to test that all files download properly for the build agent pool.



NOTE: My agent failed in the video as I ran out of allocated build minutes for the month. You will need to assess the length of your build process and ensure you plan accordingly. For more information on Team Services pricing, click here.

I strongly encourage you to read MVP David Musgrave's series on Building a Dexterity Development environment, because all principles used in that series are still applicable in our cloud Build-Engine.

Until next post!

MG.-
Mariano Gomez, MVP

Tuesday, August 1, 2017

#DevOps Series: Building Dexterity Applications with Visual Studio Team Services Part 1/3

Resuming my series, I wanted to touch base on the process of building and releasing Dexterity applications with Visual Studio Team services. My friend and fellow MVP, David Musgrave explained how to setup your Dexterity development environment in his Dexterity Development series and the first article in this series directly addressed the source code control process. Although David showed some really clever methods to build and package your Dexterity chunk application, that process still has some downsides to it. Primarily, the process is dependent on a person and a physical machine dedicated to executing the process.

Setting up a Build Engine

When creating a self-contained cloud-based VSTS Build Engine for your Dexterity projects, there are a few considerations:

1. The actual Dexterity IDE. If you are building a Dexterity chunk, you need to at least have a copy of the Dexterity IDE, because you will want to compile your project dictionary prior to chunking, and the chunking process itself still relies on Dexterity Utilities to be able to produce a chunk file.

In addition, you will need as many IDEs as versions of Dynamics GP you are supporting with your product. David describes this well in Part 2 of his series.

2. You need clean (base) dictionaries of each Dynamics GP versions you will be supporting. This is particularly important as you will want to pull the source code from the repository into clean dictionaries to compile and obtain your extracted dictionaries and finally complete the auto-chunk process.

3. Since your build process will ultimately be automated, you need macros to inject constants and compile the dictionary, based on the version of Dynamics GP your product will be supporting. You will also need macros to extract and auto-chunk your product.

NOTE: You can inject constants into your development dictionary by having a Dexterity constants resource file. Your macro will need to have steps in place to import the constants resource file.

4. You will also need scripts to drive a lot of the processes above, i.e., if you are launching Dexterity with a dictionary and a macro as a parameter to execute an automated task, this needs to be done by some task or step that supports this process. Anything scripting related, is preferable done with PowerShell since it has greater levels of automation over standard DOS batch files.

Now that you understand all the challenges, you can quickly guess that the best way to achieve this in Visual Studio Team Services is by setting up a Build Engine project with all the artifacts needed to automate the process.

The following shows the folder structure of a Build Engine project in VSTS:

Build Engine project structure
An explanation is as follows:

1. The DEX12, DEX14, and DEX16 folders contain full copies of the Dexterity IDE files, less things like samples, help files, and what's not. These are not needed as they will never be accessed.

2. The Logs folder will store any log produced by the macros being executed

3. The Macros folder includes all macros that we will need to compile and extract our code into chunk files.

If your macros refer to files in any of the folders in your Build Engine, these need to be relative to the root of structure of your project structure. In addition, it's easier to inject variables for things like the log paths, the dictionaries, version numbers, etc. It's considered best practice to not hard code any of these elements in your macro files to allow for reusability and customization. The following is an example of a chunking macro file:



# DEXVERSION=%DexMajorVersion%
Logging file '%LogPath%vDexUtilsMEP.log'
# ================================================================================
  MenuSelect title File entry 'Open Source Dictionary...' 
# ================================================================================
  FileOpen file '%ModulePath%/DYNMEP.dic' type 0 
# ================================================================================
ActivateWindow dictionary 'default'  form 'Main Menu' window 'DexUtils Toolbar' 
  MoveTo field 'Toolbar Utilities Button' item 0 
  ClickHit field 'Toolbar Utilities Button' item 6  # 'Extract' 
NewActiveWin dictionary 'default'  form Extractor window Extractor 
ActivateWindow dictionary 'default'  form Extractor window Extractor 
  ClickHit field '(L) Extract Button' 
# ================================================================================
  FileSave file '%ChunkDestination%/%VersionNumber%/MEP7156E.dic' 
# ================================================================================
NewActiveWin dictionary 'default'  form Extractor window Extractor 
NewActiveWin dictionary 'default'  form Extractor window Extractor 
  MenuSelect title File entry 'Close Source Dictionary' 
  MenuSelect title File entry 'Open Editable Dictionary...' 
# ================================================================================
  FileOpen file '%ChunkDestination%/%VersionNumber%/MEP7156E.dic' type 0 
# ================================================================================
ActivateWindow dictionary 'default'  form 'Main Menu' window 'DexUtils Toolbar' 
  ClickHit field 'Toolbar Utilities Button' item 9  # 'Auto-Chunk' 
NewActiveWin dictionary 'default'  form 'Auto Chunk' window 'Auto Chunk' 
ActivateWindow dictionary 'default'  form 'Auto Chunk' window 'Auto Chunk' 
  ClickHit field 'Lookup Button 3' 
# ================================================================================
  FileSave file '%ChunkDestination%/%VersionNumber%/MEP7156.cnk'
# ==================================================================================
  MoveTo field 'Dictionary Name' 
  TypeTo field 'Dictionary Name' , 'MEP7156.DIC'
  MoveTo field 'Dictionary Name' 
  MoveTo field '(L) Major Version' 
  TypeTo field '(L) Major Version' , '%DexMajorVersion%'
  MoveTo field '(L) Build Number' 
  MoveTo field '(L) Minor Version' 
  MoveTo field '(L) Build Number' 
  TypeTo field '(L) Build Number' , '%DexBuildVersion%'
  MoveTo field '(L) Major Version' 
  MoveTo field '(L) Build Number'  




You may be asking how these variables will be updated. Very simple: when we setup the Build process itself, we will create environment variables that can be injected into these macro files. You may also be asking how did these variables get there to begin with? Follow the steps outlined in Part 4 of the Dexterity Development Environment series to create your build macro and once you have recorded the macro, you can edit it to set up the place holders for environment variables.

4. The Resources folder contains things like constants resource files, clean dictionaries, and a Dex.ini file for the Dynamics GP versions that will be supported by your integrating Dexterity application.

5. The Scripts folder contains all the PowerShell scripts required to automate some of the tasks. One of such tasks is the ability to setup the dictionaries for the different products you will be building, as shown in this PowerShell script:

Param(
   [int] $VersionNumber,
   [int] $BuildNumber = "000",
   [int] $SubBuildNumber = "0",
   [string] $SingleModule = $null
)

$dictionary=''
$DexMajorVersion = 0
$localFolder = Get-Location #"$([System.IO.path]::GetPathRoot($(Get-Location)))" 

enum BuildType { 
    Source = 0
    Build = 1
}


switch ($VersionNumber) {
    2013 { 
   $dictionary = "$localFolder\resources\Dyn2013.dic"
   $DexMajorVersion = 12
  }
    2015 { 
   $dictionary = "$localFolder\resources\Dyn2015.dic"
   $DexMajorVersion = 14

  }
    2016 { 
   $dictionary = "$localFolder\resources\Dyn2016.dic"
   $DexMajorVersion = 16
  }

    default { 
   Write-Output "Invalid Version Number" 
   } 
}

$DexterityEXE = ".\Dex$DexMajorVersion\Dex.EXE"

$offset = "z_"  # Set blank for live mode.

if ($dictionary -ne ''){
    # Ensure the Destination folders exist.
    [System.Enum]::GetValues([BuildType]) | foreach { 
        $_compileModeName = $_
        mkdir "$localFolder\$($offset)$($_compileModeName)" -ErrorAction SilentlyContinue | Out-Null
        mkdir "$localFolder\$($offset)$($_compileModeName)\$VersionNumber" -ErrorAction SilentlyContinue | Out-Null
    }


    $fileSet = @()
    $modules = @('MICR', 'MICRJ', 'MMM', 'MEP', 'VPS')

    if ($modules -contains  $SingleModule)    
    { $modules = @($SingleModule.ToUpper()); Write-Host $modules -ForegroundColor Green }
    else { Write-Host "All Modules" -ForegroundColor Green }

    foreach($mod in $modules) {
        $workFolder = "$localFolder\$($offset)$($mod)\$($VersionNumber)"
        $dataFolder = "$workFolder\Data"
        mkdir $workFolder -ErrorAction SilentlyContinue | Out-Null
        mkdir $dataFolder -ErrorAction SilentlyContinue | Out-Null

        ## Copy the Dynamics Dictionary.
        $destination_file = "$workFolder\Dyn$($mod).dic"
     copy $($dictionary) $($destination_file)
        Set-ItemProperty $destination_file IsReadOnly -value $false
        Write-Host "$destination_file created." -Backgroundcolor Green -ForegroundColor Black

        # Copy Install_Code macro.
     $original_file = "$localFolder\Macros\Install_Code.mac"
     $destination_file =  "$workFolder\Install_Code.mac"
        $fileSet += , @($original_file, $destination_file, $mod, $_compileModeName)


        [System.Enum]::GetValues([BuildType]) | foreach { 
            $_compileModeName = $_
            $_compileMode = [int]$_

      ## Copy Constants.constant file to module-specific version and replace variables.
         $original_file = "$localFolder\resources\Constants.constants"
         $destination_file =  "$workFolder\Const_$_compileModeName.constants"
            $fileSet += , @($original_file, $destination_file, $mod, $_compileModeName)


            ## Copy the Macro - Twice: Once for Build and once for Source.
         $original_file = "$localFolder\Macros\Build_$($mod)_Source.mac"
         $destination_file =  "$workFolder\$($mod)_$($_compileModeName).mac"
            $fileSet += , @($original_file, $destination_file, $mod, $_compileModeName)

            ## Copy the Install_Constants.mac - Twice: Once for Build and once for Source.
         $original_file = "$localFolder\Macros\Install_Constants.mac"
         $destination_file =  "$workFolder\Install_Constants_$_compileModeName.mac"
            $fileSet += , @($original_file, $destination_file, $mod, $_compileModeName)
        }
        

  ## Copy Dex.INI file to module-specific version and replace variables.
  $original_file = "$localFolder\resources\Dex.ini"
  $destination_file = "$dataFolder\Dex.ini"
        $fileSet += , @($original_file, $destination_file, $mod, $compileMode)

        ## After this point, $MOD for MMM is MPP.
        if ($mod -eq 'MMM') { $mod = 'MPP' }
    }

    foreach($item in $fileSet)
    {
        $originating = $item[0]
        $destination = $item[1]
        $mod = $item[2]
        $_compileModeName = $item[3]
        $_compileMode = [int]$item[3]

        $workFolder = "$localFolder\$($offset)$($mod)\$($VersionNumber)"
        $chunkDestinationFolder = "$localFolder\$($offset)$($_compileModeName)"

        if ($_compileModeName -eq [BuildType]::Build.ToString())
        {
            $ChunkTypeComment = ""
            $_subBuildMessage = ""
        }
        else 
        {
            $ChunkTypeComment = "# -- Source -- " 
            $_subBuildMessage = "Build $($BuildNumber).$($SubBuildNumber) ($($BuildNumber).$($SubBuildNumber).$(Get-Date -format yyyyMMdd.hhmmss))"
        }


     (Get-Content $originating) | Foreach-Object {
      $_ -replace '%CompileMode%', "$_compileMode" `
         -replace '%CompileModeName%', "$_compileModeName" `
         -replace '%ChunkDestination%', "$chunkDestinationFolder" `
         -replace '%ChunkTypeConstant%', "$_compileMode" `
         -replace '%DexMajorVersion%', "$DexMajorVersion" `
         -replace '%DexBuildVersion%', "$BuildNumber" `
         -replace '%DexSubBuildMessage%', "$_subBuildMessage" `
         -replace '%ModulePath%', "$workFolder" `
               -replace '%Module%', "$mod" `
         -replace '%GenericPath%', "$localFolder\Generic\" `
         -replace '%TempPath%', "$localFolder\Temp\" `
         -replace '%LogPath%', "$localFolder\Logs\" `
         -replace '%OriginatingPath%', "$localFolder\Resources\" `
               -replace '%ChunkTypeComment%', "$ChunkTypeComment" `
         -replace '%VersionNumber%', "$VersionNumber"
        } | Set-Content $destination

        Write-Host "$($destination) created." -Backgroundcolor DarkRed -ForegroundColor Yellow
    }

    
    $DexterityEXE = ".\Dex$DexMajorVersion\Dex.EXE"
    $DexUtilsEXE = ".\Dex$DexMajorVersion\DexUtils.EXE"

    foreach($mod in $modules) {
        $workFolder = "$localFolder\z_$mod\$($VersionNumber)"
        $dictionary = "$workFolder\Dyn$($mod).dic"
        $LoadMacro =  "$workFolder\Install_Code.mac"

        Start-Process -FilePath $DexterityEXE -ArgumentList @($dictionary, $LoadMacro) -PassThru -Wait -Verbose
##        $process = (Start-Process -FilePath $DexterityEXE -ArgumentList @($dictionary, $LoadMacro) -PassThru -Wait)
##        Write-Host "$($mod) code loaded. Status: " $process.ExitCode
    }
}

6. The Source folder will contain the code retrieved from the Visual Studio Team Services repository. You will need a script to do this as well. The script will leverage the VSTS API to retrieve the code from the repo.

Param(
    [string]$SourceCodeFolder = "$/MICR/Base/2/2015B160", # Ex. 2015
    [string]$VSTSUser = "youraccount@somedomain.com",
    [string]$VSTSUserPAToken = "abcdefghijklmnopqrstuvwxyz0123456789",
    [switch]$TestStructure
)

$localFolder = Get-Location #"$([System.IO.path]::GetPathRoot($(Get-Location)))" 
$workFolder = "$localFolder\Generic\"

$scopePath_Escaped = [uri]::EscapeDataString($SourceCodeFolder) # Need to have this in 'escaped' form.

Write-Host "Pulling code from $($SourceCodeFolder) into $($workFolder)" -BackgroundColor DarkGreen

$recursion = 'Full' # OneLevel or Full
#$recursion = 'OneLevel' # or Full
 
# Base64-encodes the Personal Access Token (PAT) appropriately
$base64AuthInfo = [Convert]::ToBase64String([Text.Encoding]::ASCII.GetBytes(("{0}:{1}" -f $VSTSUser,$VSTSUserPAToken)))
 
# Construct the REST URL to obtain the MetaData for the folders / files.
$uri = "https://yourcompany.visualstudio.com/DefaultCollection/_apis/tfvc/items?scopePath=$($scopePath_Escaped)&recursionLevel=$($recursion)&api-version=2.2"

# Invoke the REST call and capture the results
$result = $null
$result = Invoke-RestMethod -Uri $uri -Method Get -ContentType "application/json" -Headers @{Authorization=("Basic {0}" -f $base64AuthInfo)}

 
# This call returns the METADATA for the folder and files. No File contents are included.
if ($result.count -eq 0)
{
     throw "Unable to locate code at $($SourceCodeFolder)"
}

$scopePathLength = $SourceCodeFolder.Length + 1 # +1 to eliminate an odd prefixed '\' character.

# =======================
# Create folder structure.
# =======================
for($index=0; $index -lt $result.count; $index = $index + 1)
{
    if ($result.value[$index].isFolder -eq $true)
    {
        #Strip the VSTS path off of the folder, and prefix with the local folder.
        $_subPath = $result.value[$index].path
        if ($_subPath.Length -ge $scopePathLength)
        {
            #Strip the VSTS path off of the folder
            $_subPath = $result.value[$index].path.Substring($scopePathLength)

            #prefix with the local folder.
            #MGB: replace the forward slashes in the remaining VSTS path with backslashes
            $_subPath = "$($workFolder)$($_subPath)" -replace "/", "\"

            if ((Test-Path $_subPath) -ne $true)
            {
                New-Item -Force -ItemType directory -Path $_subPath | Out-Null
                Write-Host $_subPath -BackgroundColor red
            }
            else
            {
                Write-Host "$($_subPath)`t$($result.value[$index].path)" -BackgroundColor Green -ForegroundColor Black
            }
        }
    }
}

# ==============
# Retrieve Files 
# -TestStructure flag will show all folders/files that will be retrieved.
# ==============
for($index=0; $index -lt $result.count; $index = $index + 1)
{
    if ($result.value[$index].isFolder -ne $true)
    {
        #Strip the VSTS path off of the folder, and prefix with the local folder.
        $_subPath = $result.value[$index].path
        if ($_subPath.Length -ge $scopePathLength)
        {
            #Strip the VSTS path off of the folder
            $_subPath = $result.value[$index].path.Substring($scopePathLength)

            #prefix with the local folder.
            #MGB: replace the forward slashes in the remaining VSTS path with backslashes
            $_subPath = "$($workFolder)$($_subPath)" -replace "/", "\"

            ## Retrieve the file text.
            if ($TestStructure -eq $true)
            {
                $fileresult = $result.value[$index].url
            }
            else
            {
                $fileresult = Invoke-RestMethod -Uri $result.value[$index].url -Method Get -ContentType "application/json" -Headers @{Authorization=("Basic {0}" -f $base64AuthInfo)}
            }

            New-Item -Force -ItemType file -Path $_subPath -Value $fileresult | Out-Null
            Write-Host $_subPath -BackgroundColor Green
        }
    }
}

You can use the Visual Studio IDE to setup a project on VSTS and add the folders and files needed for your Build Engine project.

In summary, setting up a Build Engine project involves thinking about all the elements required to produce your chunk file: IDE, macros, and scripts that will drive the process. The complexity of each script will depend on the number of points you want to automate, variables and constants you want to inject, and certainly the number of chunks you need to produce for each version of Dynamics GP.

Tomorrow, I will explain the details involved with setting up the actual Build process with the parts.

Until next post!

MG.-
Mariano Gomez, MVP
IntellPartners, LLC
http://www.IntellPartners.com/