starred/dkim-exchange-Pro
1
0
Fork 0
mirror of https://github.com/Pro/dkim-exchange.git synced 2026-04-25 08:55:52 +03:00
Code Issues 4 Projects Releases 10 Packages Wiki Activity
Page: Contributing
Pages
Changelog Configuration Contributing Home Installation Requirements Supported Versions Troubleshooting Uninstalling Updating Upgrading
11 Contributing
DJBenson edited this page 2020-01-07 22:53:23 +00:00
Table of Contents

🎉👍 First of all, thank you for contributing! 👍🎉

This document contains guidelines and helpful information for contributing to the dkim-exchange project.

Table Of Contents

Notes for developers

How to include support for newer Exchange Versions

If you want to help us supporting new Exchange Versions, please follow the steps below.

For each Exchange version we need the following files within the Lib directory:

Microsoft.Exchange.Data.Common.dll
Microsoft.Exchange.Data.Common.xml
Microsoft.Exchange.Data.Transport.dll
Microsoft.Exchange.Data.Transport.xml

These can be found at C:\Program Files\Microsoft\Exchange Server\VXX\Public (where XX is the version number on your system). Alternatively, if you have the Exchange ISO, these files can be found in the \Setup\ServerRoles\Common directory of the image.

If using the ISO method, be sure to match the filenames correctly as there are many similarly named (but incorrect) files in the ISO which will break the build process.

  1. Create a fork of our project from your GitHub account
  2. Create a new branch for your changes (e.g. EX2019CU4)
  3. Add the above mentioned files (.dll and .xml) to your fork. Create a new directory for the corresponding Exchange version in the Lib directory.
  4. If you are not familiar with Visual Studio or coding in C# please stop here and just create a new pull request. Otherwise continue with the following steps.
  5. Now you need to change each of the following files to include the new .dll.

    1. DkimSigner.sln

      1. Locate the GlobalSection(SolutionConfigurationPlatforms) section (around line 11)

        Locate the previous version to the one you are creating e.g. for Exchange Server 2019 CU3:

        Ex2019 CU3|Any CPU = Ex2019 CU3|Any CPU.

        Insert a new line below (copy/paste the previous line and update the version/CU accordingly) e.g. for Exchange Server 2019 CU4:

        Ex2019 CU4|Any CPU = Ex2019 CU4|Any CPU

      2. Locate the GlobalSection(ProjectConfigurationPlatforms) section (around line 71)

        Locate the previous version to the one you are creating in in GUID {3AF0EAB4-6135-4908-A659-5E3C974E4718} (there are two lines required) e.g. for Exchange 2019 CU3:

        {3AF0EAB4-6135-4908-A659-5E3C974E4718}.Ex2019 CU3|Any CPU.ActiveCfg = Ex2019 CU3|Any CPU
        {3AF0EAB4-6135-4908-A659-5E3C974E4718}.Ex2019 CU3|Any CPU.Build.0 = Ex2019 CU3|Any CPU

        Insert two new lines below (copy/paste the previous lines and update the versions/CUs accordingly) e.g. for Exchange 2019 CU4:

        {3AF0EAB4-6135-4908-A659-5E3C974E4718}.Ex2019 CU4|Any CPU.ActiveCfg = Ex2019 CU4|Any CPU
        {3AF0EAB4-6135-4908-A659-5E3C974E4718}.Ex2019 CU4|Any CPU.Build.0 = Ex2019 CU4|Any CPU

        Locate the previous version to the one you are creating in in GUID {8AA10740-EC1C-43D9-9BB2-9DF3F82A214F} (there is just one line this time) e.g. for Exchange 2019 CU3:

        {8AA10740-EC1C-43D9-9BB2-9DF3F82A214F}.Ex2019 CU3|Any CPU.ActiveCfg = Release|Any CPU

        Insert a new line below (copy/paste the previous line and update the versions/CUs accordingly) e.g. for Exchange 2019 CU4:

        {8AA10740-EC1C-43D9-9BB2-9DF3F82A214F}.Ex2019 CU4|Any CPU.ActiveCfg = Release|Any CPU

        Save and close DkimSigner.sln

    2. Src/Configuration.DkimSigner/Constants.cs

      1. Locate the latest CU prior to the version of Exchange you are adding e.g. if you are adding Exchange 2019 CU4 and Exchange 2019 CU3 is already supported, then locate:

        {"15.2.464.5", "Exchange 2019 CU3"},

      2. Insert a new line below (copy/paste the previous line and update the versions/CUs accordingly) e.g. for Exchange 2019 CU4:

        {"15.2.529.5", "Exchange 2019 CU4"}

        NOTE: Take care if the value you added is the last in the list, it should NOT have a comma (as per the CU4 example above). If your entry is before the last entry, it SHOULD have a comma (as per the CU3 example above).

      3. Save and close Src/Configuration.DkimSigner/Constants.cs

    3. Src/Exchange.DkimSigner/Exchange.DkimSigner.csproj

      1. Locate the TargetFrameworkVersion section

        Locate the latest CU prior to the version of Exchange you are adding e.g. if you are adding Exchange 2019 CU4 and Exchange 2019 CU3 is already supported, then locate:

        <TargetFrameworkVersion Condition="'$(Configuration)|$(Platform)' == 'Ex2019 CU3|AnyCPU'">v4.7.2</TargetFrameworkVersion>

        Insert a new line below (copy/paste the previous line and update the versions/CUs accordingly) e.g. for Exchange 2019 CU4:

        <TargetFrameworkVersion Condition="'$(Configuration)|$(Platform)' == 'Ex2019 CU4|AnyCPU'">v4.7.2</TargetFrameworkVersion>

        NOTE: Ensure the correct .NET framework version is set.

      2. Locate the PropertyGroup section

        Locate the latest CU prior to the version of Exchange you are adding e.g. if you are adding Exchange 2019 CU4 and Exchange 2019 CU3 is already supported, then locate:

        <PropertyGroup Condition="'$(Configuration)|$(Platform)' == 'Ex2019 CU3|AnyCPU'"> <OutputPath>bin\Exchange 2019 CU3\</OutputPath> <DefineConstants>TRACE;EX_2019_CU3</DefineConstants> <Optimize>true</Optimize> <DebugType>pdbonly</DebugType> <PlatformTarget>AnyCPU</PlatformTarget> <ErrorReport>prompt</ErrorReport> <CodeAnalysisRuleSet>MinimumRecommendedRules.ruleset</CodeAnalysisRuleSet> </PropertyGroup>

        Insert a new line below (copy/paste the previous lines and update the versions/CUs accordingly) e.g. for Exchange 2019 CU4:

        <PropertyGroup Condition="'$(Configuration)|$(Platform)' == 'Ex2019 CU4|AnyCPU'"> <OutputPath>bin\Exchange 2019 CU4\</OutputPath> <DefineConstants>TRACE;EX_2019_CU4</DefineConstants> <Optimize>true</Optimize> <DebugType>pdbonly</DebugType> <PlatformTarget>AnyCPU</PlatformTarget> <ErrorReport>prompt</ErrorReport> <CodeAnalysisRuleSet>MinimumRecommendedRules.ruleset</CodeAnalysisRuleSet> </PropertyGroup>

      3. Locate the ItemGroup section

        Locate the latest CU prior to the version of Exchange you are adding e.g. if you are adding Exchange 2019 CU4 and Exchange 2019 CU3 is already supported, then locate:

        <Reference Include="Microsoft.Exchange.Data.Common" Condition="'$(Configuration)'=='Ex2019 CU3'"> <HintPath>..\..\Lib\Exchange 2019 CU3\Microsoft.Exchange.Data.Common.dll</HintPath> </Reference> <Reference Include="Microsoft.Exchange.Data.Transport" Condition="'$(Configuration)'=='Ex2019 CU3'"> <HintPath>..\..\Lib\Exchange 2019 CU3\Microsoft.Exchange.Data.Transport.dll</HintPath> </Reference>

        Insert a new line below (copy/paste the previous lines and update the versions/CUs accordingly) e.g. for Exchange 2019 CU4:

        <Reference Include="Microsoft.Exchange.Data.Common" Condition="'$(Configuration)'=='Ex2019 CU4'"> <HintPath>..\..\Lib\Exchange 2019 CU4\Microsoft.Exchange.Data.Common.dll</HintPath> </Reference> <Reference Include="Microsoft.Exchange.Data.Transport" Condition="'$(Configuration)'=='Ex2019 CU4'"> <HintPath>..\..\Lib\Exchange 2019 CU4\Microsoft.Exchange.Data.Transport.dll</HintPath> </Reference>

      4. Save and close Src/Exchange.DkimSigner/Exchange.DkimSigner.csproj

    4. coverity.proj

      1. Locate the previous version to the one you are creating e.g. for Exchange Server 2019 CU3:

        <MSBuild Projects="DkimSigner.sln" Properties="Configuration=Ex2019 CU3;Platform=Any CPU" />

      2. Insert a new line below (copy/paste the previous line and update the version/CU accordingly) e.g. for Exchange Server 2019 CU4:

        <MSBuild Projects="DkimSigner.sln" Properties="Configuration=Ex2019 CU4;Platform=Any CPU" />

      3. Save and close coverity.proj

    5. install.ps1

      1. Add the Exchange Server version/CU/build number to the changelog at the start of the file e.g. for Exchange Server 2019 CU4:

        # Exchange 2019 CU4 (15.2.529.5)

      2. Locate the previous version to the one you are creating e.g. for Exchange Server 2019 CU3:

        } elseif (($exchserver.admindisplayversion).major -eq 15 -and ($exchserver.admindisplayversion).minor -eq 2 -and ($exchserver.admindisplayversion).build -eq 464) { $EXVER="Exchange 2019 CU3"

      3. Insert a new line below (copy/paste the previous line and update the version/CU and build numbers accordingly) e.g. for Exchange Server 2019 CU4:

        } elseif (($exchserver.admindisplayversion).major -eq 15 -and ($exchserver.admindisplayversion).minor -eq 2 -and ($exchserver.admindisplayversion).build -eq 529) { $EXVER="Exchange 2019 CU4"

      NOTE: Refer to this Microsoft article for Exchange Server versions and build numbers. The "Major", "Minor" and "Build" attributes must be updated for each version of Exchange or the installer will fail.

      Example:

      Exchange Server 2019 CU4 has build number 15.2.529.5 which would translate to the following in the installer script:

      Major version: 15
      Minor version: 2
      Build version: 529

      The final value (in this case "5") is not used.

      1. Save and close install.ps1

Refer to this commit for a working example: f83924a.

  1. Update the Assembly Information for each of the two projects (Configuration.DkimSigner and Exchange.DkimSigner)
    1. Right click on the Configuration.DkimSigner project in Solution Explorer
    2. Click on Properties
    3. Click on Assembly Information...
    4. Update the build numbers (Assembly Version and File Version) to match the build number you are creating (check the Releases section to ensure you submit a release in line with the current version)
    5. (Optional) Update the copyright year
  2. Make sure that everything compiles
  3. Commit/push the changes to your local repository
  4. Create a pull request

Compiling

There are two projects in the Visual Studio Solution:

To compile the Configuration.DKIMSigner executable just go to Project menu and then Build Solution.

To compile the .dll's for the Exchange Agent, go to Project menu and then select Batch Build. Make sure all the configurations are selected, then press Build. This will automatically link the agent DLLs with the correct version of the Exchange libraries.

Creating Releases

Before starting, ensure you have set your build versions (and optionally copyright year) correctly as per step 6 of the the How to include support for newer Exchange Versions section

  1. Build all the .dll versions and the Configurator as described in the Compiling Section
  2. Commit the changed files, including resulting binary files (Src/Exchange.DkimSigner/bin, and Src/Configuration.DkimSigner/bin/Release)
  3. Push all the changes
  4. Go to GitHub -> Releases (https://github.com/Pro/dkim-exchange/releases)
  5. Create a new release. As the tag use the same version you used in step 6 of the the How to include support for newer Exchange Versions section, e.g. v3.2.0. The title should summarize the release. And as text use the change log content. Just refer to previous releases.
  6. Create a new .zip File for the binary: Right-click on Src/Configuration.DkimSigner/bin/Release and then zip the folder. Rename the resulting .zip to Configuration.DkimSigner.zip. Make sure that this .zip does not contain any subfolders, but all the files directly.
  7. Add the .zip to the release
  8. Create the release as a pre-release. This will allow other users to test it as a beta version
  9. After two weeks or so just remove the pre-release flag, and it will be picked up by the configurator.exe as a new update

Debugging

If you want to debug the .dll on your Exchange Server, you need to install Visual Studio Remote Debugging on the Server.

  1. After the Remote Debugging Tools are installed on the Server, open Visual Studio
  2. Compile the .dll with Debug information
  3. Copy the recompiled .dll to the server
  4. In Visual Studio select Debug->Attach to Process
  5. Under 'Qualifier' input the server IP or Host Name
  6. Select "Show processes from all users"
  7. Select the process EdgeTransport.exe and then press 'Attach'
  8. When reached, the process should stop at the breakpoint

Table of Contents

Home