Quick Guide: How to customize a Microsoft Dynamics AX for Retail online store

Applies To: Microsoft Dynamics AX 2012 R3

This topic describes how to customize the online store by using SharePoint features and the Visual Studio source-code projects that are included in the Retail SDK. This topic also describes how to deploy customizations in development, test, and production environments. For information about developer prerequisites, including Microsoft Visual Studio, see Set up the development environment for SharePoint 2013.

Before you begin

Use SharePoint features to change the look and feel of the application

SharePoint enables you to customize the user interface of the application. Developers and administrators can edit master pages, change styles, add new pages, and change web part properties, to name a few options. You can perform these tasks in SharePoint or with 3rd party development tools that access SharePoint. It is recommended to use these tools for the initial customization process. For information about modifying web parts, including the Content Search Web Parts that display products in the store, see Edit existing Web Parts in SharePoint 2013.

Use the SDK to change the behavior, look, and feel of the application

The Retail SDK includes the source code of many retail online store features. By examining the source code, you can understand the application and adapt it to meet your needs. For example, you can implement shipping-provider calculations in the Commerce Runtime, add support for a new identity provider, or add more business-related logging to understand what online users are doing at certain stages of the checkout process. All of these changes require you to change source code. The following information describes how to customize the Retail online store by using the Retail SDK and then deploy those changes in different environments.

Install developer tools and features

You must install the Retail SDK, the Retail Online Channel, and the latest Microsoft Dynamics AX 2012 R2 cumulative updates on the SharePoint server before you can customize the Retail online store. If you deployed the Retail online store as described in Install a Retail online store (e-commerce), then you have already installed the Retail Online Channel and the latest cumulative update. Use the following procedure to verify that the server has the required tools, features, and updates for customizing the Retail online store.

1. On the SharePoint server locate the following directories:

   C:\My Documents\Retail SDK

   -and-

   C:\Program Files (x86)\Microsoft Dynamics AX\60\Retail Online Channel

2. If you do not see these folders, then you must install the Retail SDK and the Retail Online Channel by using Microsoft Dynamics AX Setup.exe. For more information, see Install retail components.

3. If you have not done so, download and install the latest cumulative update for Microsoft Dynamics AX 2012 R2.

Prepare your developer environment for signing updated source code

The process of customizing the Retail online store requires that you recompile the source code in the Visual Studio projects. After you recompile, the fully-qualified name of the rebuilt assemblies will be different than the assemblies originally provide by Microsoft. Before you can recompile the assemblies, you must provide a code signing key file (also called a strong name key file) to sign the customized code. If your business has a code signing key file (.snk file), you can reuse this file. If you do not have a code signing key file, Visual Studio can create one for you. You must create a new project and enable code signing. Then, create a second project that references the .dll of the output of the first project. You can locate the thumbprint in the assembly reference of the .csproj file in the second project. Once you have the .snk file, you must do the following:

1. Save the file in the Retail SDK folder and give it a name Name.snk.

2. Edit the UpdateAssemblyIdentities.ps1 file in the Retail SDK folder. You must update the version number and the thumbprint of the key file (lines 97, 98).

3. Update the source code to use the strong name certificate by executing the UpdateAssemblyIdentities.ps1 script. This script can take several minutes to complete.

Use Visual Studio 2012 to customize the Retail Online Store source code projects

Customization of the Retail online sample stores requires Microsoft Office Developer Tools for Visual Studio. Use the following steps to install the tools.

To download the Microsoft Web Platform Installer, see Microsoft Web Platform Installer.

To install Microsoft Office Developer Tools for Visual Studio

1. Open the Web Platform Installer, type SharePoint in the search box, and then press Enter.

2. Select Microsoft Office Developer Tools for Visual Studio 2012.

3. Click Add and then click Install.

The Retail SDK includes the following Visual Studio solution files before AX2012 R3 CU8:

• Services.sln: Use this file to customize source code for the Commerce Run-time. The file is located in the Retail SDK\Commerce Run-Time\Services directory.

• StoreFront.sln: Use this file to customize source code for the Retail online store. The file is located in the Retail SDK\Online Channel\StoreFront directory.

For AX 2012 R3 CU8, the Retail SDK is separated into 2 specific folders:

• Framework: The framework consists of the core E-Commerce platform components for Publishing and Checkout Services. This primarily consists of a core library Publishing and E-Commerce Controllers) and services folder. It also contains the reusable checkout controls

• Clients: There are 2 clients available in CU8. One is the SharePoint online store and the other a simple ASP.net online store. Both the clients use the Framework described above. To use the SharePoint online store, use SharePoint.Storefront.sln.

A typical development scenario might proceed as follows:

1. The developer opens the Services.sln project in Visual Studio, clicks Clean All, customizes the solution, and then clicks Build All.

   Visual Studio creates the output assembly files in the Retail SDK\Commerce Run-time\References directory.

2. The developer opens StoreFront.sln, project in Visual Studio, clicks Clean All, customizes the solution, and then clicks Build All.

   Visual Studio creates the output assembly files in the Retail SDK\Online Channel\References directory.

3. In Visual Studio, the developer right-clicks the StoreFront project node in the StoreFront solution, and then clicks Publish. By default, Visual Studio publishes the updated solution to the C:\Program Files (x86)\Microsoft Dynamics AX\60\Retail Online Channel\StoreFront\ORIGINAL_WSP directory. If this directory does not exist in your development environment, then you must create it.

   The publish process creates a new deployment package which you can deploy in a test environment to verify your changes.

Deploy customizations in a test environment and verify your changes

Use the following procedure to deploy the Retail online store .wsp package you just created in a test environment to verify your customizations.

1. Open the C:\Program Files (x86)\Microsoft Dynamics AX\60\Retail Online Channel\tools\oob-topology.xml file in Microsoft Visual Studio or a text editor, such as Notepad.

2. Search in the oob-topology.xml file for the parameters listed in the following table. Enter the specified value for each parameter.

   Search for	Verify or change with
   <WSPPackage generate="true" deploy="true" retract="true"> <InputFolder>..\ RetailJobs \SP</InputFolder>	Verify that <WSPPackage generate="true"
   <WSPPackage generate="true" deploy="true" retract="true"> <InputFolder>..\Contoso DemoData \SP</InputFolder>	Verify that <WSPPackage generate="true"
   <WSPPackage generate="true" deploy="true" retract="true"> <InputFolder>..\ StoreFront \SP</InputFolder>	Change <WSPPackage generate="true" to “false”

3. From a command prompt, open the directory where the oob-topology file is stored. By default, it is stored here:

   C:\Program Files (x86)\Microsoft Dynamics AX\60\Retail Online Channel\tools

4. Execute the following command:

   powershell .\Generate-WSP.ps1 oob-topology.xml oob-settings.xml

5. After the PowerShell command is finished, update the oob-topology.xml file so that the RetailJobs and DemoData XML nodes specify generate=false and the StoreFront XML node specifies generate=true.

6. Execute the following command:

   powershell .\Prepare-FromWSP.ps1 oob-topology.xml oob-settings.xml

7. After the PowerShell command is finished, execute the following command:

   powershell .\InstallPrereqs-SPFarm.ps1 oob-topology.xml oob-settings.xml

8. After the PowerShell command is finished, execute the following command:

   powershell .\Deploy-FarmSolutions.ps1 oob-topology.xml oob-settings.xml

9. Save your changes in the oob-topology.xml file.

10. Verify all of your changes. For more information, see “Verify deployment” in Install a Retail online store (e-commerce).

Deploy your solution to a production environment

To deploy a customized Retail online store into a production environment, you must complete the processes described in the following table.