Chapter 5: Visual Studio Integration

CHAPTER 5: VISUAL STUDIO INTEGRATION

Objectives
The objectives are:

• Explore the Application Object Tree (AOT) from Visual Studio.

• Create a project in Visual Studio.
• Write .NET managed code that uses X++ objects.
• Deploy managed code.
• Debug code using Visual Studio.

Introduction
With Visual Studio tools built specifically for Microsoft Dynamics® AX
development, managed code that seamlessly uses elements from the AOT and
interacts with existing Microsoft Dynamics AX business logic can be written.

5-1
Microsoft Official Training Materials for Microsoft Dynamics®
Your use of this content is subject to your current services agreement
Development III in Microsoft Dynamics® AX 2012

Scenario
Isaac, the systems developer, has been asked to write an event handler for a
Microsoft Dynamics AX event. Instead of X++, Isaac has been asked to write
this event handler in managed code, using Visual Studio.

Application Explorer
The Application Explorer in Visual Studio is a representation of the Microsoft
Dynamics AX AOT. It is organized in the same structure as the AOT.

FIGURE 5.1 VISUAL STUDIO APPLICATION EXPLORER

Like other window panes in Visual Studio, it can be toggled between visible and
invisible. To show the Application Explorer, select it from the View menu in
Visual Studio. The Application Explorer can also be docked or undocked, like
other panes in Visual Studio.

After discussing how to create a project, the Application Explorer can be used
to leverage AOT elements within Visual Studio.

5-2
Microsoft Official Training Materials for Microsoft Dynamics®
Your use of this content is subject to your current services agreement
 Chapter 5: Visual Studio Integration

Visual Studio Projects

There are various types of Visual Studio projects that can be used to interact with
Microsoft Dynamics AX. The use of the Application Explorer within Visual
Studio provides a strong Microsoft Dynamics AX developer experience, with
many familiar concepts.

Similar to development projects in Microsoft Dynamics AX, projects in Visual

Studio allow a developer to create a subset of elements, including those from the
AOT, to work with. All AOT elements added to a project in Visual Studio have
knowledge of their metadata in the Microsoft Dynamics AX AOT.

Types of Projects
There are three types of Visual Studio projects that can be used to develop
customizations for Microsoft Dynamics AX:

• Report modeling projects

• Enterprise Portal Web application projects
• Managed code projects

The Report modeling and Enterprise Portal Web application project types
have their own templates provided under the Microsoft Dynamics AX template
group. These topics are more thoroughly covered in the "Reporting in Microsoft
Dynamics AX 2012" and "MorphX and Enterprise Portal Development in
Microsoft Dynamics AX 2012" courses.

Managed code projects

Managed code projects are .NET Class Library projects in Visual Studio that
have Microsoft Dynamics AX elements included.

Create a Managed Code Project

Perform the following steps to create a Managed code project:

1. Open Visual Studio.

2. Click File > New > Project.
3. Select Visual C# and then Windows from the Installed Templates
list.
4. Select Class Library template.
5. Enter a project name into the Name field and then click OK.
6. Verify the project is created and is visible in the Solution Explorer.
7. Save the project.
8. Click Build and then Build Solution.

5-3
Microsoft Official Training Materials for Microsoft Dynamics®
Your use of this content is subject to your current services agreement
Development III in Microsoft Dynamics® AX 2012

9. Right-click on the project in the Solution Explorer and select Add

<Project Name> to AOT.
10. Notice the project icon now has the Microsoft Dynamics icon
incorporated, indicating this project is now connected with the AOT.

NOTE: VB.NET could be used in this procedure, in place of C#.

Add an AOT Element to a Managed Code Project

Once a Managed code project is created in Visual Studio, Microsoft Dynamics
AX elements from the Application Explorer can be added to it. Simply drag an
element from the Application Explorer, into the project in the Solution Explorer.

Once dropped into the Solution Explorer, a node representing the element will be
in the project. These are referred to as proxies.

To demonstrate the connectivity with the AOT, the following code could now be
written in the C# class library.

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;

namespace ClassLibrary1
{
public class Class1
{
public string GetCustomerPaymentMode(string
accountNum,
string
dataAreaId)
{
string paymentMode = String.Empty;
CustTable custTable = new CustTable();

// Search for the customer.

custTable = CustTable.findByCompany(dataAreaId,

accountNum);

if (custTable.Found)
{
// Get the value for the customer's payment
mode.
paymentMode = custTable.PaymMode;
}

return paymentMode;
}
}
}

5-4
Microsoft Official Training Materials for Microsoft Dynamics®
Your use of this content is subject to your current services agreement
 Chapter 5: Visual Studio Integration

This example illustrates how the CustTable element is now used in the C# code.
An object of type CustTable is instantiated and used to fetch a record from the
database. Notice the use of a method on the table object: findByCompany().
Also notice that Visual Studio accepts the use of table fields, like
CustTable.PaymMode, as well as table methods.

Create Event Handlers in Managed Code

In the AOT, you can associate a class method with an event handler. An event
handler is code that runs before the associated method runs or after the associated
method has finished running. The event handler itself is also a class method, and
it can be written in either X++ or managed code.

To create an Event Handler in managed code, perform the following procedure.

This procedure assumes the method that will have its events handled has already
been created in the AOT, in this case, SalesFormLetter.run():

1. Open Visual Studio.

2. Create a Managed Code project.
3. Rename the class to a meaningful name. In the example the class will
be named MyPreEventHandler.
4. Save the project.
5. Build the class by clicking Build and then Build
MyPreEventHandler.
6. Right-click on the project in the Solution Explorer and select Add
<Project Name> to AOT.
7. If the Application Explorer is not visible, open it.
8. In the code editor, open the MyPreEventHandler class and place
the cursor somewhere inside the class.
9. In the Application Explorer, locate the SalesFormLetter class.
Expand it and locate the run method.
10. Right-click the run method and select Add pre event handler.
11. Notice that an event handler method is created, as shown.

// Do not change the name of the event handler method. If

you rename the method, the event handler will not work.
[Microsoft.Dynamics.AX.ManagedInterop.XppClassDefiningEvent
Attribute(@"\Classes\SalesFormLetter")]
static public void PreRun(XppPrePostArgs args)
{

The method created is empty, and ready for the pre-event code to be added. Do
not change the name of the method, or the event handler will not work.

5-5
Microsoft Official Training Materials for Microsoft Dynamics®
Your use of this content is subject to your current services agreement
Development III in Microsoft Dynamics® AX 2012

Deploying Managed Code

For managed code to be executed by the Microsoft Dynamics AX client and
server, it must first be deployed to where it can be executed.

The following are the basic steps for deploying managed code:

1. Build the project.

2. Right-click the project and add it to the AOT.
3. Set the deployment properties for the project.
4. Right-click the project and deploy the project.

The following deployment properties are available in the Properties pane for the
project:

• Deploy to Server
• Deploy to Client
• Deploy to EP
• Deploy to SSRS

The first two properties are described in more detail below.

Deploy to Server
If the Deploy to Server property is set to Yes, the system deploys the project
output (a DLL, for example) by copying it to the server's \bin directory. The
server \bin directory might be found at a file location such as the following:

C:\Program Files\Microsoft Dynamics

AX\60\Server\MicrosoftDynamicsAX\Bin\VSAssemblies

After the managed code has been deployed, the AOS must be restarted so that the
assembly can be loaded by the AOS. If you have hot swapping enabled, the
AOS does not have to be restarted. Hot swapping allows multiple application
domains on a single AOS, allowing new versions of managed code to be
deployed and be immediately available to any new client connections. Hot
swapping can be enabled by following these steps:

1. Open the Microsoft Dynamics Server Configuration Utility by

clicking Start > Administrative Tools > Microsoft Dynamics AX
2012 Server Configuration. This must be run with administrative
credentials.
2. On the Application Object Server tab, select Allow hot swapping
of assemblies when the server is running.
3. Click OK. You will see a prompt that asks whether you want to
restart the AOS service. The change will only take effect after the
AOS is restarted.

5-6
Microsoft Official Training Materials for Microsoft Dynamics®
Your use of this content is subject to your current services agreement
 Chapter 5: Visual Studio Integration

NOTE: Hot swapping should only be enabled in development environments.

Deploy to Client
If the Deploy to Client property is set to Yes, the system deploys the project
output (a DLL, for example) by copying it to the client \bin directory. The client
\bin directory might be found at a file location such as the following:

C:\Program Files (x86)\Microsoft Dynamics AX\60\Client\Bin

Visual Studio Debugging Experience for X++

With a tight integration between X++ and Visual Studio, an integrated debugging
experience is essential for developers. It is possible to use the Visual Studio
debugger to debug managed code that is called from X++. The opposite is also
true. X++ code that is called from managed code can be debugged using the
Microsoft Dynamics AX debugger.

Debugging Managed Code Called from X++

Perform the following procedure to debug managed code called from X++ code.
The procedure continues with the example of the MyPreEventHandler managed
code, on the SalesFormLetter.run() event:

1. Create a job in Microsoft Dynamics AX that executes

SalesFormLetter.run().
2. In Visual Studio, put a breakpoint on a line of code within the
preRun method of the MyPreEventHandler class.
3. Select Debug and then Attach to Process.
4. From the Available Processes field, select the Microsoft Dynamics
AX client process (Ax32.exe) and click Attach. The client process is
selected since the code being debugged runs on the client.
5. In Microsoft Dynamics AX, run the job.
6. The Visual Studio debugger will appear, waiting at the breakpoint.

Debugging X++ Called from Managed Code

Perform the following procedure to debug X++ code called from managed code.

1. Create managed code in Visual Studio that calls a method on a

Microsoft Dynamics AX proxy (table or class).
2. On the Visual Studio project's properties, set Debug Target to
Client and Startup Element to the AOT element that contains the
X++ code you wish to debug. The format of this property should be
"AOT Node\Element Name". For example, Classes\SalesLineType.
Acceptable element types are job, menu item, class and form.

5-7
Microsoft Official Training Materials for Microsoft Dynamics®
Your use of this content is subject to your current services agreement
Development III in Microsoft Dynamics® AX 2012

3. In that startup element in Microsoft Dynamics AX, place a

breakpoint in the X++ code you wish to debug.
4. Press F5 in Visual Studio to debug the managed code.
5. When code execution reaches a breakpoint in X++ code, context will
switch to the Microsoft Dynamics AX debugger.

5-8
Microsoft Official Training Materials for Microsoft Dynamics®
Your use of this content is subject to your current services agreement
 Chapter 5: Visual Studio Integration

Lab 5.1 - Create a Managed Code Project

You have been asked to write business logic for Microsoft Dynamics AX using
managed C# code in Visual Studio.

Scenario

Before any managed code can be written, you need to create a Managed Code
project in Visual Studio that can use the Microsoft Dynamics AX integrated tool
set. Create this managed code project, and add the SalesTableType X++ class to
the project.

Challenge Yourself!

1. Create a managed code project that uses the C# language.

2. Add the SalesTableType X++ class to the project.

Step by Step

1. Open Visual Studio.

2. Click File > New > Project.
3. Select Visual C# and then Windows from the Installed Templates
list.
4. Select Class Library template.
5. Enter a project name into the Name field and then click OK.
6. Verify the project is created and is visible in the Solution Explorer.
7. Save the project.
8. Click Build and then Build Solution.
9. Right-click on the project in the Solution Explorer and select Add
<Project Name> to AOT. Notice the project icon now has the
Microsoft Dynamics icon incorporated, indicating this project is now
connected with the AOT.
10. Open the Application Explorer in Visual Studio.
11. In the Classes node, find the SalesTableType class.
12. Drag the SalesTableType class onto the project in the Solution
Explorer. The class should now appear as a proxy in the projects
contents.

5-9
Microsoft Official Training Materials for Microsoft Dynamics®
Your use of this content is subject to your current services agreement
Development III in Microsoft Dynamics® AX 2012

Lab 5.2 - Create an Event Handler in Managed Code

You have been asked to write an event handler for a Microsoft Dynamics AX
event, using managed C# code in Visual Studio.

Scenario

The event that you have been asked to handle, is the ValidateWrite method on
the SalesTableType (called to validate a SalesTable record before it is written).
You have been asked to create a post-event handler using managed code. You
will also need to create a managed code project to hold this event handler (the
project created in Lab 5.1 can be used for this purpose).

Challenge Yourself!

1. Use the Application Explorer to find the method that needs to be

handled.
2. Create a post-event handler.
3. Ensure the event handler will be deployed on the Server and Client.

Step by Step

1. Open Visual Studio.

2. If you are reusing the project from Lab 5.1, skip to step 4. Otherwise,
create a Managed Code project.
3. Right-click on the project in the Solution Explorer and select Add
<Project Name> to AOT.
4. If the Application Explorer is not visible, open it.
5. In the code editor, open the class and place the cursor somewhere
inside the class.
6. In the Application Explorer, locate the SalesTableType class.
Expand it and locate the validateWrite method.
7. Right click the validateWrite method and select Add post-event
handler.
8. Notice that an event handler method is created in the class.

5-10
Microsoft Official Training Materials for Microsoft Dynamics®
Your use of this content is subject to your current services agreement
 Chapter 5: Visual Studio Integration

Summary
By using the integrated Microsoft Dynamics AX tool set inside Visual Studio,
developers can now write managed code in any .NET language to enhance or
modify Microsoft Dynamics AX business logic. The Application Explorer tool
offers a development environment similar to that within Microsoft Dynamics
AX, making switching between the two easier and more familiar.

5-11
Microsoft Official Training Materials for Microsoft Dynamics®
Your use of this content is subject to your current services agreement
Development III in Microsoft Dynamics® AX 2012

Test Your Knowledge

Test your knowledge with the following questions.

1. What type of Visual Studio projects can be used to integrate with Microsoft
Dynamics AX?

2. What key step in creating a managed code project will connect the project
with the AX tool set within Visual Studio?

3. What four deployment properties are available for a Visual Studio project
that has been added to the Microsoft Dynamics AX AOT?

5-12
Microsoft Official Training Materials for Microsoft Dynamics®
Your use of this content is subject to your current services agreement
 Chapter 5: Visual Studio Integration

4. What needs to happen before the Visual Studio debugger will activate on
breakpoints inside managed code called from the Microsoft Dynamics AX
client or server?

5-13
Microsoft Official Training Materials for Microsoft Dynamics®
Your use of this content is subject to your current services agreement
Development III in Microsoft Dynamics® AX 2012

Quick Interaction: Lessons Learned

Take a moment and write down three key points you have learned from this
chapter

1.

2.

3.

5-14
Microsoft Official Training Materials for Microsoft Dynamics®
Your use of this content is subject to your current services agreement
 Chapter 5: Visual Studio Integration

Solutions
Test Your Knowledge
1. What type of Visual Studio projects can be used to integrate with Microsoft
Dynamics AX?

MODEL ANSWER:

Report modeling projects, Enterprise Portal Web application projects, and

Managed code projects.

2. What key step in creating a managed code project will connect the project
with the AX tool set within Visual Studio?

MODEL ANSWER:

Right-clicking the project and selecting Add <Project Name> to AOT.

3. What four deployment properties are available for a Visual Studio project
that has been added to the Microsoft Dynamics AX AOT?

MODEL ANSWER:

Deploy to Server, Deploy to Client, Deploy to EP, Deploy to SSRS.

4. What needs to happen before the Visual Studio debugger will activate on
breakpoints inside managed code called from the Microsoft Dynamics AX
client or server?

MODEL ANSWER:

The Visual Studio Debugger needs to be attached to either the Server or

Client process for Microsoft Dynamics AX.

5-15
Microsoft Official Training Materials for Microsoft Dynamics®
Your use of this content is subject to your current services agreement
Development III in Microsoft Dynamics® AX 2012

5-16
Microsoft Official Training Materials for Microsoft Dynamics®
Your use of this content is subject to your current services agreement