Use source control with solution files
This topic applies to Dynamics 365 Customer Engagement (on-premises). For the Power Apps version of this topic, see: SolutionPackager tool
The SolutionPackager tool can be used with any source control system. After a solution .zip file has been extracted to a folder, simply add and submit the files to your source control system. These files can then be synchronized on another computer where they can be packed into a new identical solution .zip file.
As further customizations and changes are necessary for the solution, developers should edit or customize components through existing means, export again to create a .zip file, and extract the compressed solution file into the same folder.
Important
Except for the sections described in When to edit the customizations file, manual editing of extracted component files and .zip files is not supported.
When the SolutionPackager tool extracts the component files it will not overwrite existing component files of the same name if the file contents are identical. In addition, the tool honors the read-only attribute on component files producing a warning in the console window that particular files were not written. This enables the user to check out, from source control, the minimal set of files that are changing. The /clobber parameter can be used to override and cause read-only files to be written or deleted. The /allowWrite parameter can be used to assess what impact an extract operation has without actually causing any files to be written or deleted. Use of the /allowWrite parameter with verbose logging is effective.
After the extract operation is completed with the minimal set of files checked out from source control, a developer may submit the changed files back into source control, as is done with any other type of source file.
Team development
When there are multiple developers working on the same solution component a conflict might arise where changes from two developers result in changes to a single file. This occurrence is minimized by decomposing each individually editable component or subcomponent into a distinct file. Consider the following example.
Developer A and B are both working on the same solution.
On independent computers, they both get the latest sources of the solution from source control, pack, and import an unmanaged solution .zip file into independent Dynamics 365 Customer Engagement (on-premises) organizations.
Developer A customizes the “Active Contacts” system view and the main form for the Contact entity.
Developer B customizes the main form for the Account entity and changes the “Contact Lookup View”.
Both developers export an unmanaged solution .zip file and extract.
Developer A will need to check out one file for the Contact main form, and one file for the “Active Contacts” view.
Developer B will need to check out one file for the Account main form, and one file for the “Contact Lookup View”.
Both developers may submit, in any order, as their respective changes touched separate files.
After both submissions are complete, they can repeat step #2 and then continue to make further changes in their independent organizations. They each have both sets of changes, with no overwrites of their own work.
The previous example works only when there are changes to separate files. It is inevitable that independent customizations require changes within a single file. Based on the example shown above, consider that developer B customized the “Active Contacts” view while developer A was also customizing it. In this new example, the order of events becomes important. The correct process to reconcile this predicament, written out in full, is as follows.
Developer A and B are both working on the same solution.
On independent computers, they both get the latest sources of the solution from source control, pack, and import an unmanaged solution .zip file into independent organizations.
Developer A customizes the “Active Contacts” system view and the main form for the Contact entity.
Developer B customizes the main form for the Account entity and changes the “Active Contacts”.
Both developers export an unmanaged solution . zip file and extract.
Developer A will need to check out one file for the Contact main form, and one file for the “Active Contacts” view.
Developer B will need to check out one file for the Account main form, and one file for the “Active Contacts” view.
Developer A is ready first.
Before developer A submits to source control they must get latest sources to ensure no prior check-ins conflict with their changes.
There are no conflicts so developer A is able to submit.
Developer B is ready next following developer A.
Before developer B submits they must get the latest sources to ensure no prior check-ins conflict with their changes.
There is a conflict because the file for “Active Contacts” has been modified since developer B last retrieved the latest sources.
Developer B must reconcile the conflict. It is possible the capabilities of the source control system in use may aide this process; otherwise the following choices are all viable.
Developer B, through source control history, if available, can see that the developer A made the prior change. Through direct communication they can discuss each change. Then developer B only has to update their organization with the agreed resolution. Developer B then exports, extracts, and overwrites the conflicting file and submits.
Allow source control to overwrite their local file. Developer B packs the solution and imports it into their organization, then assesses the state of the view and re-customizes it as necessary. Next, developer B may export, extract, and overwrite the conflicting file.
If the prior change can be deemed unnecessary, developer B allows their copy of the file to overwrite the version in source control and submits.
Whether working on a shared organization or independent organizations, team development of Dynamics 365 Customer Engagement (on-premises) solutions requires those actively working on a common solution to be aware of the work of others. The SolutionPackager tool does not fully remove this need but it does enable easy merging of non-conflicting changes at the source control level, and it proactively highlights the concise components where conflicts have arisen.
The next sections are the generic processes to effectively use the SolutionPackager tool in source control when developing with teams. These work equally with independent organizations or shared development organizations, though with shared organizations the export and extract will naturally include all changes present within the solution, not just those made by the developer performing the export. Similarly, when importing a solution .zip file the natural behavior to overwrite all components will occur.
Create a solution
The following procedure identifies the typical steps used when first creating a solution.
In a clean organization, create a solution on Dynamics 365 Server, and then add or create components as necessary.
When you are ready to check in, do the following.
Export the unmanaged solution.
Using the SolutionPackager tool, extract the solution into component files.
From those extracted component files, add the necessary files to source control.
Submit these changes to source control.
Modify a solution
The following procedure identifies the typical steps used when modifying an existing solution.
Synchronize or get the latest solution component file sources.
Using the SolutionPackager tool, pack component files into an unmanaged solution .zip file.
Import the unmanaged solution file into an organization.
Customize and edit the solution as necessary.
When you are ready to check the changes into source control, do the following.
Export the unmanaged solution.
Using the SolutionPackager tool, extract the exported solution into component files.
Synchronize or get the latest sources from source control.
Reconcile if any conflicts exist.
Submit the changes to source control.
Steps 2 and 3 must be done before further customizations occur in the development organization. Within step 5, step b must be completed before step c.
See also
Solution Tools for Team Development
Use the SolutionPackager Tool to Compress and Extract a Solution File