Programmability

Microsoft Dynamics CRM 4.0

Customizing CRM by Using the Microsoft

Dynamics CRM Developer Toolkit

White Paper

Date: April 2009

Acknowledgements
Initiated and sponsored by the Microsoft Dynamics CRM Engineering for Enterprise
(MS CRM E2) Team, the Microsoft Dynamics CRM Developer Toolkit and this accompanying
documentation was developed in part with support from across the organization and in direct
collaboration with the following:
Key Contributors Technical Reviewers
 Phil Hand (UK MCS) Nirav Shah (CRM Development)
 Jason du Plessis (UK MCS) Steve Jamieson (CRM Development)
Jonas Deibe (SE-MCS Delivery)
Amy Langlois (CRM SDK Team)
The MS CRM E2 Team recognizes their efforts in helping to ensure delivery of an accurate and
comprehensive technical resource in support of the broader CRM community.
MS CRM E2 Contributors
Amir Jafri, Program Manager
Jim Toland, Content Manager
Feedback
Please send comments or suggestions about this document to the MS CRM E2 Team feedback
alias ([email protected]).

Microsoft Dynamics is a line of integrated, adaptable business management solutions that enables you and your
people to make business decisions with greater confidence. Microsoft Dynamics works like and with familiar
Microsoft software, automating and streamlining financial, customer relationship and supply chain processes in a
way that helps you drive business success.
U.S. and Canada Toll Free 1-888-477-7989
Worldwide +1-701-281-6500
www.microsoft.com/dynamics

Legal Notice
The information contained in this document represents the current view of Microsoft Corporation on the issues
discussed as of the date of publication. Because Microsoft must respond to changing market conditions, it
should not be interpreted to be a commitment on the part of Microsoft, and Microsoft cannot guarantee the
accuracy of any information presented after the date of publication.

This White Paper is for informational purposes only. MICROSOFT MAKES NO WARRANTIES, EXPRESS, IMPLIED
OR STATUTORY, AS TO THE INFORMATION IN THIS DOCUMENT.

Complying with all applicable copyright laws is the responsibility of the user. Without limiting the rights under
copyright, no part of this document may be reproduced, stored in or introduced into a retrieval system, or
transmitted in any form or by any means (electronic, mechanical, photocopying, recording, or otherwise), or for
any purpose, without the express written permission of Microsoft Corporation.

Microsoft may have patents, patent applications, trademarks, copyrights, or other intellectual property rights
covering subject matter in this document. Except as expressly provided in any written license agreement from
Microsoft, the furnishing of this document does not give you any license to these patents, trademarks,
copyrights, or other intellectual property.

© 2009 Microsoft Corporation. All rights reserved.

Microsoft, Microsoft Dynamics, the Microsoft Dynamics logo, Visual Studio, and the Visual Studio logo are
trademarks or registered trademarks of the Microsoft group of companies.

All other trademarks are property of their respective owners.

APRIL 2009 CUSTOMIZING CRM BY USING THE MICROSOFT DYNAMICS CRM DEVELOPER TOOLKIT
Contents

Introduction................................................................................................................ 5
Overview of the CRM Developer Toolkit........................................................................... 6
The CRM Solution Framework ..................................................................................... 6
The CRM Explorer ..................................................................................................... 6
Key Benefits for Developers ....................................................................................... 7
View All CRM Entities ............................................................................................. 7
Create and Update CRM Entities .............................................................................. 7
Create a Wrapper Class .......................................................................................... 8
Generate Plug-in Code ........................................................................................... 8
Integrate the Build and Deploy Process .................................................................... 9
Deploy Across Multiple Servers ................................................................................ 9
Installation ............................................................................................................... 10
Preparing for Installation ......................................................................................... 10
Installing the CRM Explorer ...................................................................................... 10
Installing the CRM Solution Framework ...................................................................... 11
Configuring the CRM Explorer ................................................................................... 13
Structure of the CRM Solution Framework ..................................................................... 15
Top-Level Folders ................................................................................................... 15
Guidance Documentation ......................................................................................... 16
Projects in the Core Folder ....................................................................................... 16
BusinessProcesses Project .................................................................................... 16
Configuration Project ........................................................................................... 16
EntityWrappers Project......................................................................................... 17
Plugins Project .................................................................................................... 17
Building the Solution .................................................................................................. 18
TFS Integration ...................................................................................................... 18
Steps Performed During Dev Build ............................................................................ 18
Steps Performed During Daily Build ........................................................................... 19
Continuous Integration Build .................................................................................... 19
Tips for Building the Solution while Developing ........................................................... 19
Packaging................................................................................................................. 20
Deploying Windows Installer Packages across Multiple Servers ......................................... 21
Overview............................................................................................................... 21
Using the Tool........................................................................................................ 21
Configuring a new environment ............................................................................. 22
Importing an existing environment definition........................................................... 26
Upgrade an existing environment .......................................................................... 27
Uninstall an existing environment .......................................................................... 29
Deployment Roles and NodeTargets.xml ................................................................. 30
Environment Files ................................................................................................ 30
Appendix A: Walkthrough - Customizing CRM by Using the CRM Developer Toolkit .............. 32
Scenario ............................................................................................................... 32
Implementation Design ........................................................................................... 32
Implementation Process .......................................................................................... 32
Preparing the development environment................................................................. 32
Creating a backup of the code and CRM customization .............................................. 33
Performing functional customization ....................................................................... 34
Developing a stub Web service .............................................................................. 38
Adding support to simplify invocation of the Web service .......................................... 44

CUSTOMIZING CRM BY USING THE MICROSOFT DYNAMICS CRM DEVELOPER TOOLKIT APRIL 2009
 Developing the post-Retrieve plug-in for the account entity ....................................... 49
Ensuring that financially sensitive data is not persisted ............................................. 53
Appendix B: Walkthrough - Adding a Property ............................................................... 56
Appendix C: Resolving Dev Build Failures ...................................................................... 57

APRIL 2009 CUSTOMIZING CRM BY USING THE MICROSOFT DYNAMICS CRM DEVELOPER TOOLKIT
Introduction
For CRM developers, aligning the engineering delivery and process quality of their CRM
projects can significantly increase overall productivity. In addition, by documenting,
communicating, and following a consistent process for implementing CRM in Enterprise
scenarios, developers can scale projects more quickly and efficiently by adding and ramping
up consultants regardless of their previous experience with any specific project.
To provide developers with the ability to create and manage on-premise CRM solutions in an
integrated Visual Studio environment, the Microsoft Dynamics CRM Engineering for Enterprise
(CRM E2) team initiated and sponsored the development of the Microsoft Dynamics CRM
Developer Toolkit (the “Toolkit”).
Note: The Toolkit is based on components that were initially developed within the Dynamics
CRM MCS team in the UK subsidiary. Those components have been refined over several UK-
based global engagements.
This white paper provides a variety of information about the Toolkit, including:
 An overview of the primary features of the Toolkit
 A detailed listing of Toolkit components
 Instructions for installing and configuring Toolkit
 A sample “walkthrough” that demonstrates how a developer might use the Toolkit to
customize a Microsoft Dynamics CRM implementation to address the requirements of a
specific, real-world business scenario.
Important: The Microsoft Dynamics CRM Developer Toolkit currently supports customization
of on-premise CRM deployments only. This Toolkit and the accompanying documentation are
unsupported and are being provided “as is” by the CRM E2 team to assist developers with
managing and extending their on-premise Microsoft Dynamics CRM implementations.
In addition, the walkthrough sections of this document are intended to illustrate the process
that a developer might use to extend a CRM implementation to accommodate the
requirements of a specific business scenario. The procedural detail (paths, file names, etc.)
provided reflect the sample environment in which the walkthrough occurs, while the inline
graphics are designed to highlight key aspects of the interface rather than to show what a user
should expect to see at any specific point in the development process.
While the process followed in these sections adheres to solution development best practices,
the solution created in the walkthrough represents only one of several options for addressing
the requirements of the scenario.

CUSTOMIZING CRM BY USING THE MICROSOFT DYNAMICS CRM DEVELOPER TOOLKIT APRIL 2009
Overview of the CRM Developer Toolkit
The Microsoft Dynamics CRM Developer Toolkit includes two primary components:
 The CRM Solution Framework, which is designed both to provide a predictable and
repeatable foundation for delivering Enterprise CRM solutions and to reduce the time that
is required to deliver these solutions.
 The CRM Explorer, which is a tool that enables CRM developers to interact with an
existing Dynamics CRM deployment from within Visual Studio.
The following graphic identifies the features of the Toolkit as they appear within the Microsoft
Visual Studio 2008 interface:

The CRM Solution Framework

The CRM Solution Framework is a suite of Visual Studio C# projects that are coupled with CRM
Entity customizations and wrapped with extensible MSBuild–based developer builds and daily
builds. The Framework contains several “pre-canned” projects for the typical tasks that are
required of developers when undertaking most Enterprise-level CRM projects. Several of these
projects have an inheritance model that affords simple and intuitive augmentation, which can
significantly reduce the time required to “jump start” development of new projects.

The CRM Explorer

The CRM Explorer complements the CRM Solution Framework, providing the project factories
required to open and build the solution from within Visual Studio. The Explorer manifests as a
window within Visual Studio 2008 and provides direct access to CRM for creating and editing
business units, security roles, and most importantly, entities. The CRM Explorer is linked to
the solution framework which enables it to intelligently place generated code into the relevant
solution framework project.

APRIL 2009 CUSTOMIZING CRM BY USING THE MICROSOFT DYNAMICS CRM DEVELOPER TOOLKIT
Key Benefits for Developers
The Toolkit has been designed to make it easier for developers to customize, extend, and
maintain an on-premise CRM solution, all from within an integrated Visual Studio environment.
The following sections highlight how a developer would leverage the Toolkit to accomplish
specific development tasks.

View All CRM Entities

The list of entities is dynamically available from the CRM Explorer within Visual Studio 2008.

Create and Update CRM Entities

The Toolkit allows developers and system customizers to create new entities and update
existing entities from within the CRM Explorer experience.

CUSTOMIZING CRM BY USING THE MICROSOFT DYNAMICS CRM DEVELOPER TOOLKIT APRIL 2009
Create a Wrapper Class
A key Toolkit feature is the ability to auto-generate wrapper classes for entities. This exposes
the CRM entities and their corresponding attributes as classes and properties respectively to
enable development of code to interact with the entities.

Generate Plug-in Code

The CRM Explorer enumerates the available Plug-ins for an entity and generates the code
necessary to jumpstart the plug-in development process.

APRIL 2009 CUSTOMIZING CRM BY USING THE MICROSOFT DYNAMICS CRM DEVELOPER TOOLKIT
Integrate the Build and Deploy Process
The build scripts provided with the Toolkit simplify the process of building and deploying a
CRM solution. They prepare the environment, obtain and publish the latest customizations,
perform code analysis, register CRM Plug-ins, deploy the solution and execute Unit Test cases.
Note: This process is described in detail in the “Building the Solution” section.

Deploy Across Multiple Servers

The Deployment Tool provided with the CRM Toolkit assists in deployment and maintenance of
Windows installer packages across multiple environments.

CUSTOMIZING CRM BY USING THE MICROSOFT DYNAMICS CRM DEVELOPER TOOLKIT APRIL 2009
Installation
Installing the Toolkit is a three-phase process:
1. Prepare for installation
2. Install the CRM Explorer
3. Install the CRM Solution Framework
Detailed instructions for installing the Toolkit follow.
Important: These instructions assume that the files required for installation are located in
folders at the root of the C:\ drive as follows:
 C:\CRM Explorer
 C:\CRMSolutionFrameworkTemplate
During installation, be sure to specify the appropriate file locations for your environment.

Preparing for Installation

Prior to installing either component, verify that the computer you intend to install the Toolkit
on meets the following installation requirements:
Software Requirements
 Microsoft Dynamics CRM 4.0 (32-bit)  StyleCop 4.3 or later (full installation,
 Visual Studio Team System 2008 including MSBuild Integration files)
 Visual Studio Team System 2008  .NET 3.5 SP1
Team Explorer
Note: StyleCop is a utility that analyzes C# source code to enforce a set of style and
consistency rules. StyleCop can be run from inside of Visual Studio or integrated into an
MSBuild project. The latest version of StyleCop is available for download from MSDN at
http://code.msdn.microsoft.com/sourceanalysis/Release/ProjectReleases.aspx?ReleaseId=142
5
Important: To better maintain code quality during development, it is recommended to track
code changes via access to a Team Foundation Server (TFS) or another source code control
repository. If you use TFS, you can set up policies that prevent check-in unless all unit test,
code, and style analysis rules pass 100% successfully. For more information about check-in
policies, on MSDN, in the Visual Studio Team System, see Code Analysis Check-in Policies at:
http://msdn.microsoft.com/en-us/library/ms182075.aspx

Installing the CRM Explorer

The CRM Explorer is delivered within a standard Windows Installer Package (.msi). Running
the package installs a Visual Studio 2008 Integration Package, which:
 Enables interaction between Visual Studio 2008 and Microsoft Dynamics CRM 4.0
 Provides the project factories that are necessary for opening and building the solution
template during installation of the CRM Explorer Framework
 Prompts the user for a project name that is used to customize the ProjectName template
solution, including the solution name and namespaces.

10

APRIL 2009 CUSTOMIZING CRM BY USING THE MICROSOFT DYNAMICS CRM DEVELOPER TOOLKIT
To install the CRM Explorer, perform the following steps:
1. At a command prompt, navigate to the folder C:\CRM Explorer, type setup.exe and
then press ENTER.
2. In the CRM Explorer Package Setup wizard, on the Welcome page, click Next.
3. On the Select Installation Folder page, accept the default installation path or specify
an alternate, select Everyone if necessary, and then click Next.
4. On the Confirm Installation page, click Next.
The Installing CRM Explorer Package page displays installation progress.
5. When the CRM Explorer package is successfully installed, on the Installation
Complete page, click Close.

Installing the CRM Solution Framework

The CRM Solution Framework relies on the CRM Explorer Visual Studio Integration Package to
provide the project factories that are necessary for opening and building the solution template.
With the CRM Explorer successfully installed, you can install the CRM Solution Framework.
When you install the CRM Solution Framework, during the preparation phase, the installation
script performs several actions, which are described in the following table.

Action Description
Strong-name key generation Corresponding private and public strong-name
keys are generated and placed in the common
folder; these are referenced by the C# projects
and the MSBuild build scripts.
File content replacement Replaces the ProjectName place holder name
within all solution files and build script files with
the project name provided through the
installation wizard. The longer display name is
also replaced with the user provided display
name for the project while the organization
name is replaced by the name of the
organization for the relevant CRM instance.
File/Folder renaming All files and folders containing the ProjectName
place holder are scanned and the text is
replaced by the project name entered into the
installation wizard.
Unique Install GUID creation Unique GUIDs are created for the WiX template
files; note that GUIDs for components are not
updated – these should be updated manually.

To install the CRM Solution Framework, perform the following steps:

1. At a command prompt, navigate to the folder C:\CRMSolutionFrameworkTemplate, type
setup.cmd and then press ENTER to display the associated command-line syntax.

11

CUSTOMIZING CRM BY USING THE MICROSOFT DYNAMICS CRM DEVELOPER TOOLKIT APRIL 2009
 The variables available in the command-line syntax are described in the following table:
Variable Description
{InstallDir} Path to the directory location from which development work on
the customer ready solution will commence; for directory paths
containing spaces, enclose the entire path in quotation marks.
{ProjectName} Name of the solution and root namespace for all classes.
Note: The Project Name should not contain spaces and must
be Code Analysis compliant.
{Project Long Name} Name used for display purposes within the project installer and
description fields when generated
Note: The Project Long Name should not contain special
characters.
{Organization Name} Name of the organization within the CRM instance; this must
be local to the computer running the CRM Solution Framework.

2. To establish the development environment required to complete Appendix C:

Walkthrough - Customizing CRM by Using the CRM Developer Toolkit, at the command
prompt, type the following text, and then press ENTER:
setup.cmd C:\Projects\MyCrmSolution MyCrmSolution "My CRM Solution"
CRMCONFIG

Note: Avoid copying the command line from this document and pasting the text into
the command prompt window – the quotation mark characters in the document may
not be recognized correctly.
The command prompt window displays progress output as the build script creates the
solution files and folders on disk and performs a number of actions, which are detailed
above. After the program completes successfully, the command prompt window
displays confirmation of the installation and a statement that the set up succeeded.

12

APRIL 2009 CUSTOMIZING CRM BY USING THE MICROSOFT DYNAMICS CRM DEVELOPER TOOLKIT
 3. Close the command prompt window.
Important: The development environment used in the Walkthrough appendix reflects a
standard, non-customized implementation of Microsoft Dynamics CRM 4.0 with an organization
named CRMCONFIG. During installation of the CRM Solution Framework in your environment,
be sure to reference the appropriate CRM organization.
Note that the Toolkit does not require a non-customized version of CRM and is designed to
accommodate customized environments.

Configuring the CRM Explorer

To configure the CRM Developer Toolkit to reference an instance of Microsoft Dynamics CRM
4.0, perform the following steps:
1. In Visual Studio 2008, open the file MyCrmSolution.sln from the folder
C:\Projects\MyCrmSolution\SourceCode\MyCrmSolution.
Note: A security warning appears because the .csproj project files within the solution
have been customized to support delay-signed, strong naming of the output assemblies.
2. In the Security Warning for BusinessProcesses dialog box, select Load project
normally, clear the Ask me for every project in this solution check box, and then
click OK.
3. If necessary, to display the CRM Explorer window within Visual Studio 2008, on the
View menu, point to Other Windows, click CRM Explorer, and then dock the window
in the lower-left corner of the Visual Studio 2008 workspace.

13

CUSTOMIZING CRM BY USING THE MICROSOFT DYNAMICS CRM DEVELOPER TOOLKIT APRIL 2009
 4. To configure the CRM Explorer, in Visual Studio 2008, on the Tools menu, click
Connect to CRM Server.

5. In the Options dialog box, expand CRM Explorer Options and click Server
Connection if necessary, provide the CRM Server name, the CRM Organization name,
and the connection and authentication details associated with your environment, and
then click OK.
The CRM Explorer is now configured to work in your environment

14

APRIL 2009 CUSTOMIZING CRM BY USING THE MICROSOFT DYNAMICS CRM DEVELOPER TOOLKIT
Structure of the CRM Solution Framework
Top-Level Folders
Closely aligned with the various types of work required to extend and customize an Enterprise
CRM solution, the CRM Solution Framework contains eight top-level folders. These folders
appear in the Solution Framework window within the Visual Studio 2008 user interface.
The following table describes the top-level folders in the CRM Solution Framework.

Folder Description
Common A repository for the general items within the solution including common
assembly information, code analysis dictionaries and the public key part
of the strong name.
Core Central to all solutions that require development effort. This folder
contains a number of projects that act as a starting point for creating
business logic, plug-ins and code for interacting with entities.
Customizations Maintains all CRM entity customizations. Although not necessary to store
this as part of a Visual Studio solution, keeping these within the same
folder structure pays dividends for a simple and maintainable automated
build and deployment process.
Integration A place-holder folder that should be used to store projects required to
perform integration to another back-end system, database, or external
webs service. Placing all integration code in this folder ensures that it
clear this code is not part of the core CRM functionality and other
applications/systems that are involved.
ISV Contains any custom web pages or web services that may be required in
order to extend the CRM solution to meet the customer‟s requirements.
Once deployed, These web pages and web services will reside beneath
the ISV web folder provided by CRM and will run under the context of
the user associated with the application pool of the web site unless
specifically coded to do otherwise.
Services Any Windows services required by the customer solution should reside in
this folder. A template scheduling service has been provided which
allows tasks/activities to be invoked on a schedule defined within the
Environment configuration file. For example, if the customer solution
integrated with a back-end data warehouse, the scheduling service could
be tasked with synchronizing data across the systems every hour.
Stubs A placeholder repository for storage of test stubs and reflector pages.
This would typically be required for simulation of requests/responses
from a back-end system not readily available during the development
phase.
Unit Tests A repository for construction of unit tests for the CRM solution. These
unit tests will be invoked as part of the Developer build in order to
ensure the solution remains stable and does not regress prior to check-
in of changes to the code base and/or customizations.
15

CUSTOMIZING CRM BY USING THE MICROSOFT DYNAMICS CRM DEVELOPER TOOLKIT APRIL 2009
Guidance Documentation
Each of the top-level folders contains a +++ Guidance Documentation +++ folder, which
provides pertinent information regarding the relevant logic/code to be contained in the project.
Guidance is also provided on naming conventions for classes and methods based on the
business operation being performed.

Projects in the Core Folder

As mentioned in the preceding table, the Core folder contains a number of projects
(BuildProcesses, Configuration, Entities, and Plugins) that serve as a starting point for creating
business logic, plug-ins, and code for interacting with entities. While each of these projects
can exist individually, most enterprise solutions will require a combination of the projects to
meet the business requirements and separate code in a maintainable manner. The purpose of
each of these projects is detailed below.

BusinessProcesses Project
As a rule, the BusinessProcesses project encapsulates all business logic. The project has three
distinct areas, which are described in the following table:
Area Description
Operations Typically contains “Manager” style classes and methods that apply business
logic across one or more entities.
Populators These are specialized processes, primarily for preparing entities for
presentation. Typically these are invoked by Post-Retrieve plug-ins and
provide the ability to populate attributes on the fly or retrieve data from
another system and subsequently augment the data stored in CRM
Validators Used to perform complex validation of data across entities. If the validation is
part of a wider/larger operation, it is preferable to split out the validation
functionality into separate classes and store within this folder. This will
improve maintainability and promote re-use by other operations.

Configuration Project
The Configuration project manages and provides all settings that are required to be stored
within configuration files for ease of updates and to handle differences between environments
as the customer solution progresses towards production. The template configuration project
defines three areas:
Area Description
Business Settings Settings purely of a business nature (for example specific
business closures or frequency to create new phone call
tasks for a client)
Environment Settings Settings that pertain to the current physical environment
(for example IP addresses and the CRM Service URL,
that pertain to the current physical environment
Instrumentation Settings The level and type of trace output to emit.

Note: Extending the Configuration project with additional configuration areas is not a
significant development effort.
16

APRIL 2009 CUSTOMIZING CRM BY USING THE MICROSOFT DYNAMICS CRM DEVELOPER TOOLKIT
EntityWrappers Project
The EntityWrappers project supports a project factory that enables integration with CRM by
means of examining the CRM metadata and generating code within the project to support the
entities that exist. The core purpose of this project is to expose the CRM entities and their
corresponding attributes as classes and properties respectively to enable code to be developed
to interact with the entities.
The CRM Explorer is aware of this project factory and implements functionality to enable the
developer to select a specific entity and generate the representation of that entity as a class
within the Entity Wrappers project. For each CRM entity that the developer selects, two files
will be created namely: <EntityName>.cs and <EntityName>.Attributes.cs (where
<EntityName> represents the name of the Entity within CRM).
These files split a single class named after the entity through partial classing. The
<EntityName>.Attributes.cs file contains all of the attributes present on the entity at the time
of creation. These are defined as public constants to enable ColumnSets for queries against
CRM to be created. All entities are accessed as Dynamic entities with a property bag for the
attributes; these attributes are wrapped with property accessors providing common and
consistent type safety across Plug-in and other forms of CRM development. This eliminates the
need to perform type conversion (currently required by CRM SDK helper classes.)
Note: A major reason for separating the attributes into a separate file is because of their
volatility throughout the development phase. The <EntityName>.attributes.cs file should not
be manually edited by the developer as it supports re-generation via the CRM Explorer.
The <EntityName>.cs file is based on a class template and is only generated once. Its purpose
is to hook into the pre-canned support within the base classes of the project and to provide an
extension point for the developer to add functionality that is specific to the Entity. For example,
any retrieval methods based on a specific query should be implemented within this file,
including definition of the ColumnSets, i.e. AllLocationFields().
Note: Any logic that requires interaction between two or more distinct entity types should be
developed within the BusinessProcesses project.

Plugins Project
Similarly to the EntityWrappers project, the Plugins project supports a project factory that
enables integration with CRM by means of examining the CRM metadata and generating code
within the project to support plug-ins within the execution pipeline for the desired messages.
The first plug-in that is generated for an entity will result in two files being generated:
<EntityName>Plugin.cs and <EntityName><MessageName>.cs. Subsequent plug-in
generation for other message related to the entity will only result in generation of one file,
specifically for the specified message. <EntityName>Plugin.cs acts as the base class for all
plug-ins related to the entity. It contains code to manipulate elements that are common
across all messages for the entity (such as Pre and Post images).
The <EntityName><MessageName>.cs file is based on a template that acts as a starting point
for plug-in business logic, hooking up all the routine plumbing for a plug-in.

17

CUSTOMIZING CRM BY USING THE MICROSOFT DYNAMICS CRM DEVELOPER TOOLKIT APRIL 2009
Building the Solution
The Solution Framework includes MSBuild scripts to compile both solutions. Two Build Types
are provided: Dev Build and Daily Build. All build scripts are located in the \BuildScripts folder
within the installation folder.
Important: To configure the DevBuild.bat and DailyBuild.bat files for your environment, in
the following file, update the Register element with the appropriate configuration information:
 C:\Projects\MyCrmSolution\SourceCode\MyCrmSolution\Core\Plugins\Register.xml
In addition, if the CRM Web Service in your environment is configured to an address other
than the default (localhost), you must update the following two files by adding the non-
standard CRM Web Service address:
 C:\Projects\MyCrmSolution\SourceCode\MyCrmSolution\Common\MSBuild\MyCrmSolutio
n.Common.Targets
 C:\Projects\MyCrmSolution\SourceCode\MyCrmSolution\Core\Configuration\Configuratio
n\MyCrmSolution.EnvironmentSettings.xml

TFS Integration
The \BuildScripts\BuildTypes folder contains each of the Build Type definitions. Create
matching Build Types in Team Explorer or rename the existing folders. A master TFSBuild.proj
is located in \BuildScripts. All Build Types should use this folder as the location of the
TFSBuild.proj file. This enables the build scripts to be shared amongst build types.

Steps Performed During Dev Build

The Dev Build (or Desktop Build) type is designed to be executed manually on the developers‟
computer to verify that the code is ready to be checked into TFS Source Control.
Note: To ensure that the DevBuild command runs against the latest code in TFS, in the
\BuildScripts\BuildTypes\DevBuild folder, edit the TFSBuild.proj file by changing the value of
SkipGetLatest to false.
The Dev Build performs the following steps:
1. GetLatest
2. Preparation of environment
 MarkCommonTargetsSafe
 Strong-name verification skipping - All built assemblies are delay-signed with public
keys; strong-name verification is turned off so that the assemblies can be tested
within CRM.
 Import CRM Configurations: Configuration files are automatically imported into the
local CRM server and subsequently published.
 Import CRM data maps: Required data maps are imported into the local CRM server.
 Import CRM entity data: Any required data is imported into the CRM server.
3. Compile
 StyleCop/Source Analysis
 Code Analysis
 Registration of CRM Plug-ins
 Delay-signing of assemblies with public key
4. Deployment of Databases
5. Unit Test Execution
18

APRIL 2009 CUSTOMIZING CRM BY USING THE MICROSOFT DYNAMICS CRM DEVELOPER TOOLKIT
Steps Performed During Daily Build
The Daily Build is designed to be executed on a Team Build Server.
Note: CRM is not required on this server, so Daily Build performs no environment preparation.
The Daily Build performs the following steps:
1. As per standard Team Build, it compiles all solutions.
2. During the Package Binaries phases, the installer packages are generated and copied to
a drop location. The Solution Template provides the following installer packages:
 ProjectName.Configuration: Copies and registers all configuration files.
 ProjectName.Core: Deploys the Core set of assemblies.
 ProjectName.ISVPages: Copies web pages into the \ISV sub-folder on the CRM
Server. Binary files are copied into the \bin CRM folder.
 ProjectName.ISVWebServices: Copies web service files into the \ISV sub-folder on
the CRM Server. Binary files are copied into the \bin CRM folder.
 ProjectName.Plugins. Copies and register plug-ins, and any associated files.
 ProjectName.Services: Copies and installs Windows services.
 ProjectName.Stubs: Copies and installs Stub websites that can be used to simulate
external interfaces.

Continuous Integration Build

A Continuous Integration (CI) build is also recommended – particularly for projects with many
team members. This should be triggered by the check-in of a change-set. Typically, a CI build
is very similar to a Daily build and could be considered to be a light weight version thereof.
While it is important to perform the same level of compilation and code quality checks, it is
probably not necessary to include all the packaging steps since the purpose of this Build Type
is to identify errors that will break the daily build and cause both the development and test
teams to lose valuable time in the delivery of the end solution.

Tips for Building the Solution while Developing

Knowing when and how to use each of the available build configurations will aid productivity.
 Debug – The fastest and lightest build, compiles the assemblies in debug mode and is
efficient when checking code syntax.
 DeployToCRM – Similar to debug mode, the assemblies will be built in debug mode; in
addition, customizations and plug-ins will be imported and registered within CRM. Any
custom web pages and web services residing under the ISV folder will also be deployed
to the ISV web folder under the CRM web site. This configuration is effective for
debugging against your local CRM instance. Plug-ins will be registered in synchronous
mode whatever you have specified within the register.xml file to simplify debugging.
 Release – Compiles the assemblies in release mode and executes static code and style
analysis. All warnings will be treated as errors which signify that this configuration is
effective in readiness for a check-in to your source control system.
 DevBuild (from the command –line). This build is the closest match to a CI or Daily build.
All code is compiled in release mode, static code and style analysis rules are executed.
Customizations and plug-ins will be imported and registered within CRM. Any custom web
pages and web services residing under the ISV folder will also be deployed to the ISV
web folder under the CRM web site.

19

CUSTOMIZING CRM BY USING THE MICROSOFT DYNAMICS CRM DEVELOPER TOOLKIT APRIL 2009
Packaging
All packaging scripts are stored under \Main\BuildScripts\Packaging. The Daily Build executes
a set of msbuild scripts that will generate the following set of Windows Installer Packages.

Package Installer Actions

Configuration Role
ProjectName.Configuration.msi  Import the Entities
CRMServer Role
ProjectName.Core.msi 1. Installs EnvironmentSettings.xml and
ProjectName.BusinessSettings.xml configuration file
into the folder C:\Program
Files\ProjectName\Core\Configurations
2. Modifies the configuration file according to the
properties specified in the Rig Template settings.
3. Places shared assemblies into the Global Assembly
Cache (GAC).
ProjectName.Plugins.msi 1. Contains the file ProjectName.Plugins.dll, which is
placed into the Microsoft Dynamics CRM assembly
folder e.g. C:\Program Files\Microsoft Dynamics
CRM\Server\bin\assembly.
2. Registers the plug-in steps contained within the
assembly.
ProjectName.Services.msi  Installs file and register Windows NT Service.
ProjectName.Stubs.msi  Installs files and creates website and virtual directory
for external end-point simulation.
ProjectName.ISVPages.msi  Copies the files packaged from the
ISV\ProjectName.Websites project to the CRM Web
folder, typically C:\Inetpub\wwwroot\ISV folder.
Binaries files are copied into the \bin folder.
ProjectName.ISVWebServices.msi  Copies the files packaged from the
ISV\ProjectName.Webservices project to the CRM
Web folder, typically C:\Inetpub\wwwroot\ISV folder.
Binaries files are copied into the \bin folder.

20

APRIL 2009 CUSTOMIZING CRM BY USING THE MICROSOFT DYNAMICS CRM DEVELOPER TOOLKIT
Deploying Windows Installer Packages across Multiple Servers
Overview
The Deployment tool provided assists in deployment and maintenance of Windows installer
packages within multiple environments. Windows installer Packages can be grouped within
Physical Server roles and these can then be mapped onto the physical servers for deployment
within each defined Environment. To allow environment specific customization within the
Windows install Packages, the tool will inject environment-specific properties into each
package prior to deployment. The Windows Installers used are simple implementation,
making use of MSBuild tasks to configure the environment; however any Windows Installer
Package is supported.
This tool is not a stand-alone product, nor is it officially supported; it is provided “as is” to
assist developers working in environments that do not include an automated deployment
mechanism.
Important: The Deployment tool has the following known issues:
 Do not run the tool from within a folder with a name that contains spaces – the tool does
not support these folders.
 The account provided in the Environment .proj files must have Administrator rights on
each of the local servers and be a user within CRM belonging to the System Administrator
group. The password of this account is required and is not obfuscated.
 On the Save Project page, you MUST specify to save the file in same folder as
deploy.exe.

Using the Tool

In Windows Explorer, navigate to the folder containing the executable file, and then double-
click deploy.exe.
The initial page of the My CRM Solution Deployment wizard appears.

Important: The initial page of the wizard displays the version of the build that is currently
being installed. Be sure to verify that the intended version is being installed.
21

CUSTOMIZING CRM BY USING THE MICROSOFT DYNAMICS CRM DEVELOPER TOOLKIT APRIL 2009
Configuring a new environment
To use the wizard to configure a new environment, perform the following steps:
1. On the Welcome page, verify that Configure a new environment is selected, and
then click Next.

2. On the Sever Roles page, click Add to add a new server.

3. Continue to add servers and roles as necessary to define the environment.
Note – Keep in mind the following points:
 The order of Server Roles is important – any pre-requisites should appear first in
the role list.
 Configuration needs to only be installed only a single CRM server as it applies
configuration into the CRM database.
4. To continue, click Next.

5. On the Deployment Settings page, specify the shared folder and local drive to map
on the remote server (typically these would be as defined above), and then click Next.
22

APRIL 2009 CUSTOMIZING CRM BY USING THE MICROSOFT DYNAMICS CRM DEVELOPER TOOLKIT
 6. On the Installation Properties page, specify environment-specific settings, and then
click Next.
Note: A brief description of each property appears at the bottom of the dialog box to
assist the user in selecting these values. Values from another environment can be
imported as a starting point by clicking Import.

7. In the Save As dialog box, specify the location and name for the newly generated file,
and then click Save.
Important: The project file MUST be saved in the same folder as is the deploy.exe file
to run properly. The project file can be stored in RigTemplates if the file is to be used
for future deployments.
23

CUSTOMIZING CRM BY USING THE MICROSOFT DYNAMICS CRM DEVELOPER TOOLKIT APRIL 2009
 8. On the Save Project page, click Next.
9. On the Save and Deploy page, select one of the following options, and then click Next.
 Save the project and exit – to use the file at a later point
 Save the project and deploy it now - to deploy the project immediately.

10. On the Confirm Actions page, verify the server names and roles, and then click Next
to begin deployment.
The Installing page will display the progression of the installation process - failures will
be marked with a red cross, successful installations with a green tick.

24

APRIL 2009 CUSTOMIZING CRM BY USING THE MICROSOFT DYNAMICS CRM DEVELOPER TOOLKIT
 11. On the Installing page:
 For successful installations, click Next, and then click Finish.
 For unsuccessful installations:
a. Click Details for additional information about the problems encountered.

b. In the View Output dialog box, analyze the output, and click on View
Log Files to review the detailed Windows Installer logs.
c. Click Close, and then on the Installing page, click Back.
d. Attempt a reinstallation, this time, specifying to ignore uninstall failures.
Note: You can uncheck the uninstall and reinstall of roles that were
successfully installed during the initial installation process.

25

CUSTOMIZING CRM BY USING THE MICROSOFT DYNAMICS CRM DEVELOPER TOOLKIT APRIL 2009
Importing an existing environment definition
To use the wizard to import an existing environment definition, perform the following steps:
1. On the Welcome page, select Import an existing environment definition, and then
click Next.

2. On the Import Project page, specify the path and name of the project file and the
corresponding properties file (located in the \RigTemplates folder), and then click Next.

3. On the Server Roles page, verify that the server roles are correct (o changes should
be required), and then click Next to continue.
4. On the Deployment Settings page, verify the settings (no changed should be
required), and then click Next to continue.
5. On the Installation Properties page, verify the properties (no changes should be
required) and then click Next to continue.
6. On the Save Project page, click Browse.
26

APRIL 2009 CUSTOMIZING CRM BY USING THE MICROSOFT DYNAMICS CRM DEVELOPER TOOLKIT
 7. In the Save As dialog box, specify the file to save the newly generated file in the same
folder as deploy.exe to execute the file name, and then click Save.
Note: You can also save file in RigTemplates if you intend to use the file for future
deployments.
8. On the Save Project Page, click Next to continue.
9. On the Save and Deploy: page, select Save the project and exit if the project file is
to be used later or select Save the project and deploy it now to deploy immediately,
and then click Next to continue.
10. On the Confirm Actions: page, verify the server names and roles, and click Next to
begin deployment.
The Installing page displays the progress of the installation; failures will be marked
with a red cross, and successful installations will be marked with a green tick.
12. On the Installing page:
 For successful installations, click Next, and then click Finish.
 For unsuccessful installations, click Details.
11. Analyze the output, as well as click on View Log Files to review the detailed Windows
Installer logs. Click Close and click Back to attempt a reinstall. This time, ensure that
ignore uninstall failures is ticked. You can uncheck the uninstall and reinstall of roles
that were successfully installed.

Upgrade an existing environment

To use the wizard to upgrade an existing environment to the latest version, perform the
following steps:
1. On the Welcome page, select Upgrade an existing environment, and then click
Next.

2. On the Select Existing Project page, select a recent project in the list, or if not
present, click Browse and select the environment .proj file saved within the same
folder as Deploy.exe, and then click Next to continue.

27

CUSTOMIZING CRM BY USING THE MICROSOFT DYNAMICS CRM DEVELOPER TOOLKIT APRIL 2009
 3. On the Confirm Actions page, verify the server names and roles, and click Next to
begin deployment.

The Installing page displays the progress of the installation; failures will be marked
with a red cross, and successful installations will be marked with a green tick.
4. On the Installing page:
 For successful installations, click Next, and then click Finish.
 For unsuccessful installations, click Details.
5. Analyze the output, as well as click on View Log Files to review the detailed Windows
Installer logs. Click Close and click Back to attempt a reinstall. This time, ensure that
ignore uninstall failures is ticked. You can uncheck the uninstall and reinstall of roles
that were successfully installed.

28

APRIL 2009 CUSTOMIZING CRM BY USING THE MICROSOFT DYNAMICS CRM DEVELOPER TOOLKIT
Uninstall an existing environment
To use the wizard to uninstall an existing environment, perform the following steps:
1. On the Welcome page, select Uninstall an existing environment, and then click
Next.

2. On the Select Existing Project: page, select a recent project in the list, or if not
present, click Browse and select the environment .proj file saved within the same
folder as Deploy.exe, and then click Next to continue.

3. On the Confirm Actions page, verify the server names and roles, and then click Next
to begin deployment.

29

CUSTOMIZING CRM BY USING THE MICROSOFT DYNAMICS CRM DEVELOPER TOOLKIT APRIL 2009
 The Installing page displays the progress of the installation; failures will be marked
with a red cross, and successful installations will be marked with a green tick.
4. On the Installing page:
 For successful installations, click Next, and then click Finish.
 For unsuccessful installations, click Details.
5. Analyze the output, as well as click on View Log Files to review the detailed Windows
Installer logs. Click Close and click Back to attempt a reinstall. This time, ensure that
ignore uninstall failures is ticked. You can uncheck the uninstall and reinstall of roles
that were successfully installed.

Deployment Roles and NodeTargets.xml

The tool allows the definition of a set of roles. These are presented to the user when defining a
new environment. The underlying set of windows installer packages are abstracted from the
user. The roles can be installed on the same, and can be regarded as a collection of related
windows installer packages. This collection of packages can only be removed/added in entirety
– individual packages would need to be removed and added manually.

Environment Files
For each environment that an application is to be installed into, a .proj and .xml file is required.
The .proj file defines which servers the roles are installed onto, and the logon credentials.
The .xml files specify the set of properties that will be configured during installation.

CRM Setting Description

INSTALL_ROOT_DRIVE Root drive into which install the application
MACHINEKEY_VALIDATION Type of encryption to use when validating machinekey
MACHINEKEY_VALIDATIONKEY Shared machine validation key
MACHINEKEY_DECRYPTION Ttype of encryption to use when decrypting machine key
MACHINEKEY_DECRYPTIONKEY Shared machine decryption key

30

APRIL 2009 CUSTOMIZING CRM BY USING THE MICROSOFT DYNAMICS CRM DEVELOPER TOOLKIT
CRM Setting Description
CRMSVC_SERVER Server name to connect CRM Service on
CRMSVC_URL Full Web Service URL to use when connecting to CRM
Service
CRM_ORG_NAME Organization to publish/import to
META_SERVER Server name to connect CRM Metadata Service on
CRM_META_URL Full Web Service URL to use when connecting to CRM
Metadata Service
CRM_AUTH_TYPE Authentication type to use when connecting to CRM via the
CRM Service
CRM_USE_DEFAULT_CRED Flag to indicate if default credentials should be used
CRM_SQL_INSTANCE Name of the CRM SQL Server instance
CRM_CONNECT Connection string to use when connecting to CRM Database
CRMSVC_IMPORT_TIMEOUT Timeout (in milliseconds) on Importing Customizations
CRMSVC_IMPORT_BATCHSIZE Number of entities to import together in a batch
CRMSVC_SOLUTION_TIMEOUT Timeout (in milliseconds) on Publish Plug-in Solutions
CRM_SVC_TIMEOUT Timeout (in milliseconds) for the MSCRMServices; use only
if required
OPS_APP_EVENTLOG_ACE Grant access to users to event log defined by ACE string
BATCH_USER User identity to use for the BatchExeuction Service; identity
must have access to CRM and External Data Service
BATCH_PASSWORD User identity password to use for the BatchExeuction
Service
BATCH_MACHINE Machine name that the BatchExeuction Service should start
on startup; set to empty if the service should not be started
BATCH_STARTUPMODE Startup mode for the BatchExecution Service; acceptable
values are Automatic or Manual
BATCH_EXECUTIONPERIOD Time (in seconds) between executions of the service
TESTSTUB_SITENAME Web site name; thedefault is Test Stubs
TESTSTUB_APPOOLID Application Pool Id to use for stubs; the default is
DefaultAppPool
TESTSTUB_AUTHFLAGS Authentication mechanism to use on the Stubs site, the
default is NTLM

31

CUSTOMIZING CRM BY USING THE MICROSOFT DYNAMICS CRM DEVELOPER TOOLKIT APRIL 2009
Appendix A: Walkthrough - Customizing CRM by Using the CRM
Developer Toolkit
Scenario
A major investment bank requires a CRM implementation that will track foreign currency
exchange trades for their clients. One requirement of the solution is to include a client‟s
trading balance on their account form. The trading balance is sourced from a data mart that
aggregates the bank‟s global branches, spanning multiple markets into a single consolidated
repository. To accommodate the bank‟s strict regulations and classification of the CRM solution,
this financially sensitive data must not be persisted within CRM.

Implementation Design
The technical architect on your project team designed an implementation to address the
bank‟s requirements. The initial design considered the option of embedding an IFrame to
display a custom web page with the trading balance. However, while this would have
addressed the bank‟s requirement that financially sensitive data not persist within CRM, the
option was ultimately ruled out because the final implementation would have required various
plug-ins and many of those would have needed to react to the trading balance.
The final design indicates that a post-retrieve plug-in on the account entity will make a call to
an existing web service that exposes the trading balance. This plug-in will then populate a
„dummy‟ trading balance attribute on the account entity and display it on the account form.

Implementation Process
To implement the final design, the project team defines the following, high-level process:
1. Prepare the development environment
2. Create a backup of the code and CRM customization
3. Perform functional customization
4. Develop a stub Web service
5. Add support to simplify invocation of the Web service
6. Develop the post-Retrieve plug-in for the account entity
7. Ensure that financially sensitive data is not persisted
Important: For the purposes of this walkthrough, the development environment reflects a
standard, non-customized implementation of Microsoft Dynamics CRM 4.0 with an organization
named CRMCONFIG.

Preparing the development environment

Referring to the Installation and Building the Solution sections of this document, the project
team verifies that the development computer meets the Toolkit installation requirements.
After installing the CRM Explorer and the CRM Solution Framework, the project team runs a
local developer build to prepare the solution framework template for building and deploying.
Running a local developer build, compiles the code, strong names it, deploys several
assemblies to the Global Assemble Cache (GAC), and ultimately (when the developer has
created them) deploys the plug-ins and entity customizations.

32

APRIL 2009 CUSTOMIZING CRM BY USING THE MICROSOFT DYNAMICS CRM DEVELOPER TOOLKIT
To run a local developer build, perform the following steps:
1. At a Visual Studio 2008 command prompt, navigate to the folder
C:\Projects\MyCrmSolution, type devbuild.bat and then press ENTER.
2. When the program finishes running, in the Visual Studio2008 Command Prompt window,
review the confirmation of successful completion, as well as the warning text (in yellow),
which identifies that the unit tests have not passed successfully.

This warning indicates that the solution framework template does not include any tests.
Users should create their own tests, which should reflect the specific requirements of
their development environments. Note that any tests that users define will run
automatically to ensure that build quality does not regress during solution development.
The solution framework template is now ready to build and deploy.
3. Close the Visual Studio2008 Command Prompt window.

Creating a backup of the code and CRM customization

Before beginning to customize a CRM implementation, it is important to create a backup of the
code and CRM customizations in the existing environment.
1. Export all Microsoft Dynamics CRM 4.0 customizations to a zip file named
customizations.zip, replacing the file of the same name in the following folder:
C:\Projects\MyCrmSolution\SourceCode\MyCrmSolution\Customizations\Base
This backup of initial configuration will serve as a baseline against which future versions
of the code can be compared to identify specific changes that have been made.
2. Export all Microsoft Dynamics CRM 4.0 customizations to a zip file named All.zip,
replacing the file of the same name in the following folder:
C:\Projects\MyCrmSolution\SourceCode\MyCrmSolution\Customizations\Entities
The All.zip file is used to deploy (import and publish) the customizations to the solution
on each environment (i.e. development computer, test rigs, staging, and production).

33

CUSTOMIZING CRM BY USING THE MICROSOFT DYNAMICS CRM DEVELOPER TOOLKIT APRIL 2009
 The MSBuild projects that are used to build the Solution Framework have been
developed to be aware of the All.zip file. This enables the Developer Build and Daily
Build that execute the MSBuild projects to include the customizations within the
packaging process for the .msi installer file. Ultimately the .msi file can subsequently be
used to import and publish the customizations into the Microsoft Dynamics CRM 4.0
target instance in addition to deploying the binaries and other assets.

Performing functional customization

The first step in customization for this implementation is to edit and customize the account
entity, and then to generate the associated code for it.
1. In Visual Studio 2008, open the file MyCrmSolution.sln from the folder
C:\Projects\MyCrmSolution\SourceCode\MyCrmSolution.
2. When prompted with a Security Warning dialog, select Load project normally,
deselect Ask me for every project in this solution, and then click OK.
Note: The security warning is a result of the customization of the .csproj project files
within the solution to support delay-signed, strong naming of the output assemblies.
3. Familiarize yourself with the solution and project structure, referring as necessary to
the Structure of the CRM Solution Framework section of this document.

4. To configure the CRM Explorer to work with the local CRM instance, in Visual
Studio 2008, on the Tools menu, click Connect to CRM Server.

34

APRIL 2009 CUSTOMIZING CRM BY USING THE MICROSOFT DYNAMICS CRM DEVELOPER TOOLKIT
 5. In the Options dialog box, expand CRM Explorer Options and click Server
Connection if necessary, provide the CRM Server name, the CRM Organization name,
and the connection and authentication details associated with your environment, and
then click OK.
Note: If the CRM Explorer window is currently displayed, it will now update to display
the Organization name, Business Units and Entities.
6. If the CRM Explorer window does not display within Visual Studio 2008, on the View
menu, point to Other Windows, click CRM Explorer, and then dock the window in the
lower-left corner of the Visual Studio 2008 workspace.
7. In the CRM Explorer window, expand Entities, right-click account, and then click
Edit (Browser).

8. In the Entity: Account window, under Details, click Attributes, and then click New.
35

CUSTOMIZING CRM BY USING THE MICROSOFT DYNAMICS CRM DEVELOPER TOOLKIT APRIL 2009
 9. In the Attribute: New for Account dialog box, specify the display name as Trading
Balance and the type as money, and then save and close the attribute.
10. In the Entity: Account window, under Details, click on Forms and Views, and then,
under Name, double-click Form.

11. In the Form: Account window, under Common Tasks, click Add Fields.
36

APRIL 2009 CUSTOMIZING CRM BY USING THE MICROSOFT DYNAMICS CRM DEVELOPER TOOLKIT
 12. In the Add Fields dialog box, add the Trading Balance attribute to the Account
Information section of the General tab, and then click OK,
13. Save and close the form, and then close the Entity: Account window.
14. In Visual Studio 2008, in the CRM Explorer window, under Entities, right-click
account, and then click Generate wrapper class.
Note: Code generation may take several moments to complete.

37

CUSTOMIZING CRM BY USING THE MICROSOFT DYNAMICS CRM DEVELOPER TOOLKIT APRIL 2009
 When you generate the wrapper class for the account entity, two files are added to the
EntityWrappers project:
 Account.cs - Presented within Visual Studio, this file contains a partial class named
Account as well as generated code to retrieve an entity instance. The file also
initializes the base class from which it inherits.
 Account.Attributes.cs - Contains all attributes for the entity, including the Trading
Balance attribute that was created earlier. The Trading Balance attribute was
retrieved even though the entity has not yet been published. This allows a
developer to immediately start developing code against a CRM instance before
customization changes are completed and published by a functional Configrator.
Note: Do not add code to the Account.Attributes.cs file, as the contents of the file
will be deleted (including the code that one might add) and regenerated.
Regeneration of the attributes wrapper file allows changes to entity attributes to
easily be synchronized and re-generated in code when they change in CRM.
Regeneration is achieved by pointing to the entity and selecting Regenerate
wrapper class on the context menu from within the CRM Explorer.
15. In the CRM Explorer window, under Entities, right-click account, and then click
Publish.
The new attribute is now created and published.
From a functional perspective, all that remains is to maintain configuration control by
exporting the customizations from CRM and storing them in the source control
repository.
16. In the CRM Explorer window, right-click Entities, and then click Export, specifying to
save the file as All.zip in the following folder:
C:\Projects\MyCrmSolution\SourceCode\MyCrmSolution\Customizations\Entities\
Important: If necessary, check out the file All.zip before attempting to overwrite it.

Developing a stub Web service

At this point, the Trading Balance attribute must be populated. The suggested implementation
outlined previously indicates that data from a Web service will augment the account data that
is stored within CRM. However, this Web service is only available within the staging and
production environments.
Because the development environment is offsite with no access to the live Web service, the
developer must add a stub of the Web service that can be called to return the value of the
Trading Balance attribute. The developer can use WSDL to create a stub Web service that
essentially contains the interface of the Web method and reflects a value to the caller.
Using this approach allows solution development to move forward without the need to focus
on integration until the solution is ready.

38

APRIL 2009 CUSTOMIZING CRM BY USING THE MICROSOFT DYNAMICS CRM DEVELOPER TOOLKIT
To develop the stub Web service required for the development environment, perform the
following steps:
1. In the Solution Explorer window, right-click on the Stubs folder, point to Add, and
then click on New Project.

2. In the Add New Project dialog box, under Templates, click ASP.NET Web Service
Application, specify the project name as TradingService, update the path in the
Location text box to point to the Stubs folder, and then click OK.
3. In the Solution Explorer window, under TradingService, rename the file
Service1.asmx as TradingService.asmx, and then globally replace all instances of
Service1 throughout the solution with TradingService.
4. Replace the Web method HelloWorld with the following:
[WebMethod]
public decimal GetTradingBalance()
{
return new decimal (1000);
}
The build process defined in DevBuild.bat is yet not aware of the TradingService Web
service stub. Enabling automated deployment of stubs as part of the build process
requires a modification to the Environment.properties file.

5. In Visual Studio 2008, open the file Environment.properties from the folder
C:\Projects\MyCrmSolution\BuildScripts\BuildTypes\DevBuild
6. In the file, change the value of the <CreateTestStubWebSite> element to true.

39

CUSTOMIZING CRM BY USING THE MICROSOFT DYNAMICS CRM DEVELOPER TOOLKIT APRIL 2009
 7. Replace the TestStub placeholder name with TradingService (the Web Service project
you created) for the following:
 Include attribute associated with the WebVirtualDirectories element
 Text associated with the Path element
 Text associated with the WebAppName element

8. At a Visual Studio 2008 command prompt, navigate to the folder

C:\Projects\MyCrmSolution, type devbuild.bat and then press ENTER to run a local
developer build.

9. In the Solution Explorer window, under Stubs, right-click TradingService, click

Properties, and then, in the left hand navigation section, click Web.

40

APRIL 2009 CUSTOMIZING CRM BY USING THE MICROSOFT DYNAMICS CRM DEVELOPER TOOLKIT
 10. On the Web tab section, under Servers, select Use Local IIS Web server if
necessary, in the Project Url text box, type http://localhost:83/TradingService
and then save the file.
11. To test the functionality of the stub Web service, in a Web browser, navigate to the
following URL:
http://localhost:83/TradingService/TradingService.asmx

12. On the TradingService page, click GetTradingBalance.

13. Under GetTradingBalance, click Invoke.

The resulting XML string is displayed.

Notice that the decimal tag is populated with the value 1000.
41

CUSTOMIZING CRM BY USING THE MICROSOFT DYNAMICS CRM DEVELOPER TOOLKIT APRIL 2009
 To be able to use the Web service easily within different environments, various details
about the service must be stored within the configuration.
14. In the Solution Explorer window, expand the Core folder if necessary, expand the
Configuration project, right-click on the Environment sub-folder, point to Add, and then
click Class.

15. In the Add New Item dialog box, specify the file name as TradingServiceElement.cs,
and then click Add.
16. In Visual Studio 2008, on the TradingServiceElement.cs tab, modify the contents of
the file by adding a file header (to accommodate the style analysis rules) and then
replacing the contents of the file with the following text:
namespace MyCrmSolution.Core.Configuration.Environment
{
using System;
using System.Configuration;

/// <summary>
/// Custom configuration section for the TradingService
/// settings.
/// </summary>
public sealed class TradingServiceElement : ConfigurationElement
{
/// <summary>
/// Gets or sets the URL for the Trading Service.
/// </summary>
/// <value>The URL for the Trading Service.</value>
[ConfigurationProperty("Url", IsRequired = true)]
public Uri Url
{
get
{
return new Uri(this["Url"].ToString());
}

set
{
42

APRIL 2009 CUSTOMIZING CRM BY USING THE MICROSOFT DYNAMICS CRM DEVELOPER TOOLKIT
 this["Url"] = value.ToString();
}
}
}
}
17. In the Solution Explorer window, in the Environment sub-folder, open the file
EnvironmentSettings.cs, and then add the following property accessor:
/// <summary>
/// Gets the configuration property for TradingService settings.
/// </summary>
[ConfigurationProperty("TradingService")]
public TradingServiceElement TradingService
{
get
{
return this["TradingService"] as TradingServiceElement;
}
}
18. In the Configuration sub-folder, open the file MyCrmSolution.EnvironmentSettings.xml,
and then, after the CrmService element, add the following xml element:
<TradingService Url="http://localhost:83/TradingService/TradingService.asmx" />

19. At a Visual Studio 2008 command prompt, navigate to the folder

C:\Projects\MyCrmSolution, type devbuild.bat and then press ENTER to run a local
developer build on the Configuration project to ensure that there are no compilation
issues.
43

CUSTOMIZING CRM BY USING THE MICROSOFT DYNAMICS CRM DEVELOPER TOOLKIT APRIL 2009
Adding support to simplify invocation of the Web service
Before implementing the Web service plug-in, a method must be added within the
BusinessProcesses project that will enable invocation of the Trading Balance Web service.
According to the suggested implementation, the interaction with the external Web service will
be controlled from code within a project that resides in the Integration folder.
To add support to simplify invocation of the Web service, perform the following steps:
1. In the Solution Explorer window, in the Integration folder, add a new C# class library
project named BackEndTradingSystem.

2. In the BackEndTradingSystem project, delete the file Class1.cs.

3. In the Solution Explorer window, expand Properties, open the file AssemblyInfo.cs,
and then delete all attributes declared for the AssemblyDescription element.
4. Right-click References, click Add Service Reference, and then, in the Add Service
Reference dialog box, click Advanced.
5. In the Service Reference Settings dialog box, click Add Web Reference.
6. In the Add Web Reference dialog box, in the URL text box, type the following text
(the path to the TradingService stub), and then click Go:
http://localhost:83/TradingService.asmx

44

APRIL 2009 CUSTOMIZING CRM BY USING THE MICROSOFT DYNAMICS CRM DEVELOPER TOOLKIT
 7. In the Web reference name text box, type BackEndTradingSystem and then click
Add Reference.

8. In the Solution Explorer window, right-click BackEndTradingSystem, and then click

Unload Project.
9. To ensure that strong naming will occur correctly, right-click BackEndTradingSystem,
click Edit BackEndTradingSystem.csproj, and then edit the project file by adding the
following to the end of the file:
<Import
Project = "$(SolutionRoot)\Common\MSBuild\MyCrmSolution.Common.targets"
Condition =
"Exists('$(SolutionRoot)\Common\MSBuild\MyCrmSolution.Common.targets')" />

<Import
Project =
"$(MSBuildProjectDirectory)\..\..\..\Common\MSBuild\MyCrmSolution.Common.targets"
Condition =
"Exists('$(MSBuildProjectDirectory)\..\..\..\Common\MSBuild\MyCrmSolution.Common.t
argets')" />

<Import
Project =
"$(MSBuildProjectDirectory)\..\..\Common\MSBuild\MyCrmSolution.Common.targets"
Condition =
"Exists('$(MSBuildProjectDirectory)\..\..\Common\MSBuild\MyCrmSolution.Common.tar
gets')" />

<ItemGroup>
<Compile Include="..\..\Common\AssemblyStandardInfo.cs">
<Link>Properties\AssemblyStandardInfo.cs</Link>
</Compile>
<Compile Include="..\..\Common\AssemblyVersionInfo.cs">
<Link>Properties\AssemblyVersionInfo.cs</Link>
</Compile>
</ItemGroup>
45

CUSTOMIZING CRM BY USING THE MICROSOFT DYNAMICS CRM DEVELOPER TOOLKIT APRIL 2009
 10. Save the BackEndTradingSystem project file.
11. In the Solution Explorer window, right-click BackEndTradingSystem, and then click
Reload Project.
12. To set the pre-build event for the BackEndTradingSystem project, in the Solution
Explorer window, copy the build folder from the EntityWrappers project to the
BackEndTradingSystem project.
13. In the Solution Explorer window, right-click BackEndTradingSystem, and then click
Properties.
14. In the BackEndTradingSystem properties window, on the Build Events tab, set the
pre-build event to the following:
SET RunInstallUtil=true
call "$(ProjectDir)Build\PreBuild.cmd" "$(TargetDir)" "$(TargetFileName)"
"$(BuildingInsideVisualStudio)"
Set the post-build event to the following:
"$(FrameworkSDKDir)bin\gacutil" /i "$(TargetPath)" /f
SET RunInstallUtil=true
call "$(ProjectDir)Build\PostBuild.cmd" "$(TargetDir)" "$(TargetFileName)"
"$(BuildingInsideVisualStudio)"
This will enable the assembly to be installed into the Global Assembly Cache (GAC).

15. At a Visual Studio 2008 command prompt, navigate to the folder

C:\Projects\MyCrmSolution, type devbuild.bat and then press ENTER to run a local
developer build on the BackEndTradingSystem project to ensure that there are no
compilation issues.
46

APRIL 2009 CUSTOMIZING CRM BY USING THE MICROSOFT DYNAMICS CRM DEVELOPER TOOLKIT
 16. In Visual Studio 2008, in the Solution Explorer window, navigate to the
BusinessProcesses project, right-click References, and then click Add Reference.
17. In the Add Reference dialog box, add a project reference to the
BackEndTradingSystem, and then click OK.

18. Expand the Populators folder, and then open the file FormPopulator.cs.

47

CUSTOMIZING CRM BY USING THE MICROSOFT DYNAMICS CRM DEVELOPER TOOLKIT APRIL 2009
 19. Add the following using statements:
using System.Web.Services.Protocols;
using BackEndTradingSystem.BackEndTradingSystem;
using Microsoft.Crm.Sdk;
using MyCrmSolution.Core.Configuration;
using MyCrmSolution.Core.EntityWrappers;
using UKDynamics.Instrumentation;
20. Add the method PopulateAccountSensitiveFinacials as follows:
/// <summary>
/// Populates the sensitive financials related to the account
/// instance from the external web service.
/// </summary>
/// <param name="account">The account.</param>
/// <param name="crmServiceAdapter">
/// The CRM service adapter.
/// </param>
public static void PopulateAccountSensitiveFinancials(
Account account,
CrmServiceAdapter crmServiceAdapter)
{
// Assume it is better to not return the value
// than to error.
if (account == null)
{
TraceHelper.LogMessage(
TraceEntryType.Error,
EventSource.Callout,
"Argument account is null - account");

return;
}

if (crmServiceAdapter == null)
{
TraceHelper.LogMessage(
TraceEntryType.Error,
EventSource.Callout,
"Argument account is null - crmServiceAdapter");

return;
}

using (TradingService tradingService = new TradingService())

{
try
{
// Configure the Url to the web service.
tradingService.Url =
MyCrmSolutionSettings.EnvironmentSettings.TradingService.Url.ToString();
tradingService.UseDefaultCredentials = true;
48

APRIL 2009 CUSTOMIZING CRM BY USING THE MICROSOFT DYNAMICS CRM DEVELOPER TOOLKIT
 account.NewTradingbalance = new
CrmMoney(tradingService.GetTradingBalance());
}
catch (SoapException soapEx)
{
TraceHelper.LogException(
EventSource.Callout,
soapEx);
}
}
}
21. At a Visual Studio 2008 command prompt, navigate to the folder
C:\Projects\MyCrmSolution, type devbuild.bat and then press ENTER to run a local
developer build on the BusinessProcesses project to ensure that there are no
compilation issues.

Developing the post-Retrieve plug-in for the account entity

To populate the account entity instance with the Trading Balance, we must hook into the
execution pipeline after the entity has been retrieved, and then populate the Trading Balance
attribute with the value retrieved from the BackEndTradingSystem web service. To accomplish
this, generate a Post-Retrieve plug-in for the account entity.
To develop the Post-Retrieve plug-in for the account entity, perform the following steps:
1. In the CRM Explorer window, right-click the account entity, point to Generate Plug-
in, and then click PostRetrieve.

49

CUSTOMIZING CRM BY USING THE MICROSOFT DYNAMICS CRM DEVELOPER TOOLKIT APRIL 2009
 The code generator creates the following two files, which open in Visual Studio:
 AccountPlugin.cs - Presented within Visual Studio, this file contains the base
class for all plug-ins related to the account entity. The file is created only one
time, when the first plug-in is added to the entity
Note: Corresponding files / base classes can also be produced for other entities
in a similar manner.
 AccountPostRetrieve.cs - This file is used to implement the post-retrieve plug-in.

2. In the Solution Explorer window, navigate to the Plugins project, right-click

References, and then click Add Reference.

50

APRIL 2009 CUSTOMIZING CRM BY USING THE MICROSOFT DYNAMICS CRM DEVELOPER TOOLKIT
 3. In the Add Reference dialog box, add a project reference to the BusinessProcesses
assembly, and then click OK.

4. In the AccountPostRetrieve.cs file, add the following using statements:

using MyCrmSolution.Core.BusinessProcesses.Populators;
using MyCrmSolution.Core.EntityWrappers;
5. In the AccountPostRetrieve.cs file, replace the content of Execute() method with the
following code (to make the call to the Trading Service web service and populate the
attribute on the account entity):
public override void Execute()
{
// Retrieve the dynamic entity representing the account
Account account = new
Account(this.DynamicEntityFromContext);

account.RequestedColumns = this.RequestedColumns;

FormPopulator.PopulateAccountSensitiveFinancials(
account,
this.ServiceAdapter);
}
6. Because the suggested implementation does not require auditing, remove the Audit()
method from the AccountPostRetrieve.cs file.
Next, the PostRetrieve plug-in must be added to the registration file (which adheres to
the schema used by the Plug-in registration tool).

51

CUSTOMIZING CRM BY USING THE MICROSOFT DYNAMICS CRM DEVELOPER TOOLKIT APRIL 2009
 7. In the Plugins project, open the file Register.xml, and then add the following as a child
element of <Steps>:
<Steps>
<Step
CustomConfiguration = ""
Description = "Account Post-Retrieve Event"
FilteringAttributes = ""
ImpersonatingUserId = ""
InvocationSource = "0"
MessageName = "Retrieve"
Mode = "0"
PluginTypeFriendlyName = "Account Post-Retrieve"
PluginTypeName =
"MyCrmSolution.Core.Plugins.AccountPostRetrieve"
PrimaryEntityName = "account"
SecondaryEntityName = ""
Stage = "50"
SupportedDeployment = "0" />
</Steps>
Note: Ensure that the Register element contains the correct values for the attributes
based upon your configuration.
8. At a Visual Studio 2008 command prompt, navigate to the folder
C:\Projects\MyCrmSolution, type devbuild.bat and then press ENTER to run a local
developer build.
9. To test that the PostRetrieve plug-in has been deployed, is registered within CRM, and
functions correctly, launch CRM, create a sample account, and then view the account
information to verify that the Trading Balance field is populated with the expected value.

52

APRIL 2009 CUSTOMIZING CRM BY USING THE MICROSOFT DYNAMICS CRM DEVELOPER TOOLKIT
Ensuring that financially sensitive data is not persisted
The PostRetrieve plug-in populates the Trading Balance field on the account form dynamically
from an external data source. If the account record were subsequently saved, CRM would
identify the modification to the Trading Balance field and persist it to the database.
The next step in solution development is to satisfy the requirement to ensure financially
sensitive data is not persisted by removing the value from the Trading Balance attribute
(which is financially sensitive) prior to any updates.
1. In the Solution Explorer window, navigate to the EntityWrappers project, and then
open the file Account.Attributes.cs.

2. Add the following attribute to the NewTradingbalance property accessor:

[FinancialField()]

53

CUSTOMIZING CRM BY USING THE MICROSOFT DYNAMICS CRM DEVELOPER TOOLKIT APRIL 2009
 3. In the CRM Explorer window, right-click the account entity, point to Generate Plug-
in, and then click PreUpdate.

4. In the AccountPreUpdate.cs file, remove the Audit() method, and then replace the
contents of the Execute method with the following:
public override void Execute()
{
// Retrieve the DynamicEntity representing the Account
Account account = new
Account(this.DynamicEntityFromContext);

// Clear financials retrieved from the

// Back End Trading System.
account.ClearFinancialProperties();
}
5. Review the functionality of the BaseEntity.ClearFinancialProperties() method to
understand its operation.
This will inform you of how the [FinancialField()] attribute enables removal of the value
from the TradingBalance attribute.
Next, the PreUpdate plug-in must be added to the registration file.

54

APRIL 2009 CUSTOMIZING CRM BY USING THE MICROSOFT DYNAMICS CRM DEVELOPER TOOLKIT
 6. In the Plugins project, open the file Register.xml, and then add the following as a child
element of <Steps> (after the step for the Account Post-Retrieve plug-in):
<Step
CustomConfiguration = ""
Description = "Account Pre-Update Event"
FilteringAttributes = ""
ImpersonatingUserId = ""
InvocationSource = "0"
MessageName = "Update"
Mode = "0"
PluginTypeFriendlyName = "Account Pre-Update"
PluginTypeName =
"MyCrmSolution.Core.Plugins.AccountPreUpdate"
PrimaryEntityName = "account"
SecondaryEntityName = ""
Stage = "10"
SupportedDeployment = "0">
<Images>
<Image

EntityAlias = "AccountPreUpdateImage"
ImageType = "0"
MessagePropertyName = "Target"
Attributes = "new_tradingbalance" />
</Images>
</Step>
7. Save all files.
8. At a Visual Studio 2008 command prompt, navigate to the folder
C:\Projects\MyCrmSolution, type devbuild.bat and then press ENTER to run a local
developer build.
9. In CRM, open the account that you created previously, and then verify that the Trading
Balance field is populated.
10. Save the account, and then view the database to verify that the value has not been
persisted to the database.

55

CUSTOMIZING CRM BY USING THE MICROSOFT DYNAMICS CRM DEVELOPER TOOLKIT APRIL 2009
Appendix B: Walkthrough - Adding a Property
In the walkthrough described in Appendix A, the MyCrmSolution project defines a custom
configuration item (TradingService) that defines the URL of the external web service. This
appendix provides the steps necessary for adding a new environment property to the
RigTemplates and corresponding build scripts.
 To add the TRADINGSERVICE_URL to the PropertyDefinitions.xml file
1. Navigate to the folder shown below, and then open the file PropertyDefinitions.xml.
C:\Project\MyCrmSolution\BuildScripts\Deployment\DeploymentProperties\
2. Append the following snippet inside the Properties element.
<Property Name="TRADINGSERVICE_URL" Value="" Category="TradingService"
Description="The Trading web service Url." />

 To add the TRADINGSERVICE_URL to the Sample Rig Template

1. Navigate to the folder shown below, and then open the file Sample.xml.
C:\Project\MyCrmSolution\BuildScripts\Deployment\RigTemplates\
2. Append the following snippet inside the Properties element.
<Property Name="TRADINGSERVICE_URL" Value="
http://localhost:83/TradingService/TradingService.asmx" Category="TradingService"
Description="The Trading web service Url." />

 To modify the deployment script by editing the TradingService URL within

environment settings file
1. Navigate to the folder shown below, and then open the file
MSBuildBootstrap.proj.
C:\Projects\MyCrmSolution\BuildScripts\Packaging\MyCrmSolution.Core\Binaries\
2. Add the following snippet to the XmlFileParameter Item Group (line 253).
<!-- Trading Service -->

<XmlFileParameter Include="_TradingService" Condition="'$(TRADINGSERVICE_URL)' != ''" >

<Path>$(EnvironmentConfigFile)</Path>

<Force>true</Force>

<IgnoreNoMatchFailure>true</IgnoreNoMatchFailure>

<Attribute>Url</Attribute>

<XPath>MyCrmSolution.Configuration.EnvironmentSettings/TradingService</XPath>

<Value>$(TRADINGSERVICE_URL)</Value>

</XmlFileParameter>

56

APRIL 2009 CUSTOMIZING CRM BY USING THE MICROSOFT DYNAMICS CRM DEVELOPER TOOLKIT
Appendix C: Resolving Dev Build Failures
During the Dev Build process, text that is displayed in red should be considered an error that
should be investigated before code check. The following table lists potential causes of build
failure and their resolution:

Error Suggested Resolution

Registering  Timeout. The import and publishing of the customization on the

Plug-in developer machine will at times timeout. CRM is a resource intensive
application and having Active Directory, CRM Web Server and SQL Server
on a single virtual machine can cause serious delays. If this occurs, the
CRM Import service may timeout. Try increasing the amount of available
ram for the Virtual PC, compressing the .vhd image, and not running any
other applications. A final solution, especially on a new VPC, is to import
the entity file manually into CRM. Subsequent imports by the DevBuild
will be less resource intensive than the first import.
 Other failures. Typically, a result of a modified attribute or relationship
that is conflicting with the existing configuration. Import Entity files
directly to obtain more detailed reasons for the failure.
Compilation  Assembly locked. Close all solutions before re-executing the
Failure DevBuild.cmd.
 Compile error. Resolve the error within Visual Studio. Build the entire
solution before re-executing the DevBuild.cmd.
 StyleCop error. Resolve the error within Visual Studio – execute
StyleCop across the entire Solution (right-click on the Solution and click
Run Source Analysis).
Warnings Warnings should be diagnosed but need not interrupt the process. Typically,
the following warnings are generated:
 Unit Tests: Currently, the DevBuild process does not include any tests.
This is a placeholder execution for the unit test integration that will
automatically be executed after the tests are created.

57

CUSTOMIZING CRM BY USING THE MICROSOFT DYNAMICS CRM DEVELOPER TOOLKIT APRIL 2009