Tips and Tricks for Using the Solution Packager

Tips and Tricks for Using the Solution Packager in Microsoft Dynamics CRM

ImplementationsPresented by Ivan Kurtev

August 11, 2015

Introduction

• Today’s Presenter:

Ivan KurtevRole: Enterprise Technical Architect at Hitachi Solutions America

Contact Info:Twitter: @ikurtev

LinkedIn: www.linkedin.com/in/ivankurtev/

Blog: mscrmunfiltered.wordpress.com

http://www.linkedin.com/in/ivankurtev/

Agenda

• CRM Metadata and the Solution Packager

• Development Process with the Solution Packager:

• Overview

• Team and Environment Considerations

• Automation Opportunities

• Deep Dive: Check-in Process

• Build Process with the Solution Packager

CRM Solutions and CRM Metadata

• Solutions consist of CRM Metadata and custom code.

• Most of CRM Metadata lives in a single file called customizations.xml

• CRM Metadata includes the definitions of:• CRM entities, forms, views, charts, relationships, etc.

• Workflows

• Dashboards

• Templates

• Security Roles and Field Security Profiles

• And a few more customization types…

• The Customization Tools are the only supported method for modifying CRM metadata.

The Solution Packager

• Enables teams to manage CRM Metadata in source control.

• Released in August 2012 with Update Rollup 10 for CRM 2011.

• Resources:• Team Development Scenario: Use Source Control with Solution Files: • http://msdn.microsoft.com/en-us/library/jj602997.aspx

• Reference: Use the Solution Packager Tool to Compress and Extract a Solution File: • http://msdn.microsoft.com/en-us/library/jj602987.aspx

• Solution Component Reference:• https://msdn.microsoft.com/en-us/library/jj602990.aspx

http://msdn.microsoft.com/en-us/library/jj602997.aspx

http://msdn.microsoft.com/en-us/library/jj602987.aspx

https://msdn.microsoft.com/en-us/library/jj602990.aspx

Features

• Identifies individual components in the compressed solution file and extracts them out to individual files:

• Referred to as a “Extract” operation.

• The individual files can be checked into Source Control.

• Used by developers when they complete a task and want to check in the corresponding CRM metadata changes in source control.

• Re-creates a solution file by packing the files that had been previously extracted:

• Referred to as an “Pack” operation.

• The resulting solution can be deployed to target environments.

• This capability can be invoked from an automated build process.

• Few teams manage CRM Metadata in Source Control.

• But CRM Metadata is as valuable as custom code:• The definition of an entity and its fields is foundational to any solution.

• Business logic is workflows is just as important as business logic in plug-ins.

• Possible Reasons:• Historically, it was not possible to break down a solution into its components.

• Functional users who perform configuration may not have a development background and experience with source control.

• Issues with existing toolsets.

CRM Metadata and Source Control

• Full history of all changes to a component.

• View the changes made to solution component files.

• Rollback undesired changes using Source Control.

Benefits: Versioning and Auditing

• Why did the component change and how does it relate to our requirements?

• Requirement > Task/Bug > Code Check-in.

Benefits: Traceability

• Allows developers to work in isolation on separate development environments and check CRM metadata changes in source control:

• Works well when the changes are to unrelated components.

• Helps identify potential issues with CRM metadata:

• Conflicts that may result in overwrites of someone else’s changes:

• Requires process for resolving conflicts with changes to the same component.

• Frequent environment refreshes help minimize conflicting changes

• Unintentional or undesired changes that may otherwise go unnoticed.

Benefits: Support for Team Development

• Potential: ability to branch and merge CRM Metadata along with custom code.

• Caution: • Modifications to CRM metadata files other than RibbonDiffXml is officially

unsupported.

• Code merges may require reimplementation of customizations in a branch.

Benefits: Support for Parallel Development

• /action: {Extract|Pack}

• /zipfile: <file path>• The filename for the solution package.

• /folder: <folder path>:• The folder with the unpacked solution files.

• /map: <file path>• The location of the mapping file with locations of compiled assemblies or web

resource files.

• /log: <file path>• Path and name of a log file for troubleshooting.

Basic Solution Unpack Operation

Working with Managed Solutions

• Requires an export of both an unmanaged and managed solution.

• Pass /packagetype:Both to the Extract action.

• Generates separate files for FormXml and SiteMap:• The managed files have the same name as the unmanaged files with a

“_managed” suffix.

Agenda



• Overview





Development Process with the Solution Packager

• Considerations:• Address overhead:

• Developers need to understand the value of this process. Clearly articulate the benefits.• Assist with Automation wherever possible.

• Team and Environment Alignment.• When multiple differences exist between the unpacked solution and source control,

developers must decide which unpacked files related to the customization they desire to check in:• Develop an understanding of the relationships between CRM customization components and

unpacked solution files.

Implement Customization in

Development Environment

Export SolutionUnpack Solution

With Solution Packager

Check Changed Solution

Component Files in Source Control

Agenda



• Overview





• Minimize conflicts through task assignment and scheduling.

• Who checks code in Source Control?• All customizers or dedicated resource(s).

• Who modifies CRM Schema:• Entities and Relationships.

• All customizers or a dedicated resource?

• Full Isolation vs. Single CRM Organization vs in-between scenarios:• Full isolation creates conflicts in single files (solution.xml, Relationship.xml,

etc.)

• Single CRM Organization makes it harder to check in individual changes and associate them with work items for traceability.

Team and Environment Considerations

Agenda



• Overview





Automation: Solution Export

• The Solution Export Request (From the CRM 2015 SDK).

• XRM CI Framework:• Created by Wael Hamze and available at

http://xrmciframework.codeplex.com

• Includes PowerShell Scripts Build Templates for automating tasks related to Build and Deployment.

• ExtractCustomizations.ps1 script can be used to export solutions from a CRM organization and unpack them using the Solution Packager.

• Adxstudio ALM Toolkit:• Licensed tool supported by a well-known vendor.

• Addresses a wide range of Development, Build, and Deployment needs.

http://msdn.microsoft.com/en-us/library/microsoft.crm.sdk.messages.exportsolutionrequest.aspx

http://xrmciframework.codeplex.com/

http://www.adxstudio.com/adxstudio-alm-toolkit/

• Check-in/check-out automation:• Concerns:

• If multiple changes exist in the environment and developer wants to check out only some of them.

• It is possible to overwrite someone else’s changes.

• Compare Differences:

Automation: Checking In

Agenda



• Overview





• Folders:• Dashboards• Entities• OptionSets• Other• PluginAssemblies• Roles• Reports• SDKMessageProcessingSteps• Templates• WebResources• Workflows

• Solution Component File Reference: • https://msdn.microsoft.com/en-us/library/jj602990.aspx

Unpacked Solution Folder Structure

https://msdn.microsoft.com/en-us/library/jj602990.aspx

• Simple CRM solution with Account and Contact entities.

• Two Features:• Secondary Contact on Account.

• Track Account Segmentation.

• Demo:• Add “Expected Revenue” to Account entity.

• Add the field to the Account form.

Scenario

• New solution with Account and Contact Entities added:

Initial Export of Solution

Adding a new Relationship

• This is the Secondary Contact 1:M relationship from Contact to Account.

• First customization adds EntityMaps.xml. Additional relationships will result to an edit to this file.

• Relationships.xml includes only the name of the relationship.

• The file for the referenced (primary) entity contains the full relationship definition.

• Not checking in one of these files when creating or modifying a relationship can cause a solution pack or solution import error.

• Relationships.xml and EntityMaps.xml are “single files”:• Adding two different relationships in two separate environments will result in a check-in conflict.

• This is the creation of the Customer Segmentation Option Set.

• New file contains the definition of the Option Set.

• Solution.xml includes a reference to the new component added to the solution.

Adding a Global Option Set

• This is the addition of the Segmentation option set to Account.

• The only file modified is Entity.xml

Adding New Field to Entity

• This is the addition of the Segmentation field to the Account form.

• Both the managed and unmanaged versions of the form are modified:• Note the managed and unmanaged versions of the form. These files need to

be checked in together at all times to eliminate inconsistencies between the unmanaged and managed versions of the form.

Adding a Field to a Form

• This is the addition of the Segmentation field to the My Active Accounts view.

• For custom entities only:• The ObjectTypeCode value in Entity.xml needs to match the

ReturnedTypeCode value in the View Xml file. If an entity is created in one environment and a view is then modified in another, these values may not match.

Adding a Field to a View

• This is the addition of a new plug-in assembly and SDK Message Processing Step.

• Do not check in the raw file for the assembly:• Use a mapping file instead to get the assembly from Visual Studio project.

• Check in only the data.xml file named after the assembly, which contains the assembly registration settings.

• Any time a plug-in class is added to or removed from the assembly, the data.xml file needs to be updated.

• Each registration step is stored in a distinct file.

• Solution.xml and Customizations.xml are modified due to the addition of new components and component types to the solution.

Adding New Plugin and Registration Step

Using a Mapping File

• An Xml file can be passed using the /map command argument.

• Allows us to pack custom code components from a different location:• Plugin and custom workflow assemblies, JavaScript web resources.

• Builds a link between custom code and CRM metadata in source control.

• Eliminates the need for managing custom code components in two locations in source control:• Visual Studio solution versus unpacked CRM solution.

• Plugin and custom workflow assemblies can be compiled using MSBuild prior to the Pack operation

Pain Points with the Solution Packager

• Components Stored in a Single File:• Other folder:

• Solution.xml, Sitemap.xml, Relationships.xml, EntityMaps.xml

• Templates Folder:• EmailTemplats.xml, ContractTemplates.xml, KBArticleTemplates.xml,

MailMergeTemplates.xml

• Other\Relationships folder• One file per entity with all relationships for that entity.

• For 1:M relationships, the relationship is stored in the file for the Primary (Referenced) Entity

• BusinesUnit.xml, Team.xml, User.xml, Owner.xml are updated for all user/team-owned entities.

Agenda



• Overview





• Options:• Use TFS Build Engine with extensions for Build process.• Without TFS Build Engine, use TF.exe, MSBuild, and Solution Packager.

• Mapping File is need to merge assemblies and source code for web resources into solution.

• A test solution import is needed to be confident that the solution will import in target environments:• Will catch both errors during packing the solution and other breaking changes.

Build Process with Solution Packager

Get Latest Source

Compile Plugins and Workflows

ProjectsPack Solution

Test Solution Import

• During pack operation.

• During solution import:• Common with relationships due to complex file structure.

• Schedule a Continuous or Rolling Build to catch issues with recent check-ins sooner.

Possible Build Errors

• Component {xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx} of type (Number) is not declared in the solution file as a root component:• Component included in solution folder structure but not defined in

Other\Solution.xml

• Similar error can occur if component is defined in Solution.xml but is not present in the solution folder structure.

• 'The element 'EntityRelationship' has incomplete content. List of possible elements expected: 'EntityRelationshipType‘:• Relationships.xml checked in but not corresponding file in

Other\Relationships folder.

Two Common Build Errors

Component Types in Solution.xml

Id Component Type

1 Entity

9 Global Option Set

20 Security Role

29 Workflow

50 RibbonDiffXml

60 Dashboard

61 Web Resource

70 Field Security Profile

91 Plugin Assembly

92 SDK Message Processing Step

Questions?

• This is the addition of the Secondary Contact field to the Account form.

• First customization to the form adds the main account form metadata.• Subsequent changes will result to an update to the form files.

• Solution.xml changes can be ignored, they affect only the order of missing dependencies.

Adding a Field to a Form

• This is the addition of the Secondary Contact field to the Active Accounts view.

• First modification to the view adds the definition of the view and a <SavedQueries> node to Entity.xml.

• Subsequent view changes will contain edits to the view will not impact Entity.xml

Adding a Field to a View

Documents

Tips and Tricks for Using the Solution Packager