Introduction

The xExchange module is a part of the Windows PowerShell Desired State Configuration (DSC) Resource Kit, which is a collection of DSC Resources produced by the PowerShell Team. This module contains the xExchActiveSyncVirtualDirectory, xExchAutodiscoverVirtualDirectory, xExchAutoMountPoint, xExchClientAccessServer, xExchDatabaseAvailabilityGroup, xExchDatabaseAvailabilityGroupMember, xExchDatabaseAvailabilityGroupNetwork, xExchEcpVirtualDirectory, xExchExchangeCertificate, xExchExchangeServer, xExchImapSettings, xExchInstall, xExchJetstress, xExchJetstressCleanup, xExchMailboxDatabase, xExchMailboxDatabaseCopy, xExchMapiVirtualDirectory, xExchOabVirtualDirectory, xExchOutlookAnywhere, xExchOwaVirtualDirectory, xExchPopSettings, xExchPowershellVirtualDirectory, xExchReceiveConnector, xExchUMCallRouterSettings, xExchUMService, xExchWaitForADPrep, xExchWaitForDAG, xExchWaitForMailboxDatabase, xExchWebServicesVirtualDirectory resources. This DSC Module allows you to configure many different properties of Exchange 2013 servers, including individual server properties, databases and mount points, and Database Availability Groups.

All of the resources in the DSC Resource Kit are provided AS IS, and are not supported through any Microsoft standard support program or service. The "x" in xExchange stands for experimental, which means that these resources will be fix forward and monitored by the module owner(s).

Please leave comments, feature requests, and bug reports in the Q & A tab for this module.

If you would like to modify xExchange module, feel free. When modifying, please update the module name, resource friendly name, and MOF class name (instructions below). As specified in the license, you may copy or modify this resource as long as they are used on the Windows Platform.

For additional information on using the xExchange module that is not contained within this documentation, see the Managing Exchange 2013 With DSC blog series.

For more information about Windows PowerShell Desired State Configuration, check out the blog posts on the PowerShell Blog (this is a good starting point). There are also great community resources, such as PowerShell.org, or PowerShell Magazine. For more information on the DSC Resource Kit, check out this blog post.

Installation

To install xExchange module

To confirm installation:

Requirements

This module is designed to be used with Exchange 2013. The latest version, 1.0.3.6, has only been tested on Exchange 2013 CU6 and CU7 servers running Windows Server 2012, or Windows Server 2012 R2. The module requires the latest version of PowerShell (v4.0, which ships in Windows 8.1 or Windows Server 2012R2). To easily use PowerShell 4.0 on older operating systems, install WMF 4.0. Please read the installation instructions that are present on both the download page and the release notes for WMF 4.0.

Description

The xExchange module contains the xExchActiveSyncVirtualDirectory, xExchAutodiscoverVirtualDirectory, xExchAutoMountPoint, xExchClientAccessServer, xExchDatabaseAvailabilityGroup, xExchDatabaseAvailabilityGroupMember, xExchDatabaseAvailabilityGroupNetwork, xExchEcpVirtualDirectory, xExchExchangeCertificate, xExchExchangeServer, xExchImapSettings, xExchInstall, xExchJetstress, xExchJetstressCleanup, xExchMailboxDatabase, xExchMailboxDatabaseCopy, xExchMapiVirtualDirectory, xExchOabVirtualDirectory, xExchOutlookAnywhere, xExchOwaVirtualDirectory, xExchPopSettings, xExchPowershellVirtualDirectory, xExchReceiveConnector, xExchUMCallRouterSettings, xExchUMService, xExchWaitForADPrep, xExchWaitForDAG, xExchWaitForMailboxDatabase, xExchWebServicesVirtualDirectory DSC Resources. This DSC Module allows you to configure many different properties of Exchange 2013 servers, including individual server properties, databases and mount points, and Database Availability Groups.

Details

* Denotes a mandatory property

xExchActiveSyncVirtualDirectory resource has the following properties. Where no description is listed, properties correspond directly to Set-ActiveSyncVirtualDirectory parameters.

xExchAutodiscoverVirtualDirectory resource has the following properties. Where no description is listed, properties correspond directly to Set-AutodiscoverVirtualDirectory parameters.

xExchAutoMountPoint is used to automatically find unused disks, and prepare them for use within AutoReseed. With the disks that are found, it will assign appropriate volume and database mount points. Once fully configured, if a disk fails and is replaced with a new disk, xExchAutoMountPoint will automatically detect it and format and assign an Exchange volume mount point so that AutoReseed can detect it as a spare disk. xExchAutoMountPoint resource has the following properties.

xExchClientAccessServer resource has the following properties. Where no description is listed, properties correspond directly to Set-ClientAccessServer parameters.

xExchDatabaseAvailabilityGroup is used to configure a Database Availability Group using New/Set-DatabaseAvailibilityGroup. Only a single node in a configuration script should implement this resource. All DAG nodes, including the node implementing xExchDatabaseAvailabilityGroup, should use xExchDatabaseAvailabilityGroupMember to join a DAG. xExchDatabaseAvailabilityGroup has the following properties. Where no description is listed, properties correspond directly to Set-DatabaseAvailabilityGroup parameters.

xExchDatabaseAvailabilityGroupMember is used to add a member to a Database Availability Group. This must be implemented by all nodes, including the one that creates and maintains the DAG. xExchDatabaseAvailabilityGroupMember has the following properties. Where no description is listed, properties correspond directly to Add-DatabaseAvailabilityGroupServer parameters.

xExchDatabaseAvailabilityGroupNetwork is used to add, remove, or configure a Database Availability Group Network. This should only be implemented by a single node in the DAG. xExchDatabaseAvailabilityGroupNetwork has the following properties. Where no description is listed, properties correspond directly to Set-DatabaseAvailabilityGroupNetwork parameters.

xExchEcpVirtualDirectory resource has the following properties. Where no description is listed, properties correspond directly to Set-EcpVirtualDirectory parameters.

xExchExchangeCertificate is used to install, remove, or configure an ExchangeCertificate using *-ExchangeCertificate cmdlets, and has the following properties.

xExchExchangeServer resource has the following properties. Where no description is listed, properties correspond directly to Set-ExchangeServer parameters.

xExchImapSettings is used to configure IMAP settings using Set-ImapSettings, and has the following properties.

xExchInstall is used to install Exchange 2013, and has the following properties.

xExchJetstress is used to automatically run Jetstress using the JetstressCmd.exe command line executable. The resource looks for the existence of TYPE*.html files in the Jetstress installation directory to determine whether Jetstress has already been run, or if it needs to be executed. TYPE corresponds to the Type defined in the JetstressConfig.xml file, where valid values are Performance, Stress, DatabaseBackup, or SoftRecovery. If TYPE*.html files exist, the newest file is inspected to determine whether the Jetstress run resulted in a Pass or Fail. Note that a TYPE*.html file is not written until Jetstress has finished it's initialization phase, and has also finished the testing phase with either a Pass or a Fail. A crash of the JetstressCmd.exe process will also prevent the file from being written.

xExchJetstressCleanup is used to clean up the database and log directories created by Jetstress. It can optionally remove mount points associated with those directories, and can also remove the Jetstress binaries. Note that xExchJetstressCleanup does NOT uninstall Jetstress. That can be accomplished using the Package resource which is built into DSC.

xExchMailboxDatabase resource has the following properties. Where no description is listed, properties correspond directly to Set-MailboxDatabase parameters.

xExchMailboxDatabaseCopy resource has the following properties. Where no description is listed, properties correspond directly to Add-MailboxDatabaseCopy parameters.

xExchMapiVirtualDirectory resource has the following properties. Where no description is listed, properties correspond directly to Set-MapiVirtualDirectory parameters.

xExchOabVirtualDirectory resource has the following properties. Where no description is listed, properties correspond directly to Set-OabVirtualDirectory parameters.

xExchOutlookAnywhere resource has the following properties. Where no description is listed, properties correspond directly to Set-OutlookAnywhere parameters.

xExchOwaVirtualDirectory resource has the following properties. Where no description is listed, properties correspond directly to Set-OwaVirtualDirectory parameters.

xExchPopSettings is used to configure POP settings using Set-PopSettings, and has the following properties.

xExchPowershellVirtualDirectory resource has the following properties. Where no description is listed, properties correspond directly to Set-PowerShellVirtualDirectory parameters.

xExchReceiveConnector resource has the following properties. Where no description is listed, properties correspond directly to Set-ReceiveConnector parameters.

xExchUMCallRouterSettings is used to configure the UM Call Router service using Set-UMCallRouterSettings, and has the following properties.

xExchUMService is used to configure a UM server using Set-UMService, and has the following properties.

xExchWaitForADPrep is used to ensure that Active Directory has been prepared for Exchange 2013 using setup /PrepareSchema, /PrepareAD, and /PrepareDomain. To find appropriate version values for the SchemaVersion, OrganizationVersion, and DomainVersion parameters, consult the 'Exchange 2013 Active Directory versions' section of the article Prepare Active Directory and domains.

xExchWaitForDAG is used by DAG members who are NOT maintaining the DAG configuration. Intended to be used as a DependsOn property by xExchDatabaseAvailabilityGroupMember. Throws an exception if the DAG still does not exist after the specified retry count and interval. If this happens, DSC configurations run in push mode will need to be re-executed.

xExchWaitForMailboxDatabase is used as a DependsOn property by xExchMailboxDatabaseCopy to ensure that a Mailbox Database exists prior to trying to add a copy. Throws an exception if the database still does not exist after the specified retry count and interval. If this happens, DSC configurations run in push mode will need to be re-executed.

xExchWebServicesVirtualDirectory resource has the following properties. Where no description is listed, properties correspond directly to Set-WebServicesVirtualDirectory parameters.

Renaming Requirements

When making changes to these resources, we suggest the following practice:

  1. Update the following names by replacing MSFT with your company/community name and replacing the "x" with "c" (short for "Community") or another prefix of your choice:
    • Module name (ex: xExchange becomes cExchange)
    • Resource folder (ex: MSFT_xExchActiveSyncVirtualDirectory becomes Contoso_cExchActiveSyncVirtualDirectory)
    • Resource Name (ex: MSFT_xExchActiveSyncVirtualDirectory becomes Contoso_cExchActiveSyncVirtualDirectory)
    • Resource Friendly Name (ex: xExchActiveSyncVirtualDirectory becomes cExchActiveSyncVirtualDirectory)
    • MOF class name (ex: MSFT_xExchActiveSyncVirtualDirectory becomes Contoso_cExchActiveSyncVirtualDirectory)
    • Filename for the <resource>.schema.mof (ex: MSFT_xExchActiveSyncVirtualDirectory.schema.mof becomes Contoso_cExchActiveSyncVirtualDirectory.schema.mof)
  2. Update module and metadata information in the module manifest
  3. Update any configuration that use these resources

We reserve resource and module names without prefixes ("x" or "c") for future use (e.g. "MSFT_ExchActiveSyncVirtualDirectory"). If the next version of Windows Server ships with "ExchActiveSyncVirtualDirectory" resources, we don't want to break any configurations that use any community modifications. Please keep a prefix such as "c" on all community modifications.

Versions

1.0.3.6

1.0.1.0

1.0.0.0

Example: ConfigureAutoMountPoint-FromCalculator

Configures ExchangeDatabase and ExchangeVolume mount points automatically using the xExchAutoMountPoint resource. Shows how to feed the .CSV files from the Server Role Requirements Calculator into the resource. The example code for ConfigureAutoMountPoint-FromCalculator is located in "ConfigureAutoMountPoints-FromCalculator.ps1" in the module folder under ...\xExchange\Examples\ConfigureAutoMountPoint-FromCalculator.

Example: ConfigureAutoMountPoint-Manual

Configures ExchangeDatabase and ExchangeVolume mount points automatically using the xExchAutoMountPoint resource. Configures disk map manually. The example code for ConfigureAutoMountPoint-Manual is located in "ConfigureAutoMountPoints-Manual.ps1" in the module folder under ...\xExchange\Examples\ConfigureAutoMountPoints-Manual.

Example: ConfigureDatabases-FromCalculator

Configures primary databases and database copies using the xExchMailboxDatabase, xExchMailboxDatabaseCopy, and xExchWaitForMailboxDatabase resources. Shows how to feed the .CSV files from the Server Role Requirements Calculator into the resource. The example code for ConfigureDatabases-FromCalculator is located in "ConfigureDatabases-FromCalculator.ps1" in the module folder under ...\xExchange\Examples\ConfigureDatabases-FromCalculator.

Example: ConfigureDatabases-Manual

Configures primary databases and database copies using the xExchMailboxDatabase, xExchMailboxDatabaseCopy, and xExchWaitForMailboxDatabase resources. Configures database list manually. The example code for ConfigureDatabases-Manual is located in "ConfigureDatabases-Manual.ps1" in the module folder under ...\xExchange\Examples\ConfigureDatabases-Manual.

Example: ConfigureNamespaces

Contains three different examples, SingleNamespace, RegionalNamespaces, and InternetFacingSite, which show different ways to configure Client Access Namespaces. The three examples are in separate folders the module folder under ...\xExchange\Examples\PostInstallationConfiguration.

Example: ConfigureVirtualDirectories

Configures various properties on Exchange Virtual Directories, like URL's and Authentication settings. The example code for ConfigureVirtualDirectories is located in "ConfigureVirtualDirectories-Manual.ps1" in the module folder under ...\xExchange\Examples\ConfigureVirtualDirectories.

Example: CreateAndConfigureDAG

Creates a Database Availability Group, creates two new DAG networks and removes the default DAG network, and adds members to the DAG. The example code for CreateAndConfigureDAG is located in "CreateAndConfigureDAG.ps1" in the module folder under ...\xExchange\Examples\CreateAndConfigureDAG.

Example: InstallExchange

Shows how to install Exchange using the xExchInstall resource. The example code for InstallExchange is located in "InstallExchange.ps1" in the module folder under ...\xExchange\Examples\InstallExchange.

Example: JetstressAutomation

Contains two separate example scripts which show how to use the xExchJetstress resource to automate running Jetstress, and the xExchJetstressCleanup resource to cleanup a Jetstress installation. The example code for JetstressAutomation is located in "1-InstallAndRunJetstress.ps1" and "2-CleanupJetstress.ps1" in the module folder under ...\xExchange\Examples\JetstressAutomation.

Example: PostInstallationConfiguration

Shows how to use the majority of the post-installation resources in the xExchange module. The example code for PostInstallationConfiguration is located in "PostInstallationConfiguration.ps1" in the module folder under ...\xExchange\Examples\PostInstallationConfiguration.

Example: WaitForADPrep

Shows how to use the xExchWaitForADPrep resource to ensure that Setup /PrepareSchema and /PrepareAD were run successfully. The example code for WaitForADPrep is located in "WaitForADPrep.ps1" in the module folder under ...\xExchange\Examples\WaitForADPrep.