In order to save cost or time, it may be practical for partners/customers to host their own version of the VHD that is based on the official downloadable VHD by Microsoft. One scenario could be that the Contoso demo data is good enough for development, but some additional data setup, hotfix application or code customizations may be needed. These steps could be carried out once by one person, and then that VHD could be re-used. Some partners may be on a monthly cadence to “rev” their dev environments. There are two options to do this:
- Reuse the VHD and host it locally in HyperV or similar virtualization technologies
- Reuse the VHD and host it in Azure
The option 1) is straightforward and many will opt for this. There are some cases where it is useful to host in Azure though, mostly for simpler sharing of a VM or because an appropriate host for the VM is not available (i.e. laptop not powerful enough). Here is a step-by-step guide that worked for me to bring up the VHD to Azure so I can simply spin up a new instance in relatively short time:
- Download the VHD from https://connect.microsoft.com/ and unpack it
- (optional) prepare the VHD with data, binary fixes or customizations
- Upload the VHD to your Azure subscription. If you have not done already, you need to install the Windows Azure Sdk. If you have not done already, you need to create a management certificate for Azure on the local machine and upload it to Azure (basically this grants access to the Azure subscription). Then follow this: https://docs.microsoft.com/en-us/azure/virtual-machines/virtual-machines-windows-classic-createupload-vhd. I did not have to run sysprep on the downloaded VHD from Microsoft. I think this step is needed if you carry out step 2).
When the steps are done, you should see the new VHD ready to be used as a template for creating new VMs.
- Create a new VM based on that VHD: https://docs.microsoft.com/en-us/azure/virtual-machines/virtual-machines-windows-classic-createportal?toc=%2fazure%2fvirtual-machines%2fwindows%2fclassic%2ftoc.json(optional but suggested) Update the administrator password to something else, so nobody else can hijack your VM (if they somehow had the RDP connection)
I have added a PowerShell script that is ready do be executed after changing some of the variables:
This video demonstrates how to store application settings securely and manage them in AX. These settings are needed for AX business logic and CommerceRuntime business logic. The data is fetched via a RetailTransactionServiceEx call. The CommerceRuntime service takes care of calling the RTS and caching for a configurable period. Video also shows how to test this by exposing it via RetailServer and using the RetailServer TestClient.
This video shows the steps involved to code merge a new Retail Sdk into your current customization branch. In this case, I am updating my AX 7 RTW Retail Sdk (with customizations) to the AX 7 Update 1 Sdk. Same steps apply if you snap to a hotfix or to another update. It is a good practice to use a mirror branch as it makes code merges much easier. The update of the mirror branch is a prerequisite for this step, and was shown in a separate video.
This video shows the steps involved to update your VSTS-based Retail Sdk mirror branch with a newer build. In this case, I am updating my AX 7 RTW Retail Sdk to the AX 7 Update 1 Sdk. Same steps apply if you snap to a hotfix or to another update. It is a good practice to use a mirror branch as it makes code merges much easier. The code merge (as the next step) will be shown in a separate video.
Final note: If you take the Sdk from a new development VM, it may be installed at the C:\ or J:\ drive as shown in the video. If you however take a hotfix, the Retail Sdk can be found in the ‘Code’ subfolder:
Update 8/8/2016: Hotfix to Update 1 is now available: “KB 3183058: Retail Sdk update for packaging and deployment of payment files.”. If you can update, that is recommended, if you cannot, this article still applies.
The steps below allow you to update some files in your Retail Sdk so that payment packages can be built as well. The same code changes as in this zip package will be released as part of Update 2 and possibly even as a hotfix to Update 1.
The update allows you to generate all packages with all payment files (payment device assemblies, payment connector assemblies, and payment web files) embedded. All you would need to do is to get the payment files from the 3rd party, place them into the 3 locations dedicated for them and build. Whether built manually on command line or via VSTS automated build, the packages would include the files correctly.
Furthermore, the deployment of these packages will place the file in the correct locations. The packages that include these files are RetailServer, ModermPOS, ModernPOSOffline, CloudPOS, HardwareStation and AOS. The developer is not needed to know where the files need to be deployed too.
One-time setup steps
- Make sure you do not have any open files in your current VSTS client. If you do, look at RetailSdk-PaymentIncremental.zip and make sure at least these files are not in edit mode.
- Take the RetailSdk-PaymentIncremental.zip (link is below) and unpack it into the Retail Sdk customization branch (Note: At a future date, these changes will come through an update, at that point a simple code merge will have to be done). Make sure that the top folders of the zip file are being copied into the root of the Retail Sdk ($RetailSdk).
- In Visual Studio, look at the changes and make sure no customizations (to the same files) were overwritten. If they were, merge the files rather than just copy them in. However, the chances are high none of these files were customized.
- Add the payment files from the 3rd party vendor to the Sdk, under the PaymentExternals folder. You should have gotten 3 different folders, and these should be matching the new Sdk folders.
- Do a local verification build. Open a Visual Studio 2015 Developer command window and issue a “msbuild /v:Rebuild” from the top of the Retail Sdk.
- If it built successfully, this part is done.
- After doing the build, verify that $RetailSdk\Packages\AosPaymentsPackage\content.folder\AOSService\Code\WebArtifacts has the files from the $RetailSdk\PaymentExternals\PaymentWebFiles folder.
- Verify, that $RetailSdk\Packages\AosPaymentsPackage\content.folder\AOSService\Code\Assemblies has the files from $RetailSdk\PaymentExternals\IPaymentProcessorAssemblies
- Verify that $RetailSdk\Packages\ModernPOS\bin\Debug\content.folder\CustomizedFiles\ClientBroker has the files from $RetailSdk\PaymentExternals\IPaymentDeviceAssemblies.
- Deploy the packages via runbook and verify functionality (on development or sandbox environment).
- If there are any issues with the payment assemblies themselves (not with packaging or deployment), contact the party that released the files
- Once everything worked (one-time steps and verification with payment files and deployment), submit the changes from the zip file plus the payment files to your VSTS.
There is no difference for deployment of the existing packages. One thing to note is that the new package AOSPaymentPackage must be installed by itself and last. The deployment for production environments is exactly the same (via DSE if Microsoft-hosted). The AosPaymentPackage must be installed last.