capgemini / msbuild-xrm-sourcecontrol

MSBuild Visual Studio Extensions to provide easy source control for Dynamics 365

MSBuild.Xrm.SourceControl

Releases

2.0.0

Added Environment variable to support multiple extracts for people who work across multiple projects environments

1.0.4

Initial release supporting Extract of Customisations.

Build and Release Status:

Description

MSBuild.Xrm.SourceControl provides a simple but powerful method for extracting Dynamics 365 customisations. The extension uses PowerShell scripts that can seamlessly extract customisations from a Dynamics 365 instance and then subsequently rebuild them into a zipped Solution file ready for import when necessary.

The scripts use the SolutionPackager.exe tool provided by the Dynamics 365 SDK. It supports file mappings, managed and unmanaged solutions, and the export of AutoNumber and Calendar settings.

MSBuild.Xrm.SourceControl extends the MSBuild process for the Clean and AfterBuild targets:

1. Clean - Executes a custom PowerShell script to export solution files from Dynamics and unpack them with SolutionPackager.exe to the "Src" folder.
2. AfterBuild - Executes a custom PowerShell script to pack the "Src" folder into Managed (for Release configuration) and Unmanaged (for Release and Debug configuration) Dynamics solution files using SolutionPackager.exe.

Table of Contents

• Installation
• Usage
• Contributing
• Credits
• License

Installation

Prerequisites

• Minimum .NET Framework: 4.5.1
• PowerShell 4.0+

Create a new class project in Visual Studio and install this extension by either searching for "MSBuild.Xrm.SourceControl" from 'Manage Nuget Packages' or run the command line Install-Package MSBuild.Xrm.SourceControl in the 'Package Manager Console'.

More detailed installation instructions can be found on the wiki.

Usage

The configuration shown below demonstrates a basic setup to extract the customisations into source control.

Configuration

When the Nuget package is first installed, two configuration files will be added into the project.

CrmConfiguration.props

Default Values

<?xml version="1.0" encoding="utf-8"?>
<Project ToolsVersion="4.0" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
  <PropertyGroup> 
    <CrmSolutionName>NOT_DEFINED</CrmSolutionName> 
    <CrmConnectionString>AuthType=OAuth;Url=url; Username=user; Password=password;ClientId=clientid;RedirectUri=redirectUri;</CrmConnectionString>
    <ExportAutoNumberSettings>0</ExportAutoNumberSettings>
    <ExportCallendarSettings>0</ExportCallendarSettings>
  </PropertyGroup> 
</Project>

The first step is to populate the values for each of the elements:

• CrmSolutionName: The Name of the Dynamics Solution
• CrmConnectionString: The connection string that will be used to connect to the Dynamics instance, for more information, see here
• ExportAutoNumberSettings: Option for whether to Export the AutoNumber Settings for the Solution, 0 for No, 1 for Yes
• ExportCallendarSettings: Option for whether to Export the Calendar Settings for the Solution, 0 for No, 1 for Yes

MappingFile.xml

Default Values

<?xml version="1.0" encoding="utf-8"?>
<Mapping>
  
</Mapping>

The Mapping configuration is used when the Solution is being rebuilt from the extracted files. The mapping file can define mappings between a file that is contained in the extracted solution files, to a file that is in another location on the file system. An example usage of this is for Web Resources, but it can also be used for compiled solution components such as Plugin .dll files. When the solution is being built, the mapped files will be used instead of the ones already in the solution. This is to try to make sure that the latest version of the files are used.

Example

<?xml version="1.0" encoding="utf-8"?>
<Mapping>
  <FileToPath map="WebResources\*.*" to="..\..\XXX.Base.CrmPackage\WebResources\**" />
  <FileToPath map="WebResources\**\*.*" to="..\..\XXX.Base.CrmPackage\WebResources\**" />
  <FileToFile map="Capgemini.Base.Workflows.dll" to="..\..\XXX.Base.Workflows\bin\**\Capgemini.Base.Workflows.dll" />
  <FileToFile map="Capgemini.Base.Plugins.dll" to="..\..\XXX.Base.Plugins\bin\**\Capgemini.Base.Plugins.dll" />
</Mapping>

You can either use the FileToPath or FileToFile elements to map a collection of files or just a single file.

Solution Extraction

The installation of the Nuget package will modify the .csproj file to add tasks into the project build process. When the "Clean" command is run on the project, the ExtractCrmCustomizations.ps1 PowerShell script will be executed using the configuration files that are mentioned on the Setup page to connect to Dynamics and extract the solution files into the "Src" folder of the project.

NOTE: It is not recommended to select the 'Include in Project' option for the Src folder or any of its contents, as this will lead to unnecessary modifications to the project file every time a "Clean" is performed. Instead it is recommended to simply use the "Show All Files" button, to show the files.

The "Src" folder and its contents should be included in Source Control. Every time the "Clean" command is executed, and the changes are synced, a history will be built in Source Control giving more visibility of changes.

Solution Build

When the "Build" command is run on the project, the BuildCrmCustomizations.ps1 PowerShell script will be executed using the configuration files that are previously mentioned and pack the solution files in the "Src" folder into a Dynamics Solution file. There are two different types of Dynamics solution, Managed or Unmanaged. If the Build Configuration in Visual Studio is set to Debug, only the Unmanaged version of the Dynamics solution will be built, if the Build Configuration is set to Release, both Managed and Unmanaged versions will be built.

The built solution files will be output to the project's "bin" folder. Ready to be manually deployed to another environment or used in an automated CI process:

Use in CI Pipeline

As the extensions are for MSBuild, they can be used not only through Visual Studio, but anywhere that MSBuild can be executed, this means that the rebuilding of the solution files can be done and is recommended to be done through a CI pipeline, such as those available in Azure DevOps:

NOTE: You may need to include the /bin/coretools/ folder and its contents into Source Control for this to work. For git repositories, this would involve editing your git.ignore file.

Contributing

The source code for the extension will be made available soon. All contributions will be appreciated.

To contact us, please email [email protected].

Credits

Capgemini UK Microsoft Team

This extension uses the excellent Microsoft.Xrm.Data.Powershell, by seanmcne.

License

MIT

msbuild-xrm-sourcecontrol's Issues

support for Oauth authentication

the current supported authentication method "Office365" is deprecated, I think we should support Oauth.
This tool uses Microsoft.Xrm.Data.PowerShell which if updated supports this auth method. note after looking into it, it seems it does not support client/secret

Update documentation and point to replacement

Cannot bind argument to parameter 'environmentVariable' because it is an empty string.

@Dave-Robertson92 we are using Capgemini.Crm.VisualStudioExtensions" version="2.0.6" in our project, since it's not supporting Oauth authentication ,we changed it to <package id="MsBuild.Xrm.SourceControl" version="3.0.0" targetFramework="net452" /> and changed the crmconfiguration.props file as follows,

<?xml version="1.0" encoding="utf-8"?>
<Project ToolsVersion="4.0" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
  <PropertyGroup> 
    <CrmSolutionName>Solutionname</CrmSolutionName> 
    <EnvironmentVariableName>XRMExtract</EnvironmentVariableName>
    <CrmConnectionString>Url=https://XXXXXX.crm4.dynamics.com; Username=XXXXXX.onmicrosoft.com; Password=XXXXX; AuthType=OAuth; AppId = XXX-XX-XXXX-XXX-XXXX; RedirectUri = app://XXX-XX-XXXX-XXX-XXXX; LoginPrompt=Auto;</CrmConnectionString>
      <ExportAutoNumberSettings>0</ExportAutoNumberSettings>
    <ExportCallendarSettings>0</ExportCallendarSettings>
      </PropertyGroup>
</Project>

However, with the new .prop file <EnvironmentVariableName> property got introduced and In the description of the nugget package here we don't find any information around this property.

Because of this property, we are not able to clean/ build our project and getting the error:
Cannot bind argument to parameter 'environmentVariable' because it is an empty string.

Could you please help us with the missing property information, and what should we add here to make it work?

Clean sometimes fails on the first attempt.

Very often you are required to clean twice for the customisations to work. On investigation it seems the timeout property is being ignored. However this needs further investigation.

Deprication on Org Service Endpoint

The endpoint /xrmservices/2011/organizationdata.svc is being removed by Microsoft at the end of April. Its been discovered that this package utilizes the endpoint to extract solutions from dynamics, are there plans to update this before the deadline?