Importing an Azure BACPAC to a development VM

As a Dynamics 365 for Finance and Operations developer, you will probably find it easier to develop, test, and debug problems if you have a recent database available to you in your development VM. Although there does exist general documentation on this process, as of this writing, I’ve found it less than ideal for developers; a couple of minor errors, some extra steps, and lacking a few tips for problems you might run into.


For sake of this post, I’m going to assume that a system administrator has tackled providing you with an exported BACPAC file, and that you are able to get it copied to your development VM.

You should install the latest version of SQL Server Management Studio (or at least some 17.x version), which is an easy way to get the updated SQL tools you will need to work with BACPAC files from current versions of SQL Server Azure. Honestly, I recommend this as part of the initial VM setup.

If you’ve been running Dynamics 365 for Finance and Operations for a while, your VM hard drive might not be big enough. You might need to make the virtual drive larger.

Import the database

You need to run an command prompt as administrator. If you don’t run the command prompt as administrator, you will probably get an error like “Unable to connect to master or target server …” At the administrator command prompt, use the following:

cd "C:\Program Files (x86)\Microsoft SQL Server\140\DAC\bin"
SqlPackage.exe /a:import /sf:C:\TEMP\BackupFilename.bacpac /tsn:localhost /tdn:AxDB_YYYYMMDD /p:CommandTimeout=1200

You should note three parts of these commands:

  1. If the first command gives you an error, and/or you only have a “C:\Program Files (x86)\Microsoft SQL Server\130\DAC\bin” directory, and/or you get an error similar to “Error importing database:Could not read schema model header information from package. The model version ‘3.5’ is not supported.“: you should, as mentioned in the prerequisites, install the latest version of SQL Server Management Studio (or at least some 17.x version), which is an easy way to get the updated SQL tools you need.
  2. For the second command, you need to change the /sf: switch to point to the BACPAC file.
  3. For the second command you also need to change the /tdn: switch to whatever temporary name you want to use to import the new database. You will change it later, but the name you choose will determine filenames used for the database; so it’s best to choose something you haven’t used before. I recommend using a AxDB_YYYYMMDD format. If importinf gives you an error about the filename being in use, the easiest thing to do is pick a different database name. Remember, it’s just temporary!

Once you have it running, be prepared to wait a while. Like, a couple of hours is very possible.

Update the database

This is pretty much just running code in a query window of SQL Server Management Studio (SSMS). I offer some minor tweaks (and comments) to what Microsoft does.

-- Following is the SQL script you use after importing the database.
-- You might want to run it one "chunk" (up to each "go" statement) at a time.
-- You need to change the next line to use the "temporary" database name you picked.

CREATE USER axdeployuser FROM LOGIN axdeployuser
EXEC sp_addrolemember 'db_owner', 'axdeployuser'

CREATE USER axdbadmin FROM LOGIN axdbadmin
EXEC sp_addrolemember 'db_owner', 'axdbadmin'

-- might error - deprecated or retail?
CREATE USER axmrruntimeuser FROM LOGIN axmrruntimeuser
EXEC sp_addrolemember 'db_datareader', 'axmrruntimeuser'
EXEC sp_addrolemember 'db_datawriter', 'axmrruntimeuser'

CREATE USER axretaildatasyncuser FROM LOGIN axretaildatasyncuser
EXEC sp_addrolemember 'DataSyncUsersRole', 'axretaildatasyncuser'

CREATE USER axretailruntimeuser FROM LOGIN axretailruntimeuser
EXEC sp_addrolemember 'UsersRole', 'axretailruntimeuser'
EXEC sp_addrolemember 'ReportUsersRole', 'axretailruntimeuser'

EXEC sp_addrolemember 'db_owner', 'NT AUTHORITY\NETWORK SERVICE'

-- Not everybody needs this, but it doesn't hurt.
SET T1.storageproviderid = 0
 , T1.accessinformation = ''
 , T1.modifiedby = 'Admin'
 , T1.modifieddatetime = getdate()
FROM docuvalue T1
WHERE T1.storageproviderid = 1 --Azure storage

-- It is very unlikely you need this in a development environment. Microsoft includes it, but I do not recommend it for developers.

-- Begin Refresh Retail FullText Catalogs
-- If you do not use retail components, you do not need this section, but it doesn't hurt.
OPEN retail_ftx;

 PRINT 'Refreshing Full Text Index ' + @RFTXNAME;
 PRINT error_message()

CLOSE retail_ftx; 
DEALLOCATE retail_ftx; 
-- End Refresh Retail FullText Catalogs

-- Microsoft does not tell you to do this, but in a development environment, it is very likely that you want to change the database "recovery model."
-- Otherwise, you need to set up backups and/or clean up the transaction log; otherwise the database can grow at an unmanageable rate, eating up your whole VM drive.

-- You might want to shrink the size of the transaction log, just to keep room free on your VM's drive.
-- You can do it in the SSMS GUI, or use the following statement (with a change to reflect your DB name).

Re-provision the target environment & Reset the Financial Reporting database

I do not use Retail components or Financial Reporting, especially not in my development environment; so I have no reason not to follow exactly what is in the Microsoft documentation.

Start to use the new database

To switch to using the new database, you must first stop these three services (the Microsoft documentation is out of date on the service names):

  • Management Reporter 2012 Process Service
  • Microsoft Dynamics 365 for Operations – Batch Management Service
  • World Wide Web Publishing Service

Then rename the databases so your new one is named AxDB (the old one can be named AxDB_ORIG or AxDB_old or whatever; eventually you will want to delete it, to save space). Then you can re-start the three services above, and you are good to go!

You can rename the databases using the SSMS GUI (in Object Explorer) or by using T-SQL commands similar to:

USE master;

Build/synchronize the new database

You should launch Visual Studio, go to Dynamics 365 > Build Models, and do a full build (with the “Synchronize Database” option) all of your customized and/or extended models.

After that, you are ready to go!

Expanding the hard drive on your development VM (“onebox”)

In some development shops, the development VMs will be cloud hosted and centrally managed. But I try to help out others who are managing their own development VMs; and if you’re restoring copies of a growing production database in order to debug a trick issue, you might find that the “as shipped” VM doesn’t have a big enough hard drive. Here are the steps to help you expand it.

  1. In Hyper-V Manager, stop the VM and delete any checkpoints. (Unfortunately, you can’t expand the drive for a VM with checkpoints.)
  2. In Hyper-V Manager, in the “Settings” for the VM, go to “Hard Drive” and find the “Edit” button under the virtual hard disk:
    Edit virtual hard drive in Hyper-V Manager
  3. Use the wizard to “Expand” to the desired size. (Unfortunately, it’s hard to know exactly how much space you’ll need. A database bacpac is significantly compressed, and you know better than me how much space you are likely to need.)
  4. Start & connect to the VM. You will not see the new space available yet.
  5. In the VM, run Disk Management. It is in Control Panel, or will come up if you type diskmgmt in the Start menu:
    Typing “diskmgmt” in the Start menu should bring up something that looks like this.


  6. In Disk Management, right-click the OsDisk (C:) partition and choose “Extend Volume.”
    Extend volume in Disk Management
  7. You should be able to just keep clicking “Next” through the wizard without changing any defaults; it will expand to fill the newly available space.
  8. That’s all, you’re done! When you are done restoring your bacpac and building it (or whatever else you wanted to expand the disk for), don’t forget that you’ve deleted all your checkpoints.


Although this isn’t a process specific to Dynamics 365, if you aren’t used to managing a VM, I hope it helps you get back to developing a little sooner.

Logging in to SQL Server in the developer VM

Connecting to SQL Server in the Dynamics 365 for Operations development VM

This post assumes you are comfortable in the use of SQL Server. If you are not, this is a good entry to go ahead and skip.

EDIT: This post might not be necessary. I am told that due to UAC, all you need to do is launch SSMS using “run as administrator” instead. I’ll leave what I wrote here for historical purposes (it’s still interesting) but you don’t need it!

Coming from a SQL Server background, I have frequently found it helpful to dig through the tables in AxDB, the SQL Server database used as a datastore for Dynamics AX / Dynamics 365 for Operations. Although we do not have direct access to them when programming, and the “Tables” in the AOS are an abstraction that sometimes differs, they are often analogous; it can be easier to plan out a join in familiar T-SQL before trying it in X++. It’s also a good troubleshooting and debugging tool.

And, let’s face it… Microsoft might not like it, but once in a blue moon it can be easier to do certain cleanup or bulk updates that way, if you know what you are doing. Not the best practice, but certainly a fast way to clear a new table you are building, or activate a hundred imported users in one shot…

Working on platform update 3 and earlier, all you had to do was fire up SSMS (SQL Server Management Studio) while you were logged in as the VM Administrator, and (per defaults for most SQL Server installations) you were a sysadmin. After moving to a fresh Platform Update 5 VM (skipping PU4), however, I found that they’d configured SQL Server to no longer allow you access. Not cool, Microsoft.

However, there is a workaround. As you might know, there is a web.config file that contains information Dynamics 365 for Operations uses to connect to its datastore, including a sysadmin user and password. Although the password is stored “encrypted,” you can decrypt it temporarily. Just do that and find the relevant entries in the web.config file:

Although “security through obscurity” ain’t great, I’m not going to put the actual platform update 5 default password here, especially since it might change anyway.

If you want long-term convenience, you might want to immediately log in with these credentials and re-add the local administrator as a login with the sysadmin role. (If you don’t know how to do that, maybe you shouldn’t be mucking around in the SQL Server after all!) Then you don’t need to remember or save the password you dug out of here.

Oh, and… don’t forget to re-encrypt the web.config file when you’re done.

ADDENDUM: In case something happens to the linked post, here are the commands to decrypt and re-encrypt the web.config file. But please, go through and comment on the original post… and comment here too… it motivates bloggers to keep going when we get the occasional response. Just a quick “thank you” is plenty!

C:\AOSService\webroot\bin\Microsoft.Dynamics.AX.Framework.ConfigEncryptor.exe -decrypt C:\AOSService\webroot\web.config

C:\AOSService\webroot\bin\Microsoft.Dynamics.AX.Framework.ConfigEncryptor.exe -encrypt C:\AOSService\webroot\web.config

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!