Merge pull request Azure#3285 from Azure/release-3.3.0

[Release 3.3.0] Merge release-3.3.0 --> master

Author: cormacpayne

.github/PULL_REQUEST_TEMPLATE.md

@@ -12,7 +12,7 @@ If applicable, reference the bug/issue that this pull request fixes here.
 This checklist is used to make sure that common guidelines for a pull request are followed. You can find a more complete discussion of PowerShell cmdlet best practices [here](https://msdn.microsoft.com/en-us/library/dd878270(v=vs.85).aspx).
 
 - [ ] **I have read the [contribution guidelines](https://github.com/Azure/azure-powershell/blob/dev/CONTRIBUTING.md).**
-- [ ] **If changes were made to any cmdlet, the XML help was regenerated using the [platyPSHelp module](https://github.com/Azure/azure-powershell/blob/dev/documentation/platyps-help.md).**
+- [ ] **If changes were made to any cmdlet, the XML help was regenerated using the [platyPSHelp module](https://github.com/Azure/azure-powershell/blob/dev/documentation/platyPSHelp-documentation.md).**
 - [ ] **If any large changes are made to a service, they are reflected in the respective [change log](https://github.com/Azure/azure-powershell/blob/dev/CONTRIBUTING.md#updating-the-change-log).**
 
 ### [General Guidelines](https://github.com/Azure/azure-powershell/blob/dev/CONTRIBUTING.md#general-guidelines)

AzurePowershell.Test.targets

@@ -85,6 +85,7 @@
       <XUnitTests Include=".\src\ResourceManager\Dns\Commands.Dns.Test\bin\Debug\Microsoft.Azure.Commands.Dns.Test.dll"/>
       <XUnitTests Include=".\src\ResourceManager\HDInsight\Commands.HDInsight.Test\bin\Debug\Commands.HDInsight.Test.dll"/>
       <XUnitTests Include=".\src\ResourceManager\Insights\Commands.Insights.Test\bin\Debug\Microsoft.Azure.Commands.Insights.Test.dll"/>
+      <XUnitTests Include=".\src\ResourceManager\IotHub\Commands.IotHub.Test\bin\Debug\Microsoft.Azure.Commands.IotHub.Test.dll"/>
       <XUnitTests Include=".\src\ResourceManager\KeyVault\Commands.KeyVault.Test\bin\Debug\Microsoft.Azure.Commands.KeyVault.Test.dll"/>
       <XUnitTests Include=".\src\ResourceManager\LogicApp\Commands.LogicApp.Test\bin\Debug\Microsoft.Azure.Commands.LogicApp.Test.dll"/>
       <XUnitTests Include=".\src\ResourceManager\Network\Commands.Network.Test\bin\Debug\Microsoft.Azure.Commands.Network.Test.dll"/>
@@ -106,6 +107,8 @@
       <XUnitTests Include=".\src\ResourceManager\UsageAggregates\Commands.UsageAggregates.Test\bin\Debug\Microsoft.Azure.Commands.UsageAggregates.Test.dll"/>
       <XUnitTests Include=".\src\ResourceManager\Websites\Commands.Websites.Test\bin\Debug\Microsoft.Azure.Commands.Websites.Test.dll"/>
       <XUnitTests Include=".\src\Common\Commands.Common.Authentication.Test\bin\Debug\Microsoft.Azure.Commands.Common.Authentication.Test.dll"/>
+	  <XUnitTests Include=".\src\ResourceManager\ServiceBus\Commands.ServiceBus.Test\bin\Debug\Microsoft.Azure.Commands.ServiceBus.Test.dll"/>
+	  <XUnitTests Include=".\src\ResourceManager\EventHub\Commands.EventHub.Test\bin\Debug\Microsoft.Azure.Commands.EventHubs.Test.dll"/>
       <XUnitTests Include="@(AsmXUnitTests)"/>
     </ItemGroup>
     <ItemGroup Condition=" '$(scope)' == 'ServiceManagement' ">
@@ -526,4 +529,3 @@
 
 
 </Project>
-

ChangeLog.md

@@ -72,15 +72,15 @@ For detail descriptions and examples of the cmdlets, type
 You can also find the standalone installers for all the versions at [Downloads](https://github.com/Azure/azure-powershell/releases)
 
 ### PowerShell Gallery
-1. Install [Windows Management Framework 5 with PowerShellGet cmdlets](https://www.powershellgallery.com/GettingStarted?section=Get%20Started)
+1. Install [Windows Management Framework 5 with PowerShellGet cmdlets](https://msdn.microsoft.com/en-us/powershell/gallery/psgallery/psgallery_gettingstarted)
 2. In an elevated PowerShell session, run  ```Install-Module AzureRM```
 3. Run ```Install-AzureRm```
 4. To install RDFE cmdlets, run ```Install-Module Azure```
 
 ### Source Code
 
 1. Download the source code from GitHub repo
-2. Follow the [Microsoft Azure PowerShell Developer Guide](https://github.com/Azure/azure-powershell/wiki/Microsoft-Azure-PowerShell-Developer-Guide)
+2. Follow the [Azure PowerShell Developer Guide](https://github.com/Azure/azure-powershell/wiki/Azure-Powershell-Developer-Guide)
 
 ### Supported PowerShell Versions
 

README.md

@@ -0,0 +1,59 @@
+branches:
+  only:
+    - master
+environment:
+  github_access_token:
+    secure: VMFbecLLHzDq/09YDPbcM0VDDSwwgY57vr5GXK6cZZ4Ti/Xs5RZoylzV8MMr1350
+
+build_script:
+  - ps: |
+      $ErrorActionPreference = "Stop"
+      $response = Invoke-WebRequest ("https://api.github.com/repos/" + $env:APPVEYOR_REPO_NAME + "/releases/tags/" + $env:APPVEYOR_REPO_TAG_NAME) -Timeout 10
+      if($response -ne $null -and $response.StatusCode -ne 200)
+      {
+        $host.SetShouldExit(1)
+      }
+
+      $unzip_path = "C:\projects\azure-powershell-release"
+      $unzip_file = $unzip_path + "zip"
+      Invoke-WebRequest ($response.Content | ConvertFrom-Json).zipball_url -OutFile $unzip_file
+      7z x $unzip_file -o"$unzip_path"
+      $src = Join-Path (ls $unzip_path -dir | select -First 1 | % { $_.FullName }) "src"
+      $global:output = Join-Path $unzip_path "output"
+      ni $global:output -type dir
+      $pattern = "\d(.\d)*"
+
+      foreach($folder in (ls $src -dir))
+      {
+        foreach($module in (ls $folder.FullName -dir | % { $_.FullName }))
+        {
+          # find out docs in help folder and version in .psd1 file 
+          $help = ls $module -dir -Recurse | ? { $_.Name -eq "help" } | select -First 1 | % { $_.FullName }
+          if($help -eq $null)
+          {
+            continue
+          }
+          $psd1= ls $module | ? { $_.extension -eq ".psd1" } | select -First 1 | % { $_.FullName }
+          if($psd1 -eq $null)
+          {
+            continue
+          }
+          if((gc $psd1 | Out-String) -notmatch "ModuleVersion\s*=\s*$pattern")
+          {
+            continue
+          }
+          robocopy $help "*.md" (Join-Path $global:output $folder | Join-Path -ChildPath (gi $psd1).BaseName | Join-Path -ChildPath ("v" + ($matches[0] -match $pattern)))
+        }
+      }
+test: off
+shallow_clone: true
+on_success:
+  - git clone -q --branch=%target_branch% %content_repo% %TEMP%\Azure
+  - cd %TEMP%\Azure
+  - ps: ls $global:output -dir | % { copy $_.FullName (ls -dir | select -First 1) -Recurse -Force }
+  - git config --global credential.helper store
+  - ps: ac "$env:USERPROFILE\.git-credentials" "https://$($env:github_access_token):[email protected]`n"
+  - git config --global user.email %email%
+  - git config --global user.name %name%
+  - git add -A
+  - git diff --quiet --exit-code --cached || git commit -m "Sync docs from source code repo to content repo." && git push origin %target_branch% && appveyor AddMessage "Content Updated"

appveyor.yml

@@ -2,8 +2,8 @@
 
 ###### Usage:
 
-1. Start PS-VSPrompt.lnk (shortcut), this will start VS Dev Prompt in powershell
-2. Import-Module ./Repo-Tasks.psm1
+1. Start .\tools\PS-VSPrompt.lnk (shortcut), this will start VS Dev Prompt in powershell
+2. Import-Module .\tools\Repo-Tasks.psd1
 	1. During import, we allow to load additional functions that users might want to use it in their session.
 	2. If you have any userPreference.ps1 file under %userprofile%/psFiles directory, the module will try to load it by dot sourcing it.
 	2. It will also honor environment variable $env:psuserpreferences and load .ps1 files from the location that is pointed by $env:psuserpreferences
@@ -20,4 +20,4 @@
 		1. Will build and run existing tests.
 
 ###Note:
-If you do not start your powershell session using PS-VSPrompt shortcut, you will not have access to all the environment variables that are set as part of VS Dev Command prompt.
+If you do not start your powershell session using PS-VSPrompt shortcut, you will not have access to all the environment variables that are set as part of VS Dev Command prompt.

documentation/Repo-Tasks-Module.md

@@ -25,4 +25,5 @@
     https://github.com/Azure/azure-powershell/blob/dev/documentation/breaking-changes/breaking-change-template.md
 -->
 
-# Upcoming Breaking Changes
+# Upcoming Breaking Changes
+

documentation/breaking-changes/upcoming-breaking-changes.md

@@ -17,16 +17,28 @@ It can be difficult to follow the changes in a pull request when the number of c
 
 ### Rebasing
 
-Sometimes a pull request can be based on a much earlier commit in the branch that you are trying to merge into it, causing a large amount of commits and file changes to litter the pull request. In this case, it would be better to **rebase** (move branches around by changing the commit that they are based on). After rebasing, you will want to close the pull request and open a new one, which will now have fewer commits.
+Sometimes a pull request can be based on a much earlier commit in the branch that you are trying to merge into it, causing a large amount of commits and file changes to litter the pull request. In this case, it would be better to **rebase** (move branches around by changing the commit that they are based on).
 
-For example, if you're working from the branch **feature** and are trying to rebase with **master**, you may run one of the following commands:
-> `git rebase master`
-> `git rebase master feature`
+For example, if you're working from the branch **feature** and are trying to rebase with **dev**, you'll first want to pull the latest changes from **dev**:
 
-You can also rebase with the following command:
-> `git pull --rebase`
+```
+git pull upstream dev
+```
 
-A normal `git pull` is equivalent to `git fetch` followed by `git merge FETCH_HEAD`, but when you run `git pull --rebase`, it runs `git rebase` instead of `git merge`.
+Next, you'll want to "uncommit" all of the changes in **feature** that differ from **dev**:
+
+```
+git reset --soft upstream/dev
+```
+
+Finally, make a small number of commits with the changes you have made and push them to your fork:
+
+```
+< commit changes >
+git push origin feature -f
+```
+
+**Note**: the `-f` must be included when pushing to your fork for the rebase to be successful 
 
 For more information on rebasing, click [here](https://git-scm.com/docs/git-rebase).
 
@@ -35,7 +47,10 @@ For more information on rebasing, click [here](https://git-scm.com/docs/git-reba
 When your pull request has a group of commits that can be condensed into one, logical commit, use **squashing**. This will clean up the number of commits your pull request has while also grouping together common commits. 
 
 For example, if you wanted to squash the last three commits into one, you may run the following command:
-> `git rebase -i HEAD~3`
+
+```
+git rebase -i HEAD~3
+```
 
 This will bring up an editor showing your last three commits. Pick a commit to keep (as the message), and squash the other two into it.
 
@@ -46,13 +61,19 @@ For more information on squashing, click [here](https://git-scm.com/book/en/v2/G
 If you want to merge specific commits from another branch into the current one you are working from, use **cherry-picking**. 
 
 For example, if you're working on the **master** branch and want to pull commit X (the commit-hash) from the **feature** branch, you may run the following commands:
-> `git checkout master`
-> `git cherry-pick X -n`
+
+```
+git checkout master
+git cherry-pick X -n
+```
 
 The `-n`, or `--no-commit`, is recommended for cherry-picking because it won't automatically create a commit for the cherry-picked change; this will allow you to view the changes first and make sure that you want to add all everything from the cherry-picked commit.
 
 Now, if you want to cherry-pick a range of commits, say X through Y, from the **feature** branch, you may run the following commands:
-> `git checkout -b temp-branch X`
-> `git rebase --onto master Y^`
+
+```
+git checkout -b temp-branch X
+git rebase --onto master Y^
+```
 
 For more information on cherry-picking, click [here](https://git-scm.com/docs/git-cherry-pick).

documentation/cleaning-up-commits.md

@@ -1,8 +1,11 @@
 # PlatyPS Help
 
 - [Description](#description)
+- [Prerequisites](#prerequisites)
+    - [Install and import platyPS](#install-and-import-platyps)
+    - [Check for valid paths](#check-for-valid-paths)
 - [Getting Started](#getting-started)
-    - [Installing the platyPSHelp Module](#installing-the-platypshelp-module)
+    - [Installing the platyPSHelp module](#installing-the-platypshelp-module)
     - [Running the New-ServiceMarkdownHelp cmdlet](#running-the-new-servicemarkdownhelp-cmdlet)
     - [Running the Validate-ServiceMarkdownHelp cmdlet](#running-the-validate-servicemarkdownhelp-cmdlet)
     - [Running the Update-ServiceMarkdownHelp cmdlet](#running-the-update-servicemarkdownhelp-cmdlet)
@@ -20,15 +23,44 @@
 
 PlatyPS is used to create PowerShell external help in markdown rather than XML (MAML). Where as XML help (MAML) can be difficult to edit by hand or read, markdown is designed to be human-readable and easy to edit. This will allow service teams to quickly and easily edit any help documentation they have for their cmdlets.
 
-Install (and read more about) platyPS from the README, located [here](https://github.com/PowerShell/platyPS/blob/master/README.md).
+You can find the more information on platyPS [here](https://github.com/PowerShell/platyPS/blob/master/README.md).
+
+The platyPSHelp module uses platyPS to allow service teams to achieve the following:
+- Create markdown files for each of their cmdlets
+- Update the markdown files when changes are made to the cmdlets
+- Validate the help content in the markdown files to ensure no sections are missing information
+
+## Prerequisites
+
+### Install and import the platyPS
+
+In order to use the platyPSHelp module, you will first need to install the platyPS module. To do so, run the following commands:
+
+```powershell
+Install-Module -Name platyPS -Scope CurrentUser
+Import-Module platyPS
+```
+
+### Check for valid paths
+
+The platyPSHelp module builds paths to the service module and commands directory using the service name provided, the build target, and if the service is ARM or RDFE.
+
+For ARM services, these paths include:
+- Path to module: `src\Package\<Build Target>\ResourceManager\AzureResourceManager\AzureRM.<Service>\AzureRM.<Service>.psd1`
+- Path to commands: `src\ResourceManager\<Service>\Commands.<Service>`
+- Path to help: `src\ResourceManager\<Service>\Commands.<Service>\help`
+
+TrafficManager, for example, is a service that doesn't follow the format of these paths that are built - the path to their commands folder is `src\ResourceManager\TrafficManager\Commands.TrafficManager2`.
+
+In the case that your service doesn't follow the format of the above paths, you will need to use the "FullPath" parameter set, which allows you to pass in the paths as parameters rather than have them built.
 
 ## Getting Started
 
 If your service does not currently have any markdown help, follow the below steps to get started.
 
 **NOTE**: Currently, the platyPSHelp module mentioned below is unable to create markdown help for **ServiceManagement** cmdlets. However, markdown help can be created for these cmdlets when running the regular platyPS cmdlets mentioned in the [How it Works](#how-it-works) section.
 
-### Installing the `platyPSHelp` Module
+### Installing the platyPSHelp module
 
 The `platyPSHelp` module contains cmdlets that will help service teams with creating, updating, and validating markdown help for their cmdlets.
 
@@ -39,15 +71,20 @@ There are three cmdlets contained in this module:
 
 Help documentation has been written for each of these cmdlets, outlining the purpose of each cmdlet, the different parameter sets, and examples.
 
-To use this module, change your directory to the **azure-powershell** repo, and from there, go to `tools\platyPS`. Run the following command to import the module:
+To use this module, change your directory to the **azure-powershell** repo, and from there, go to `tools\platyPSHelp`. Run the following command to import the module:
 
 ```powershell
 Import-Module .\platyPSHelp.psd1
 ```
 
 After executing this command, you will have access to the above cmdlets.
 
-### Running the `New-ServiceMarkdownHelp` cmdlet
+If you are not using the "FullPath" parameter set, you will need the following information to use the cmdlets:
+- `Service` - the name of the service
+- `BuildTarget` - either Build or Release, the type of build used when building the service project locally
+- `ModuleName` - the name of the module corresponding to the service (_i.e._, AzureRM.Profile)
+
+### Running the [New-ServiceMarkdownHelp](https://github.com/Azure/azure-powershell/blob/dev/tools/platyPSHelp/help/New-ServiceMarkdownHelp.md) cmdlet
 
 Once the module is installed, you will need to generate the markdown for your cmdlets; to do so, you will run the `New-ServiceMarkdownHelp` cmdlet.
 
@@ -61,16 +98,12 @@ There are four possible parameter sets to choose from when creating your cmdlets
 - `FullPath`
     - This parameter set will be used if there is an issue when using any of the above parameter sets (*e.g.*, the path to the XML help (MAML) or commands folder does not follow what the cmdlet is expecting); in this case, you can provide the full path to the required items
 
-More information about this cmdlet can be found in the [help](https://github.com/Azure/azure-powershell/blob/dev/tools/platyPSHelp/help/New-ServiceMarkdownHelp.md).
-
 Once ran, this cmdlet will create markdown files for each of the cmdlets in your module, and will be placed in the help folder located on the same level as your XML help (MAML). It will also regenerate the XML help (MAML) to ensure that the information in the markdown help is seen when `Get-Help` or `Get-HelpPreview` is ran.
 
-### Running the `Validate-ServiceMarkdownHelp` cmdlet
+### Running the [Validate-ServiceMarkdownHelp](https://github.com/Azure/azure-powershell/blob/dev/tools/platyPSHelp/help/Validate-ServiceMarkdownHelp.md) cmdlet
 
 Before checking in this markdown, you will need to check to make sure all of the necessary parts are filled out (*i.e.*, synopsis, description, examples, parameter descriptions, and outputs). 
 
-This cmdlet contains the same four parameter sets as the `New-ServiceMarkdownHelp`, and more information about the cmdlet can be found in the [help](https://github.com/Azure/azure-powershell/blob/dev/tools/platyPSHelp/help/Validate-ServiceMarkdownHelp.md).
-
 Once ran, this cmdlet will output a list of errors for each cmdlet in the following format:
 
 ```
@@ -87,12 +120,10 @@ File: Some-Cmdlet.md
 
 This will let you know what parts of the markdown help need to be updated. A recommended tool for editing and visualizing markdown is [Dillinger](http://dillinger.io/), which will display your markdown changes in real-time.
 
-### Running the `Update-ServiceMarkdownHelp` cmdlet
+### Running the [Update-ServiceMarkdownHelp](https://github.com/Azure/azure-powershell/blob/dev/tools/platyPSHelp/help/Update-ServiceMarkdownHelp.md) cmdlet
 
 Anytime that you make changes to a cmdlet (*e.g.*, add/edit/remove parameter, edit output type, etc.), you will need to make sure that those changes are reflected in the markdown. The `Update-ServiceMarkdownHelp` cmdlet will update your markdown with the changes made to your cmdlets.
 
-This cmdlet contains the same four parameter sets as the other two cmdlets, and more information about the cmdlet can be found in the [help](https://github.com/Azure/azure-powershell/blob/dev/tools/platyPSHelp/help/Update-ServiceMarkdownHelp.md).
-
 In addition to updating the markdown help files, it will also regenerate the XML help (MAML) to ensure that the information in the markdown help is seen when `Get-Help` or `Get-HelpPreview` is ran.
 
 ## How it Works

documentation/platyps-help.md renamed to documentation/platyPSHelp-documentation.md

@@ -1,11 +1,11 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <Wix xmlns="http://schemas.microsoft.com/wix/2006/wi" xmlns:util="http://schemas.microsoft.com/wix/UtilExtension">
 
-  <?define productName="Microsoft Azure PowerShell - November 2016" ?>
+  <?define productName="Microsoft Azure PowerShell - December 2016" ?>
   <?define sourceDir="$(var.SolutionDir)..\src\Package\$(var.Configuration)" ?>
   <?define caSourceDir="$(var.SolutionDir)setup\bin\$(var.Configuration)" ?>
 
-  <?define version="3.1.0" ?>
+  <?define version="3.3.0" ?>
 
   <Product Id="*"
            Name="$(var.productName)"