WRITING to Financial Dimensions (DefaultDimension) in X++

One of my initial programming tasks with Dynamics 365 for Operations (AX 7) has been writing routines to import data from external systems. These complex routines are writing to multiple tables, and sending email when there are problems (a subject for a future post)… and, recently, took another step up in complexity.

When I found out I had to write a routine to import data to “Financial Dimensions” (sometimes called “Default Dimensions” for reasons I’ll soon explain) on employees/workers (more specifically, their employment records, the HcmEmployment table) I was flummoxed for a while.

It took me a bit of reading to figure out what Financial Dimensions even were. Basically, they are attribute/value pairs that you can define yourself. There is more to them then that, and I won’t say I fully understand them yet… that’s a subject for other posts, so I’m just giving you some basics here in case you are unfamiliar. A few are set up by default, but you can also create your own. (General ledger > Chart of accounts > Dimensions > Financial dimensions) So you or an admin can go create a Favorite_Color dimension, give it a bunch of choices (01=Red, 02=Blue, etc.) and then attach a favorite color to a bunch of entities. Just look for a DefaultDimension column. Once that’s done, users can see and set them. For example, in my case, I could go to Human resources > Workers > Worker, look under “Employment” for a given worker, and see the Financial dimensions section listed at the bottom.

Unfortunately, the way they are stored and managed is complex. It’ll take a bunch of reading and looking at code samples to figure out how to get data out of them; I won’t repeat that here, it’s easy to find. But for all my searching, I could not find a way to WRITE to financial dimensions in X++. Finally, with a little help (thanks to Steeve Gilbert in the AXUG forums), I was able top work out a reusable method (or three) to help.

I’m sharing my sample code here to save you the pain I experienced. For sake of example, I’m assuming you put this in a class named MyDimensionHandlerClass, along with any other generic/reusable dimension-related methods you want.

In future blog posts I will share sample code for reading and validating attributes, just for completeness… although there are other samples for those out there.

/// <summary>
/// Generic dimension updater. Call this with the DefaultDimension of any table, and update that table’s DefaultDimension with the returned value.
/// Sample usage:
/// hcmEmployment.DefaultDimension = xczDimensionHandler::PutDimension(hcmEmployment.DefaultDimension, ‘Favorite_Color’, ’01’);
/// hcmEmployment.validTimeStateUpdateMode(ValidTimeStateUpdate::Correction); // This may or may not be appropriate for your circumstances
/// hcmEmployment.update();
/// Based on sample code courtesy Steeve Gilbert.
/// </summary>
/// <param name = "_DimensionAttributeValueSet">Value in the "DefaultDimension" column of the linked table (i.e. HcmEmployee, etc.). Links to DimensionAttributeValueSet.RecId. You will need to update the calling table this came from.</param>
/// <param name="_attribute">Attribute (e.g. "Department").</param>
/// <param name="_value">Potential value for the Attribute (e.g. "950").</param>
public static RecId PutDimension (RecId _defaultDimension, str _attribute, str _value)
DimensionAttribute dimAttribute;
DimensionAttributeValue dimAttributeValue;
DimensionAttributeValueSetStorage dimStorage;
// Verify that the value passed for _attribute identifies a real dimension.
select firstonly dimAttribute
where (dimAttribute.Name == _attribute);
if (!dimAttribute)
throw error(“Invalid _attribute passed to PutDimension: ” + _attribute);
// Find or create a storage dimension that contains each dimension attribute and their value.
dimStorage = DimensionAttributeValueSetStorage::find(_defaultDimension);
// Update or delete the value within that storage dimension.
if (_value)
dimAttributeValue = DimensionAttributeValue::findByDimensionAttributeAndValue(dimAttribute, _value, true, true);
//If there’s no value, that means we want to remove that Dimension Attribute



Finding the customizations/extensions on an object

A minor tip, but a useful one that doesn’t seem to be widely documented/circulated:

Perhaps you might find yourself searching for the customizations or extensions that have been made to a standard object. It usually isn’t difficult to find these manually, but here’s a simple tip to do so quickly:

You’ll notice that you have a “search” option in design view.


If you use c: or e: for the search, it will show you customizations or extensions, respectively.



Installing Application X++ updates when SCDPBundleInstall.exe sucks

(UPDATE TO ORIGINAL POST: I’ve written more on this subject, and there is now a GUI tool in Visual Studio for applying hotfixes; you don’t need to use the SCDPBundleInstall.exe command line tool. Take a look at Installing Application X++ Updates Still Sucks (part one) and Installing Application X++ Updates Still Sucks (part two) instead of this, and only come back if you feel you still need to use SCDPBundleInstall.exe and you’re having problems. Installing Application X++ updates still sucks, but it does suck significantly less now.)

If you’re reading this, you have probably already tried to install some Application X++ updates you downloaded from Lifecycle Services, and failed. I’m assuming you’ve gone to this page:

…and tried to follow it, and run into one or both of these problems:

(1) As of this writing, the instructions on that page are out of date, and have one or two mistakes.

(2) SCDPBundleInstall kind of sucks. It doesn’t seem to always get dependencies right when the updates stack up, running them in the right order; and in some cases -prepare doesn’t create needed directories, although -install does.

For example, if you included hotfix 3208224, you probably got an error like this:

Could not find a part of the path 'C:\AOSService\PackagesLocalDirectory\AccountsPayableMobile\AccountsPayableMobile\AxLabelFile\LabelResources'.
 at Microsoft.Dynamics.AX.Servicing.SCDPBundleInstall.PrepareCommand.RunCommand()
 at Microsoft.Dynamics.AX.Servicing.SCDPBundleInstall.Program.Main(String[] args)

As such, you need to follow some steps that include a couple of corrections and workarounds. These will get you a good safe changeset to roll back to in source control if things go awry; it will also help make sure you have a deployable package that will install correctly through Lifecycle Services.

After much suffering on my end, I want to save you the trouble, and step you through what to do. This came from my own trial and error, and I haven’t seen these steps laid out anywhere else; if they have been, please let me know so I can link there and/or give credit. If there is a better way, or this gets fixed, please let me know and I’ll update this.

Part I: Prepare your dev/onebox

Step 1: Have the hotfixes

I assume that you have downloaded the package of hotfixes, which is fairly well documented elsewhere (and pretty intuitive anyway). You should have a file with a .axscdppkg extension on your dev/onebox, with a name/folder location that is clear and recognizable. (Do yourself a favor: have a folder where you put all the hotfixes, and create subfolders that include the VM name, date, number of hotfixes, and the text “X++ Hotfixes,” or something similar.)

Step 2: Your dev/onebox needs to be healthy

By the time you’ve done your web searches and gotten here, it might be too late, and your dev/onebox might be messed up. I can’t help you fix it here. Maybe you’re lucky and have a good checkpoint to go back to, and a good point in version control to pull from. I have had to reinstall my dev/onebox, and it stinks; if you do too, then you have my sympathy.

Temporarily, you should probably not have any mapping to your main/production/build branch in your dev/onebox. If you do, strongly consider removing that mapping for now. You’ll probably need to put it back if you are doing branch merges from your box. But, having mapping to multiple branches will probably confuse SCDPBundleInstall; running it will at least take longer, as it creates the same changes in multiple branches.

Step 3: Get version control to a healthy state

If you’ve hoarked your version control, you need to get back to a healthy state, and I can’t help with that. You need to work with someone who understands version control.

This will be easiest/simplest if your production/build branch is up to date and in sync with your dev/working branch. Consider doing a compare before proceeding.

Locally, on your dev/onebox, this will be easiest if you start from a point where you have nothing in Pending Changes > Included Changes. (If you don’t know how to find that easily yet– in Visual Studio, under Team Explorer– you are swimming in the deep end now!)

Step 4: Checkpoint your VM

If you screwed up your dev/onebox before finding this page, you already appreciate the value of frequent checkpoints. If not… be thankful and do a checkpoint now anyway.

If you don’t know how to do a checkpoint, you should probably spend a little time poking around whatever tool you use to manage virtual machines. In Hyper-V Manager on Windows, right-click the VM and choose “Checkpoint.”

Part II: Create the directory structure required to make SCDPBundleInstall -prepare work properly

Step 5: Do SCDPBundleInstall -install

If you are reading these instructions, it’s probably because -prepare failed for you. As of this writing, -prepare does not always create necessary folders, but -install does. That’s why you’re doing all these convoluted steps. As much time as it wastes, we are going to do the -install first solely to get the directory structure created.

This step will take a while, especially if you have  multiple branches mapped. Note my earlier advice that you (at least temporarily) remove mappings for anything but your dev/working branch.

Note also that, as of this writing, the syntax of the -tfsprojecturi switch is not documented correctly, at least not on the wiki page noted above. You just use a URL, not a project.  Here is some sample syntax (anybody with sufficient WordPress expertise to help me format this better, please comment!):

C:\AOSService\PackagesLocalDirectory\Bin>SCDPBundleInstall -install
-packagepath="C:\AXHotfixes\X++ hotfixes 2017-02-22 (142)\HotfixPackageBundle.axscdppkg" 

If you get an error, try re-running the command, and it might work! This does not seem to do things in the right order, or consistently, and sometimes it runs fine after a retry or two. The important thing is that it eventually completes, creating the directory structure we need.

If you absolutely can’t get this to finish, go back to your VM checkpoint and quit following these instructions. Sorry, but you’re beyond the help I can give here.

Step 6: Undo the file changes via source control

This is where we get tricky. In Visual Studio, in Team Explorer, look under Pending Changes and undo all the Included Changes. Not exclude; undo. We are rolling back the file changes that the -prepare just made. (But give them a once over first to make sure you’ve excluded any active development you still have going. Ideally you don’t have anything outstanding, but we don’t live in a perfect world, or you wouldn’t be here.)

After completing this step, you should be at a point where the directory structure you need for the hotfixes has been created; but none of the files have been changed.

Step 7: Copy the directory structure

We want to take a copy of just the directory structure (the files inside would be overkill), which we can effectively do with this command:

C:\AOSService\PackagesLocalDirectory>xcopy * "C:\PLDstructure" /T /E /X /I /H

If run this in your packages folder as shown, this is going to copy out JUST the folder structure, with no files, to C:\PLDstructure. Adjust the command as necessary if you are using another directory.

(It might be possible to speed this up by also using the /D:m-d-y switch, but this should not take too long anyway.)

After doing this, copy the C:\PLDstructure folder (or whatever you named it) out of your VM and into your host operating system. We need it backed up outside the VM, because we are just about to…

Step 8: Apply the checkpoint you took in Step #4

Something might have gotten screwed up on your dev/onebox by doing this. SCDPBundleInstall can’t be trusted. Let’s be safe and apply our checkpoint, restoring our box to the healthy state before we ran it.

Step 9: Restore the needed folder structure

Copy the C:\PLDstructure (or whatever you named  it) back into your VM.

Now create whatever empty folders you need in your packages directory by doing this (adjust the locations as necessary):

xcopy "C:\PLDstructure" "C:\AOSService\PackagesLocalDirectory" /T /E /X /I /H

Part III: Back on track!

We are now at a place where we can mostly return to following the wiki.


Step 10: Do SCDPBundleInstall -prepare

This may take a couple of minutes, but nearly as long as the -install. Remember the different syntax for -tfsprojecturi. You are pretty much using the same command that you used in Step #5, other than replacing -install with -prepare.

Although the -prepare probably failed before, it hopefully works now that the directory structure it needs exists. If not… you might be beyond the help I can give.

Step 11: Check in the touched files

All the files you see in Pending Changes > Included Changes should be files that currently exist but will be changed by running the actual install. They should not have been changed, just “touched” so that they are picked up as pending changes for version control. (There are less of them than what the -install will create since you are just getting the pre-existing files. -install will create all new files, but we don’t need them in the checkpoint we are creating, since rolling back to it in an emergency should delete files that did not exist.)

You now want to check all these in, with a clear note that this changeset is your pre-hotfix rollback point. If things go south, we can theoretically roll back to this point to get our VM back to a good state.

Make sure to merge your dev/working branch into your main/production/build branch so you have somewhere to fall back there, too. Watch the changesets; I got some false matches of older ones.

You might want to run a build in Lifecycle Services at this point, just to make sure nothing unexpected broke. Theoretically, there is nothing new being introduced, and you should have no problems. But that requires more trust of SCDPBundleInstall than I have.

Step 11: Do SCDPBundleInstall -install (again)

Once again, you might need to run it multiple times, if dependencies and/or run orders aren’t right.

This will take a while, especially if you have  multiple branches mapped. Note my earlier advice that you (at least temporarily) remove mappings for anything but your dev/working branch.

Step 12: Review “Pending Changes”

Take a look at your Pending Changes. If you have multiple branches mapped, you might have redundancies you need to clean up by excluding/undoing them. Ideally, you see a nice clean set of hotfix changes, all contained in your packages directory (i.e. C:\AOSService\PackagesLocalDirectory).

Step 13: Resolve Conflicts

This is covered pretty well in the original wiki:

Step 14: Do a local build

Before doing this, refresh the list of models, so any new models are picked up by your build! Go to Dynamics 365 > Model Management > Refresh Models.

Do a local build. I usually just include all models at this point; be sure to “Synchronize Database” under Options, too! Because the build’s analysis of dependencies isn’t perfect, you might get build errors that resolve themselves if you do the build one or two more times. I ended up running the local build four or five times; as long as you are getting different errors each time, it means you’re making progress. (If you have a deeper understanding of this than me, please let me know, and I’ll add detail.) Eventually, you should hit a point where it builds without error, and all you get are the 1000+ warnings you are used to ignoring with every build.

If you keep getting the exact same errors over and over, you are outside the scope of help I can offer in this blog post.

Step 15: Check in, Synchronize, Deploy

The original wiki picks up fine at this point:

It may go without saying, but you should be sure to use check-in comments and deployable package names that are clear about their contents. I try to include at least the date, number of hotfixes, and the text “X++ Hotfixes,” or something similar. If you have a small enough set of hotfixes, actually including the hotfix number(s) makes sense!

Setting up a personal Dynamics 365 For Operations, Enterprise Edition, development environment

Setting up a personal virtual machine to do Dynamics 365 For Operations development.

(last updated 2018-06-11)

Microsoft expects all Dynamics 365 / X++ development to be done in a preconfigured virtual machine (sometimes called a “onebox”) that has local installs of Visual Studio, Dynamics, and SQL Server; these are integrated in a way to ease development. They would prefer that you rented these VMs from them, which has some integration advantages; but it is possible to set up your own, which is probably less expensive in the long run, and might be more convenient. These instructions will help you set up that development environment on a personal machine; although there are a few wiki pages on it, there does not seem to be any complete, up-to-date information gathered in one place.

As with all my blog posts, if you have comments or additional information, I will endeavor to update what I have written here. I have noticed that this is by far my most popular blog post, so please, contirbute if you can… you’ll be helping many others!

This guide is up-to-date for the application release 7.3 platform update 12 version. Sometimes things change slightly between versions, but it is now rare to find drastic changes.



You probably want at least 16 GB of memory to SPARE for the VM beyond what you are already using, plus, probably around 150-200 GB of HD space. (By default the VM wants to offer you 128 GB on the virtual drive; but more room for a realistic database or checkpoints is good to have.) At least two CPUs. (As always, the more resources, the better; these are pretty good minimums.) And you have to be able to enable virtualization in the BIOS; many modern high-end machines enable it by default, but some might have it disabled, and older or less powerful machines might not support it..

You need to be able to run virtual machines on your computer

Not all machines can handle virtualization (it usually requires a BIOS setting that might not be enabled by default) and you probably need Windows 10 Professional or Enterprise (64 bit) as your operating system. I’m not sure that any other Windows operating systems other than Server ones will run Hyper-V. (You might be able to set it up with another OS entirely? Like, can Mac users run a Windows VM?)

 Setting up Hyper-V on Windows 10 is covered here (consider installing Hyper-V a prerequisite):

You need to have an MSDN account attached to a Visual Studio subscription

Your MSDN account might use the same email address as your “work/school” account, but they are different accounts in different Microsoft databases, and yes it can be confusing; but they can be linked together after you create the MSDN account.

NOTE: I believe the following information is deprecated, but I am temporarily leaving it here (struck through) until I am sure. Feedback from people having trouble setting up MSDN is welcome. Based on personal experience, I recommend using different passwords, so you can keep straight which one you are using at any given time. Go to to create an MSDN account. Although counterintuitive, you probably must create it as an “individual” account (instead of a “work/school” account) because you probably already have a “work/school” account for your work email address.

At least, that was the situation I ran into, and web searches lead me to realize I was far from alone. If you have been able to set this all up with a single account, let me know.

Downloading the VM

This can be tricky. Microsoft isn’t keen on putting these in the hands of people who want to learn the product; only paying customers and partners. If you know of a location where people who just want to learn how to program in X++ can get the VM, let me know. (I get asked a lot.)

The location at which you should download the VHDs has changed four times over the past year or so, but I think it’s finally somewhere it will stay: the “Shared asset library” in Lifecycle Services. Introducing you to Lifecycle Services is outside the scope of this post, but if you are a paying customer or partner, you should become very familiar with it pretty quickly.

Don’t confuse the “Shared asset library” with your project-specific “asset library.” To get to the “Shared asset library,” after logging in (but before clicking on your project), look at the eight blue tiles on the right side of the screen (to the right of the “Announcements”).

Shared asset library tile

In the Shared asset library, click on the “Downloadable VHD” section.

click on Downloadable VHD

Find and download all the parts of the VHD you want. For example, if you want application version 7.3 with platform update 12:

download the VHD parts

Once you have downloaded them all, one of the files should be an executable that assembles the others into a complete VHD file.

Installing the VM

 You should have Hyper-V set up, per the prerequisites. Use Hyper-V Manager to set up your new VM.

You probably want to copy the VHD file into C:\Users\Public\Documents\Hyper-V\Virtual hard disks locally; that’s the default location Hyper-V wants. (It can go other places; you’ll just have to configure it properly.)

 The VHD file is in the wrong format to import as a VM, so you have to create a new machine, then during the phase to create or connect a disk point to the VHD file.

In Hyper-V Manager (you are going to get very familiar with Hyper-V Manager), do not choose Import Virtual Machine; instead, choose New > Virtual Machine

Hyper-V - New Virtual Machine

…and use the wizard:

  • Specify Name and Location: You might have more than one VM set up at a time when transitioning to new updates, so consider including the version number in the name. You can change this later so don’t sweat it too much.
  • Specify Generation: You need to set it up as a “Generation 1” machine.
  • Assign Memory: I usually give it 18 GB (18,432 MB) out of the 32 GB on my laptop, and definitely Dynamic Memory, but you might want to experiment with this.
  • Configure Networking: Start by choosing whatever connection you are currently using, but we’ll configure any others later.
  • Connect Virtual Hard Disk: “Use an existing virtual hard disk” and specify the VHD you downloaded.

Configuring the VM

After initial setup, you can change settings on the virtual machine. (Not while it is started, though.) Highlight it in Hyper-V Manager and choose “Settings.”

  • If you switch between multiple wired and/or wireless network connections on your laptop, you want to “Add Hardware” and add any Network Adapter you’ll use with the VM. I haven’t used any of the advanced settings. (Be careful not to just overwrite your old network adapter instead of creating a new one.)add network adapter
  • You probably want to let it use more than one (1) virtual processor; not more than your hardware has, but at least two (2) will help performance. (I have eight (8) processors and give the VM six (6), but you might want to experiment with this.)Hyper-V - enable multiple processors
  • Obviously, give it a useful name. You might have more than one set up at a time when transitioning to new updates, so consider including the version number in the name to distinguish them.

If you know that you are going to need extra space (for example, you expect to restore a production database that has grown somewhat), then now is a good time to proactively expand the size of the virtual hard drive, before possibly checkpointing and continuing.

Post-VM-installation configuration

Before you do any of this, you might want to checkpoint the VM. If the download process is long and slow, you don’t want to repeat it if you accidentally make a mistake you can’t undo.

When you first try to connect (and later, if you choose View > Enhanced Settings from the Virtual Machine Connection window) you can set display resolution and whether to use multiple monitors; also whether local resources (clipboard, printers, drives) are available to the VM. This is personal preference, but I find it easiest to work in a full screen single monitor, with access to the clipboard and local drive. Just be ready to set up what you want.

Logging in: Once you can launch the VM, you have to log in with Administrator / pass@word1 as the credentials.

Rename VM

This step is optional if you are the only developer; but if you are sharing VSTS with other developers, it seems to be necessary. Otherwise, you end up with Workspace collisions when trying to map source control.

If you get an error that looks like “The working folder C:\AOSService\PackagesLocalDierctory is already in use by workspace MININT-MHQ9O7x;DeveloperName on computer MININT-MHQ9O7x” when trying to do the “Source Control” steps below, you probably need to do this.

  • Go to Control Panel > System and Security > System and click “Change settings” next to the computer name.
    • Change it to a name of fifteen (15) characters or less; I suggest a standard that includes your name and the version (i.e. BPARKER-71-PU7 or BPARKER-73-PU12 would be fine). We just want to avoid the same name being used twice. Do not change the Workgroup or Domain. This will require rebooting the VM.
  • Change SQL Server Reporting Services to use the same name. Launch “Reporting Services Configuration Manager” from the Start menu.
    • Make sure the “Server Name” matches your new name and click “Connect.”
    • Select “Database.” If the SQL Server Name does not match your new name, choose “Change Database” and run through the Wizard. (Nothing else should change; Report Server Database should remain as DynamicsAxReportServer.)
    • Select “Web Portal URL” and make sure the URL matches the new name.
    • Select “Web Service URL” and make sure the URL matches the new name. You can probably click through to verify that it is running.
  • If you’ve already set up Workspace mapping in Visual Studio, you probably need to change it.

Provision Admin User

Once you can log in as Administrator, you need to use the AdminUserProvisioning tool (should be a shortcut on the desktop) to link the VM Administrator account to your MSDN account. All kinds of stuff in Visual Studio and the Dynamics AX/365 web interface depends on you being recognized as your Microsoft account. If the shortcut isn’t on the desktop (it wasn’t in early releases), go straight to: C:\AOSService\PackagesLocalDirectory\Bin\AdminUserProvisioning.exe

Be aware that there is a bug in the Platform Update 12 VMs; if you are still on a release using that, you need to work around it at this point:

Where I work, we don’t use the Retail module, so I ignore the RetailTenantUpdateTool (delete it from the desktop, even). If you use it and have information to share on it, let me know.

Operating System

If you want sound, you might want to launch Services and set “Windows Audio” to Automatic startup. They seem to leave it as Manual on the VM with the assumption that you don’t want it. (Even if you chose sound in Enhanced Settings.) Then set whatever Windows sound scheme will help you.

Do whatever other OS configuration makes you comfortable. You can usually run “Settings,” search “For developers settings,” and easily mass-apply some useful settings there.

 If you are as fussy as me (or like efficiency), you might want to put together your own checklist. For example, some things I like to do:

  • Install the updated version of SQL Server Management Studio (SSMS), if you’re the kind of developer who dips into SQL Server frequently.
  • Show file name extensions in Windows Explorer.
  • Create a desktop shortcut for Visual Studio with “Run as administrator” set.
  • Create a desktop shortcut for an Administrator Command Prompt with “Start in:” set to C:\AOSService\PackagesLocalDirectory\Bin and the Layout size increased a bit; I have to fire that up to run ModelUtil pretty frequently.
  • For the same reason (running ModelUtil), I like to take a minute to install “Path Copy Copy.”
  • Set your time zone, if needed.
  • You might want to change the Administrator password.
  • As of platform update 5, you are getting wallpaper instead of a plain grey desktop background. Your aesthetics are up to you.

The OS will probably need to download and install some Windows Updates; be ready for that.

Visual Studio

As of this writing, Visual Studio needs to “Run As Administrator,” so you might want to set up a shortcut for that.

You seem to need to log in to Visual Studio with your “Work/School” account rather than your “personal” (MSDN) account. You’ll need to configure workspaces and get from source control, which is out of the scope of this document. (If you don’t already understand source control as well as or better than me, then you need help I can’t give you.)

You should also review these (out-of-date and obviously woefully incomplete) setup steps from the Microsoft managed Wiki:

NOTE: Some of these are now set as advised in advance. I have no idea if Intellitrace still exists. (You’re told to disable it but I can’t find it anymore.) I will probably remove the above link eventually, since it is increasingly out of date.

In Visual Studio, go to Tools > Options > Dynamics 365 > Projects and select “Synchronize database on build for newly created project.” It will make your life easier. Based on my experience, I haven’t figured out a reason you would NOT want this activated for your development projects. I also use “Organize projects by element type” and recommend it as a standard for complex projects.

If you are aesthetically minded, you can install additional Visual Studio color themes with this:

You might want to install other Visual Studio add-ons. There are tons, but I haven’t found any specific to X++ development; mostly they would just offer aesthetic tweaks.

Source Control

I am not an expert on source control, and it can be complicated. (It possibly justifies its own separate blog post.) First you’ll need to connect to and log in to your VSTS server.

You are going to need to edit your Workspace. (Don’t rename it; that will mess some things up with IIS/Reporting Services. Instead, follow the “Rename VM” steps above if you need to share source control with other developers.) Just do this:


…and map certain parts of your projects to C:\AOSService\PackagesLocalDirectory (obviously this is only if you have existing projects):

VSTS mapping

Different companies will have different source control setups, so, DO NOT FOLLOW THIS BLINDLY.

Why do you need to do this?… When you create some objects, they are created right in your default folder. However, to let the “onebox” environment work its integration magic with the local Dynamics install, some objects you create in Visual Studio will instead be created in the C:\AOSService\PackagesLocalDirectory directory. In order for source control to see them, this mapping needs to exist for it to look in the right directories.

This configuration will differ depending on how you set up your source control. You might only need a single line added, and you might map it to a different “SourceControlFolder.” The important thing is making sure the objects created in C:\AOSService\PackagesLocalDirectory get in source control!

Do A Full Build

Especially if you have any existing code out there in source control already, now is a good time to get latest and do a full build of all models.

Dynamics 365 For Operations Local Install/Data

You might want to set an Internet Explorer favorites/bookmark for the local install of D365 ( Although this seems like an internet URL, your “onebox” has a hosts file that will point that URL to (your local machine) instead. You can find that file in C:\Windows\System32\drivers\etc if you’re curious, but you have no need to do anything with it.

A favorite/bookmark for VSTS and Lifecycle Services isn’t a terrible idea, either.

You probably want to go into the local installation of D365O, click the “cog” in the upper right for Settings, and change some User Options/Preferences. The USMF company has better test data, and you probably want to change the time zone. Again, this is personal preference.

There is a good chance that your organization has certain test accounts you will want to set up as Users (System administration > Users > Users) and/or Employees (Human resources > Workers > Employees). Or, perhaps you’ll have a database you want/need to restore that contains this info.

Configure SQL Server to let you log in

If you use SQL Server, you need to do this as of Platform Update 5:

Alternatively (and this is the better solution), you can still use Windows Authentication to connect to the local SQL Server if you run SSMS as administrator. So you might at least want to set up a shortcut for that, if you are the type who goes into SQL to debug problems.

Checkpoint the VM

After all this, if you accidentally do something wrong, you don’t want to have to do it all again. Checkpoint the VM. And don’t forget to do it regularly going forward.

Happy coding!