Skip to content

Build and Deployment

Jump to bottom
Nilesh Ghodekar edited this page Jan 18, 2021 · 28 revisions

Prerequisites

Build / Developer Machine

The following prerequisites are required only on the build / developer machine:

  • Visual Studio 2012, 2013 or 2015. Visual Studio 2015 Community is available for free here.
    • Visual Studio 2017 and above does not support .NET 3.5 Workflow projects. However, if you must, you can compile the MIMWAL solution using Visual Studio 2017 and later as mentioned in the Issue #77.
  • .NET Framework 3.5 SP1 (if not installed as part of Visual Studio).
  • Copies of the following binaries referenced in the project:
  • Copies of the following .NET Framework 3.5 SP1 SDK utilities:
    • gacutil.exe
    • sn.exe
      • Note: If you take these utilities from .NET Framework 4.0 or later you will also need the copy of corresponding .cofig files (gacutil.exe.config and sn.exe.config). Additionally, you'll also need to ensure that the servers on which these utilities are run have the compatible .NET Framework version installed.

Note: These files are neither included nor distributed as part of the MIMWAL project source code or release downloads (as their distribution and usage is governed by the licensing agreement of the respective products they are shipped with) and should be gathered before building the solution in Visual Studio.

WARNING: If you do not follow the above recommendations and gather the listed versions of the DLLs and EXEs, you will need expert knowledge of .NET for a successful deployment of MIMWAL.

MIM / FIM Server

The following are the prerequisites for the deployment of the compiled WAL assemblies on a MIM / FIM Server:

  • Microsoft Identity Manager (MIM) 2016 at build version 4.3.1935 and above.
    • OR
  • Forefront Identity Manager (FIM) 2010 R2 at build version 4.1.3496 and above.
  • Solution Output files ("src\SolutionOutput" folder after compilation of the source code) from the build machine accessible during the deployment.

Build

  • Download the source code for the latest release from https://github.com/Microsoft/MIMWAL/releases and extract it on to C:\ (or any other) drive.

    Important. Before extracting the downloaded zip file, UNBLOCK the zip file by right-clicking on the file and in the properties dialogue clicking the ‘UNBLOCK’ button.

    To avoid compilation issues due to long file paths, it is recommended that you place the WAL source code directory in the drive root or a folder closer to the drive root.

  • Ensure that the referenced assemblies and .NET utilities are copied / placed in the source code folder structure:

    • src\Scripts
      • gacutil.exe
      • sn.exe
    • src\ReferencedAssemblies\
      • System.Management.Automation.dll
    • src\ReferencedAssemblies\4.1.3496.0
      • Microsoft.IdentityManagement.WebUI.Controls.dll
      • Microsoft.IdentityManagement.WFExtensionInterfaces.dll
      • Microsoft.ResourceManagement.dll
      • Microsoft.ResourceManagement.WorkflowContract.dll

    Important. Make sure you have UNBLOCKed all these referenced assemblies by right-clicking on the file and in the properties dialogue clicking the ‘UNBLOCK’ button. Otherwise the compilation will fail.

  • Replace the WAL.snk file with your own strong name key. It is recommended that you keep the filename same as WAL.snk so as to avoid making any changes to the solution / project settings. To generate your own strong name key, you can use the sn.exe –k command from the "src\Scripts" folder with output file path specified as ..\WAL.snk: sn.exe -k ..\WAL.snk.

    WARNING. If you have already deployed a previous version of WAL in production, it is strongly recommended that you do not generate a new strong name key file, but instead reuse the existing one.

Deploy - Build - SigningKeyGeneration

  • Using Windows Explorer, navigate to the "src" folder and copy the newly generated WAL.snk to a safe location for future use.

  • Open the WAL.sln solution from the "src" folder and compile it in the "Release" mode (and NOT "Debug" mode) using "BUILD | Rebuild Solution" menu. All the files needed to complete the deployment of WAL get copied to the “src\SolutionOutput” folder as part of Post Build Event.

Deploy - Build - SolutionCompilation

  • Open a command prompt, change directory to "src\SolutionOutput" and run the sign.cmd to fully sign the delay-signed WAL assemblies:

Deploy - Build - AssemblySigning

Deploy

Important: Do not deploy a newer version of WAL directly in production before testing all your existing WAL workflows thoroughly in a DEV / TEST environment.

  • Copy the content of "src\SolutionOutput" folder to a local folder on the MIM / FIM Service and Portal servers.
  • Open an administrative command prompt and execute Register.ps1 script on each of your MIM / FIM Service server as well as each MIM / FIM Portal server specifying the name of the IIS Website as the PortalSiteName parameter. e.g. .\Register.ps1 -PortalSiteName "FIM Portal"

Deploy - RegisterWAL

Note: If the server does not have MIM / FIM Portal deployed, the value of PortalSiteName is irrelevant and you can safely ignore any warning for the script about not being able to update web.config.

  • Review the console messages from the Register.ps1 script. If there are no errors, manually confirm that the following tasks were performed successfully:
    • In the GAC of the server with MIM / FIM Service role MicrosoftServices.IdentityManagement.WorkflowActivityLibrary.dll is registered.
    • In the GAC of the server with MIM / FIM Portal role MicrosoftServices.IdentityManagement.WorkflowActivityLibrary.dll and MicrosoftServices.IdentityManagement.WorkflowActivityLibrary.UI.dll are registered.
    • The WAL Assembly Bindings redirects in the app.config and / or web.config are created / updated with the latest version of the WAL assemblies.
    • A diagnostics source for WAL is present in the app.config and / or web.config.
    • An ActivityInformationConfiguration (AIC) object for each WAL activity is created / updated. All WAL AIC's are labelled with the "WAL: " prefix.
    • An event log and a event source for WAL is registered. There will be a test event logged in the "WAL" event log (located in the Event Viewer under "Applications and services Log").

Note: If you get any access denied errors from FIM Service of a FIM 2010 R2 implementation in the script code that tries to create AIC's for MIMWAL activities, you may have forgotten to correct the typo "IsAuthoriztionActivity" to "IsAuthorizationActivity" in the selected resource attributes list of the built-in MPR called "Administration: Administrators control configuration related resources".

WAL supports ETW tracing. When you collect the ETW traces for Microsoft.ResourceManagement.Service, it will collect it for WAL as well. ETW tracing at verbose trace level is enabled by default for Microsoft.ResourceManagement.Service and hence for WAL. For ongoing production operation, it is recommended that you turn off ETW tracing and turn it on only when there is a need to troubleshoot MIM / FIM Workflow issues. After enabling ETW tracing at verbose trace level (if you had turned it off), you may choose to utilize CaptureTrace.cmd from the SolutionOutput folder to capture the trace for troubleshooting any issue.

  • Confirm that the previous deployment steps were executed on all your FIM Service and Portal servers.
  • Now, update the WAL assembly version in the workflow XOMLs by running the UpdateWorkflowXoml.ps1 script once from any server with MIM / FIM Service role.

Important: Run UpdateWorkflowXoml.ps1 only after successfully running the Register.ps1 on all your servers. Do not uninstall older versions of WAL binaries from the GAC at this point in time as it will abort any existing in-flight workflows that use WAL activities. Once all the requests that were in-flight before this deployment are processed, you can then choose to safely unregister the older version from the GAC.

MIM WAL Docs

Clone this wiki locally