A brave new world for Exchange 2016 cmdlet reference topic delivery and updates

[The_Exchange_Team]

Update-ExchangeHelp is an Exchange cmdlet that installs the latest available Exchange cmdlet reference help topics on the Exchange server for use in the Exchange Management Shell (Get-Help <Cmdlet>). Although there are ostensibly Windows PowerShell cmdlets for this same task (Update-Help and Save-Help), they don’t work with the Exchange Management Shell.

Update-ExchangeHelp was available in Exchange 2013, but we haven’t previously used it to its full potential. That’s about to change for Exchange 2016. We’re going to rely heavily on Update-ExchangeHelp to release new and updated Exchange cmdlet reference topics for the Exchange Management Shell for all Exchange 2016 product releases (RTM and Cumulative Updates (CUs)). In fact, in a given Exchange product release, you may find that some Exchange cmdlet reference topics aren’t fully documented at the command line.

And how, is this a positive, you may ask? By changing how we approach updating cmdlet reference topics, we can achieve the following benefits:

• Increased quality for the cmdlets customers actually use   We can concentrate on writing help for new cmdlets and updates to high-usage cmdlets first. We have 2+ years of customer usage data for the Exchange 2013 cmdlet reference topics on TechNet. Instead of attempting to update every single cmdlet topic completely for an Exchange release, as we’ve done in the past (think: wide and shallow), we can concentrate on making updates to the new and most highly viewed cmdlets first (think: narrow and deep).
• Timely localization   For a given Exchange release, the English help for Exchange cmdlets comes first, and the translated versions follow. This means that localized Exchange cmdlet help for RTM was available at the command line for CU1, localized Exchange cmdlet help for CU1 was available at the command line for CU2, etc. Using Update-ExchangeHelp, we can make the localized Exchange cmdlet help available as soon as it’s ready without having to wait for the next release.

For an Exchange product release, we’ll target the highest priority updates for Exchange cmdlet reference topics, and get those updates into Exchange code for availability at the command line. After the Exchange product release, we’ll continue to work on updates to Exchange cmdlet reference topics, and publish them to TechNet and as downloadable update packages for Update-ExchangeHelp. At your convenience before the next Exchange product release, you can use Update-ExchangeHelp to download the updated Exchange cmdlet reference topics for the Exchange Management Shell.

We’ll try to balance the frequency of update package releases between Exchange product releases. An Exchange product release allows us to get updated Exchange cmdlet reference topics into Exchange code, so there’s no need to release a downloadable update package right before an Exchange product release. Given the quarterly status of Exchange product releases, it’s reasonable to expect one or two English update packages releases per quarter, and no more frequently than a month or so apart. For localized versions, it’s likely we’ll release one update package per quarter. The English versions of the topics will always be ahead of the localized versions, but the gap will be smaller.

Here’s an example. There’s an Exchange product release, and not all of the Exchange cmdlet reference topics are complete. We’ll continue to work on the topics, and one month after the release, we’ll publish an update package for English. We’ll localize that update package and publish it as soon as it’s ready (likely, a few weeks after the English update package). We’ll continue to work on incomplete cmdlet reference topics in English, and we’ll publish another update package for English about a month after the first one. At this point, we’re two months into the quarter, and the next Exchange product release is likely only one month away. We’ll continue to improve the cmdlet reference topics, and we’ll check them into Exchange code for that next product release. When that Exchange product release goes public, the cycle starts over again.

Another key factor in this strategy is notification. You can periodically run Update-ExchangeHelp to check for updates, but that’s not ideal. We’ll likely use an RSS feed to notify when an updated package is available.

How it works

Using Update-ExchangeHelp is pretty straightforward: you run this command in the Exchange Management Shell on an Exchange server, or on a computer that has the Exchange Management Tools installed.

Update-ExchangeHelp -Verbose

The Verbose switch is important, because it gives you status messages, like “your server is already up-to-date” or “you already tried this within the last 24 hours.” To bypass the 24-hour limit and run the command more frequently, you can add the Force switch.

The problem? The Exchange server requires Internet access so it can download the update package. Not a big deal for some, but a deal-breaker for others. To work around this, read on.

Offline mode for Update-ExchangeHelp

Basically, there are the 4 steps you need to follow to customize Update-ExchangeHelp so it looks for updates on your local network.

1. Download and inspect the ExchangeHelpInfo.xml manifest file.
2. Download the update packages, publish the update packages on an internal web server, and customize the ExchangeHelpInfo.xml file.
3. Publish the customized ExchangeHelpInfo.xml file.
4. Modify the registry of the Exchange servers to point to the customized ExchangeHelpInfo.xml file.

Step 1: Download and inspect the ExchangeHelpInfo.xml manifest file.

Open http://go.microsoft.com/fwlink/p/?LinkId=287244, save the ExchangeHelpInfo.xml file, and open the file in Notepad. Here’s a hypothetical example of the contents of the ExchangeHelpInfo.xml file:

<?xml version="1.0" encoding="utf-8"?>
<ExchangeHelpInfo>
  <HelpVersions>
    <HelpVersion>
      <Version>15.01.0225.030-15.01.0225.050</Version>
      <Revision>001</Revision>
    <CulturesUpdated>en</CulturesUpdated>
<CabinetUrl>http://download.microsoft.com/download/8/7/0/870FC9AB-6D22-4478-BFBF-66CE775BCD18/ExchangePS_Update_...>
    </HelpVersion>
    <HelpVersion>
      <Version>15.01.0225.030-15.01.0225.050</Version>
      <Revision>002</Revision>
      <CulturesUpdated>de, es, fr, it, ja, ko, pt, pu, ru, zh-HanS, zh-HanT</CulturesUpdated>
<CabinetUrl>http://download.microsoft.com/download/8/7/0/870FC9AB-6D22-4478-BFBF-66CE775BCD18/ExchangePS_Update_...>
    </HelpVersion>
    <HelpVersion>
      <Version>15.01.0225.030-15.01.0225.050</Version>
        <Revision>003</Revision>
      <CulturesUpdated>en</CulturesUpdated>
<CabinetUrl>http://download.microsoft.com/download/8/7/0/870FC9AB-6D22-4478-BFBF-66CE775BCD18/ExchangePS_Update_...>
      </HelpVersion>
    </HelpVersions>
</ExchangeHelpInfo>

Each available update package is defined in a <HelpVersion> section, and each <HelpVersion> section contains the following keys.

• <Version>   Identifies the version Exchange that the update package applies to. 15.01.xxxx.xxx is Exchange 2016. 15.00.xxxx.xxx is Exchange 2013. This key might specify one version or a range of versions.
• <CulturesUpdated>   Identifies the language that the update package applies to. This key might specify one language or multiple languages.
• <Revision> Identifies the order that the updated packages were released for the major version of Exchange. In other words, the first update package released for Exchange 2016 is 001, the second is 002, etc. And, there's no relationship between the update packages and the order they were released in. For example, 001 might be an English only update, 002 might be an update for all other supported languages, and 003 might be a German-only update.
• <CabinetUrl>   Identifies the name and location of the update package for the <HelpVersion> section.

The update package that's defined in a <HelpVersion> section applies to an Exchange server based on the combination of <Version> and <CulturesUpdated> values.

You might find that multiple <HelpVersion> sections apply to your Exchange servers for a given version of Exchange. For example, there might be multiple updates for the same language, or separate updates for different languages that both apply to your Exchange servers because you have multiple languages installed. Either way, you need only the most recent update for your Exchange server version and language based on the <Revision> key.

For example, suppose your Exchange servers are running Exchange 2016 version 15.01.0225.040 with English and Spanish installed, and the ExchangeHelpInfo.xml manifest file looks like the example mentioned above.

In this example, all the updates apply to you based on the version of Exchange. However, you need only revision 003 for English, and revision 002 for Spanish. You don't need revision 001 for English because revision 003 is newer.

Step 2: Download the update packages, publish the update packages on an internal web server, and customize the ExchangeHelpInfo.xml manifest file.

The easiest and least time-consuming thing to do is to act like every available update package applies to you.

1. Download all of the .cab files that are defined in the ExchangeHelpInfo.xml file by using the URL that’s defined in the <CabinetUrl> value.
2. Publish those .cab files on an Intranet server (for example http://intranet.contoso.com/downloads/exchange).
3. Modify the <CabinetUrl> values in the ExchangeHelpInfo.xml file to point to the .cab files on the Intranet server (for example, http://intranet.contoso.com/downloads/exchange/<cabfile>).
4. Save the customized ExchangeHelpInfo.xml file.

The benefits to this approach?

• Not much thought involved. It’s difficult to make a mistake and accidentally miss an update that applies to you, because you’re grabbing every available .cab file.
• Easier maintenance. Whenever we release an update package, you just download the new ExchangeHelpInfo.xml file, and grab every new .cab file that’s defined in it.

The drawback to this approach?

• It’s pretty much guaranteed that you’ll download update packages than you don’t need based on version and language.
• Space is consumed on the Intranet server by irrelevant .cab files that you don’t need.

If you want to identify only the .cab files that apply to you, follow these steps.

1. Find the version details for your Exchange servers

a. To find the version details on a single Exchange server, run the following command in the Exchange Management Shell.

Get-Command Exsetup.exe | ForEach {$_.FileVersionInfo}

b. To find the version details for all Exchange servers in your organization, run the following command in the Exchange Management Shell.

Get-ExchangeServer | Sort-Object Name | ForEach {Invoke-Command -ComputerName $_.Name -ScriptBlock {Get-Command ExSetup.exe | ForEach{$_.FileVersionInfo}}} | Format-Table -Auto

The result for ProductVersion will be in the format 15.01.0225.xxx.

2. Find the <HelpVersion> sections in the ExchangeHelpInfo.xml file that apply to you based on the values of the <Version>, <CulturesUpdated>, and <Revision> keys. The methodology was described in Step 1.

After you identify the .cab files that apply to you, follow these steps:

1. Download the applicable .cab files by using the URL that’s defined in the <CabinetUrl> value.
2. Publish those .cab files on an Intranet server (for example http://intranet.contoso.com/downloads/exchange).
3. Modify the <CabinetUrl> values in the ExchangeHelpInfo.xml file to point to the .cab files on the Intranet server (for example, http://intranet.contoso.com/downloads/exchange/<cabfille>).
4. If you like, you can also remove the <HelpVersion> sections that don’t apply to you.
5. Save the customized ExchangeHelpInfo.xml file.

Step 3: Publish the customized ExchangeHelpInfo.xml file

In the previous step, you customized the ExchangeHelpInfo.xml file by changing the <CabinetUrl> values to point to the .cab files on an Intranet server. Now, you need to publish the customized ExchangeHelpInfo.xml file on an Intranet server (for example, http://intranet.contoso.com/downloads/exchange/ExchangeHelpInfo.xml). Note that there's no relationship between the ExchangeHelpInfo.xml file and .cab file locations. You can have them available at the same URL or on different servers.

Step 4: Modify the registry of the Exchange servers to point to the customized ExchangeHelpInfo.xml file

You need the Intranet location for the ExchagneHelpInfo.xml file that you configured in the previous step. This example uses the value http://intranet.contoso.com/downloads/exchange/ExchangeHelpInfo.xml as an example.

1. Copy and paste the following text into Notepad, customize the URL for your environment, and save the file as UpdateExchangeHelp.reg.

Windows Registry Editor Version 5.00
[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\ExchangeServer\v15\UpdateExchangeHelp]
"ManifestUrl"="http://intranet.contoso.com/downloads/exchange/ExchangeHelpInfo.xml"

2. Run the UpdateExchangeHelp.reg file on your internal Exchange servers.

Maintenance and use of Update-ExchangeHelp

Now when you run Update-ExchangeHelp in the Exchange Management Shell on your Exchange servers, the command gets information and downloads files from the Intranet locations you specified. That’s easy.

What’s less easy is the long-term maintenance of this customized setup. Basically, you'll need to repeat Steps 1 through 3 when you discover a downloadable update package has been made available for Exchange cmdlet reference help, and you want to deploy that updated help to your Exchang e servers (everything but the registry modification).

Chris Davis