Extending Microsoft Dynamics 365 for Operations Cookbook: Create and extend real-world solutions using Dynamics 365 Operations

Microsoft Dynamics AX 2012 underwent a name change in what would have been version 7. The official name is now Microsoft Dynamics 365 for Operations. It isn't just that the version number has been dropped, but it appears to have been adopted into the Microsoft Dynamics 365 product suite. The product is not a component of Microsoft Dynamics 365, which is just a way to group Microsoft's various business solutions. We can't, therefore, shorten the name to Dynamics 365, we will refer the product by either its full name or the abbreviation Operations.

New features will be introduced to Operations as both a continual and cumulative process. There are two main types of update, Platform and Application. Platform updates are similar to the binary updates in prior releases, but also contain AOT elements that are now locked and can no longer be changed. Platform updates can contain changes to the language, and new features have been brought in with each bi-yearly release. When running in the Cloud, Microsoft will periodically release updates to the Platform for you. This is needed, since the it uses Azure SQL Server and they may need to service the platform in order to maintain compatibility to the database server.

Application updates are changes to the other packages that make up the source code of Operations, and can be considered similar to the meta data updates in previous releases of Operations.

This book was started on the May 2016, or Update 1 release and has been updated with each release. The version on publication is Update 5, released in March 2017.

All development work is carried out in conjunction with Visual Studio Team Services or VSTS. It used to be optional, but the implementation process that is managed through Lifecycle Services (LCS) requires that we have a VSTS project linked to it to function to its fullest. This is not just for source control and work management, but it is also used when performing code upgrades.

Please see the following links for further reading on Microsoft Dynamics 365 for Operations:

All development work in Operations is either performed on a development virtual machine hosted in Azure, or a local virtual machine. Each developer will use their own virtual machine. Azure hosted virtual machines are deployed through LCS under your own Azure subscription, and can be used to development, learning, and demonstration. Once, as a customer, a cloud hosted subscription has been bought, you are provided 3 environments as part of that subscription under Microsoft's subscription. These are Build, Sandbox, and Production. The build sever is a OneBox server (all in one virtual machine) that is also labelled Development, but it should always be used as a build server and not for development. The sandbox server is a full environment, with multiple servers using a separate Azure SQL Server. The production environment is the environment that you (as a customer) will go live with. All code must first be deployed to the sandbox before it is applied to live, which this is enforced by LCS - no more 'quick fixes' directly into live, and no access to SQL server for the production environment.

The on premise version of Operations may allow us to bypass some of these rules, but we shouldn't try - these practices of forcing code through a full testing cycle are very important. Waiting a couple of days for a needed feature may be inconvenient, but regression is perceived very negatively by users. During the implementation we ask a lot of the users, they are already busy with their jobs and are being asked to also help with testing new software, so user buy-in to the project is a critical factor, and regression is the most efficient way of eroding the initial excitement of delivering new software.

For local development virtual machines that are often the cheapest option, we will download the virtual machine from Microsoft Connect. This is a website used for many programs at Microsoft, and access is provided to partners and customers.

The terms Visual Studio Team Services and Team Foundation Server (TFS) are often used interchangeably. In Visual Studio, the user interface states that we are connecting to a Team Foundation Server. However, we are actually connecting to VSTS, which is an online service. VSTS is required for Operations development, and that is what we will use.

The project is normally created under the end-user's VSTS site, unless the work is being written as an ISV solution (or a personal development or learning project). The reason for using the client's VSTS system is that LCS is associated with the VSTS site, and support calls created through Cloud-powered support are generated within the associated VSTS. Cloud powered support is an online support solution within LCS that is exposed to the Operations client, allowing users to log support issues with their internal support team.

For up to five users, VSTS is free, and the customer can create many accounts with limited access without charge. These accounts as called stakeholder accounts, and allows the user access to work items, which also allows the users the ability to log support calls from within Operations. For those with an MSDN subscription, the five user limit is not counted.

This process is normally performed as part of the LCS project creation. If this were an implementation project type, the project is created when the customer signs up for Operations. The customer would then invite their Cloud solution provider (Partner) to the project. If this were an internal development project, such as a new vertical solution by an ISV, a Migrate, create solutions, and learn Dynamics 365 for Operations project type would be used.

In either case, we will have an LCS project, which will usually have an Azure VM deployed that acts as a build server.

For simplicity, and to keep the focus on software development, a project of type Migrate, create solutions, and learn Dynamics 365 for Operations was created for the purpose of the example of the book.

How to do it...

To create the project, follow these steps:

1. Navigate to your VSTS site, for example, https://<yourdomain>.visualstudio.com/.
2. Under Recent projects & teams, click on New.
3. Complete the form as shown as follows:

Field	Value
Project name	Unique name, careful to name the projects for easy recognition, and how they are ordered. This is more important for ISVs who may have many projects.
Description	Short description of the project
Process template	Agile
Version control	Team Foundation Version Control

4. Press Create project.

 

 

5. Once complete, you can then navigate to your project and work with VSTS in order to plan your project.
6. To authenticate with LCS, we will need to generate a personal access token; to set this up, click on the control panel (cog) icon, as shown in the following screenshot:

7. This takes you to the control panel, again, on the top-right click on your name and choose Security, as shown in the following screenshot:

8. The personal access tokens option is selected by default; on the right-hand pane, click on Add.
9. On Create a personal access token form, enter a short description, for example, the LCS project name. Set the Expires in field based on how long you would like it to last for.
10. Leaving the Accounts and Authorized scopes fields as default; press Create token.
11. Finally, copy the resultant access code into a safe place; we will need it when we link VSTS to LCS. If we don't, we will have to create a new access token as you can't see it after the web page is closed.

Next, we will need to link the project to our LCS project. If an LCS project is not currently linked to a VSTS project, we get the following message on the left hand side, as shown in the following screenshot:

To configure VSTS for the LCS project, follow these steps:

1. To authenticate with LCS, we will need to generate a personal access token, so from within VSTS.
2. Click on the Setup Visual Studio Team Services button in the Action center dialog box.
3. On the Enter the Visual Studio Team Service site page, enter the URL of our VSTS site into the Visual Studio Team Services site URL field; for example, https://<mysite>.visualstudio.com/.
4. Enter the personal access token generated earlier into the Personal access token field.
5. Press Continue.
6. On the Select the Visual Studio Team Service project page, select the project from the Visual Studio Team Service list.
7. You are then shown the Workitem type mapping list. This allows you to select how to LCS Workitem Type / LCS Workitem Sub Type elements to VSTS Workitem Type elements. Leave this as the default and press Continue.
8. On the final Review and save page, press Save.
9. This takes us back to the main project page and the action center will ask you to authorize the project; click on Authorize.

 

 

10. You will be warned about being redirected to an external site; click on Yes.
11. You may be asked to log on; if so, do it with the account you use for VSTS, which might be your Microsoft account.
12. This will open the Authorize application page from within VSTS, and you will be told that you are allowing Microsoft Dynamics Lifecycle Services to access the VSTS and the specific permissions it will receive. Press Accept.

Each developer has their own development VM, hosted either in Azure or locally. This is by design and is part of the application lifecycle process. Each developer would get the latest code from source control, and then check in their changes according their organization's development methodology. As part of this check in they can link the check-ins. This allows a build to then be created, and we gain a level of traceability since each work item (user story, feature, bug, and so on.) is linked to the check-ins in that build. This also allows test projects to be automatically executed when the build is generated.

How to do it...

To connect Visual Studio to VSTS, follow these steps:

1. Create a folder for your projects, and underneath a subfolder with your initials, or others that make the folder unique, within your team; in my example, I chose C:ProjectsTFS.
2. Start Visual Studio.
3. You will be presented with the licensing page. Use the page to log in to the account used to create the project within VSTS. Which could be either your Microsoft account, or Work (O365) account.
4. On the top toolbar, select Team and then Manage connections.
5. The Team Explorer will open, under default layout, on the right-hand side. On this pane, select Manage Connections | Connect to Team Project:

6. This will open the Connect to Team Foundation Server dialog, in the Select a Team Foundation Server drop-down list and select your VSTS site.
7. Select your project in the lower portion of the dialog, as shown in the following screenshot:

8. After pressingConnect, Visual Studio is connected to your project.
9. We have one final step before we continue; we have to configure our workspace so Visual Studio knows which folders are under source control and how they map to VSTS. On Team Explorer, click on Configure workspace under the Project section. This will show the Configure Workspace section at the top of the Team Explorer.

 

 

10. Do not press Map & Get.
11. Press Advanced....
12. The Edit Workspace dialog will look similar to the following screenshot:

For Operations development, we will need to map a projects folder and the Operations local packages folder (the application source code, or metadata as it is often referred to) to two different folders in VSTS. The Projects folder is the one we created earlier, which was C:ProjectsSB in my case. The Operations local packages folder is C:AOSServicePackagesLocalDirectory.

Note

If you look around the local packages folder, you can see how the relationship between package and Model is actually stored.

 

13. In my case, the project is B05712_AX7_DevelopmentCookbook, so I will configure the dialog as shown in the following screenshot:

14. Press OK.
15. You will then be told that the workspace has been modified, and if you want to get the latest code. Either option has no effect if we are the first developer, but it is a good habit to always press Yes.

When creating a new project, it is usually a new Package and a new Model. This keeps things simple, and there is usually no benefit in separating them. You may wish to create a test project in a different Model in the same solution, but you may not wish to deploy the test projects to live.

There are two types of projects: an extension project and an over-layer project. Over-layering means modifying the source code of Operations, and requires a code upgrade for each application hotfix. Extension projects work on delta changes to the standard object, or using delegates to affect code execution. Extension projects shouldn't need a code upgrade when application hotfixes are applied. Avoidance of over-layering cannot be overstated, in the time this book was being written Platform and Foundation have been locked, meaning that the over-layering must be removed. The ability to write good code through extension has been improved with each release, and with clever design the need to over-layer has been significantly reduced.

We will use extension projects exclusively, in order to to avoid conflicts with future upgrades. They make it possible to service the environment without having to deploy a new build of the custom solution. This is very exciting for ISV solutions, but also very important for VAR and end-user customers.

See the There's more... section for information on the relationship between packages, models and projects.

There's more...

When a solution is designed, it will be done by breaking the solution into packages of functionality. This is a normal design paradigm that has now been implemented (and, to an extent, enforced) within Operations. This means that our solution design will now define the various packages, and how they depend on each other. In the case of Operations, the package is a deployable unit that becomes a distinct DLL.

We can make a hotfix to a package and, technically, deploy it separately to other packages in the solution. Although this is possible, we would normally create a release of packages as a Deployable package. A Deployable package is a collection of one or more packages that contains both the built package code of one or more packages, and the routine required to install them. This process is simplified using a build server that performs the build process for us, executes any tests, and creates Deployable packages that we can then apply to our test environment.

There is a further level within Operations, which is a Model. A Model is a subset of elements, such as classes, within a package and can be used to move code from one development system to another, for example. A Model can only belong to one package, and a Package can contain one or more Models. Each package becomes a DLL, that has to have references added in order to 'see' elements in order packages. Because of this we should use a limited number of packages. As a guide we tend to have one package for the main stream, and one for reporting and business intelligence. To simplify management of development tasks, we tend to have a project per specification / Technical Design Document (TDD), all within the main or reporting packages, simplifying multi-developer projects. Just like working on complex C# projects, we can perform code merges, branching, and shelving within VSTS.

Layers has been a core part of prior releases from its first release, but is no longer that significant. As a partner we still use the VAR layer, and recommend the same guidelines as before to customers as before, but since we avoid over-layering this feature will not be covered in this book.

Note

The dependencies are defined against the Package, not the Model. When we create a project, the project is associated with a Model. It is typical, and desirable, to keep this structure simple and only have one Model (or limited to a few Models) for each package and to give both entities the same name.

The following diagram shows a typical Package, Model, and Project structure:

Note

The ApplicationSuite package is a standard package that we normally always reference, as it contains the majority of the types that we usually need. The arrows indicate the reference direction, showing that it is not possible for the Vehicle management package to see the elements created in the Vehicle management reporting package.

Prefixes and naming conventions

Operations does not use namespaces. Neither packages nor models equate to a namespace. A model simply implies a scope, but all types must be globally unique; even in different models and packages. A name space would allow a class to have the same name as another class in a different namespace.

Therefore, every element must be globally unique by type; this includes models, packages, and every element in the application metadata. So, we will still need prefixes. Even if we create an extension of an element, such as a form, we must change the name so that it is guaranteed to be globally unique.

For example, if we wanted to create an extension of the WHSLoadTable table, it will call the WHSLoadTable.extension object by default. As our customer might want an add-on that also adds fields to this table, we need a want to ensure that the element is unique.

The best way to do this would be to use our prefix, which is Con in our case. To make it obvious of where the element is used, we use the package name as the suffix, for example, WHSLoadTable.ConWHS. There is no official best practice available for this, but the point to remember is that all elements of a type must be globally unique - and extensions are no exception.

Before we can get stuck into writing some code, we need to set up some parameters. Many settings described here are good for all projects, but some you may wish to change, depending on the scenario.

Most projects have some kind of user interface, and therefore we need to display text to the user other than the field names. The best practice method to do this is to use a label file. The label file contains a language specific dictionary of label IDs and the translation.

Standard elements tend to have the legacy label IDs of an @ symbol, followed by a three-digit label ID and a number. This format worked well for the past 15 years, but the prefix was potentially limiting, especially to aid ISVs. Labels are no longer restricted to three digits, which helps Microsoft attain one of its goals of making ISV add-ons easier to write, maintain and adopt.

The choice of how many and which packages need a label file depends on the solution design.

It isn't a terrible idea for an end user customer solution to have one package just for labels that are re-used by each package. This does mean that we run the risk of using a label out of context. You may choose to use a standard label for Name on personal record, only for the label to be changed by the original developer to something specific to the original context, for example, Product name.

We tend to create a label file for each package as this ensures that the package can correct and change labels without worrying about regression in other Models.

ConWHS1=Vehicle type 
 ;ConWHS 
ConWHS2=The type of vehicle 
 ;ConWHS 
VehTransComplete=Complete inspection 
 ;ConWHS 
VehTransCompleteHT=Complete, and finalise the vehicle inspection 
 ;ConWHS