Merge latest changes into live

README.md

@@ -14,7 +14,7 @@ Each folder in this repo publishes to [MSDN](https://msdn.microsoft.com/en-us/po
 * [/dsc/](https://msdn.microsoft.com/en-us/powershell/dsc/) is  for the Desired State Configuration feature
 * [/gallery/](https://msdn.microsoft.com/powershell/gallery) is for the [PowerShell Gallery](https://www.powershellgallery.com/)
 * [/jea/](https://msdn.microsoft.com/powershell/jea/) is for the Just Enough Administration feature
-* [/reference/](https://msdn.microsoft.com/powershell/reference/) is for PowerShell module reference across versions 2.0, 3.0, 4.0, 5.0, 5.1, and 6.0
+* [/reference/](https://msdn.microsoft.com/powershell/reference/) is for PowerShell module reference across versions 3.0, 4.0, 5.0, 5.1, and 6.0
   * This content will be retrieved by the `Get-Help` cmdlet in the future
 * [/scripting/](https://msdn.microsoft.com/en-us/powershell/scripting/) is general PowerShell reference content
 * [/wmf](https://msdn.microsoft.com/en-us/powershell/wmf/readme) contains release notes for the Windows Management Framework, the package used to distribute new versions of PowerShell to previous versions of Windows. 

dsc/authoringResourceComposite.md

@@ -197,7 +197,7 @@ To access the user context from within a custom resource, you can use the automa
 For example the following code would write the user context under which the resource is running to the verbose output stream:
 
 ```powershell
-if (PsDscContext.RunAsUser) {
+if ($PsDscContext.RunAsUser) {
     Write-Verbose "User: $PsDscContext.RunAsUser";
 }
 ```

dsc/metaConfig.md

@@ -81,7 +81,7 @@ The following properties are available in a **Settings** block.
 | CertificateID| string| The thumbprint of a certificate used to secure credentials passed in a configuration. For more information see [Want to secure credentials in Windows PowerShell Desired State Configuration](http://blogs.msdn.com/b/powershell/archive/2014/01/31/want-to-secure-credentials-in-windows-powershell-desired-state-configuration.aspx)?. <br> __Note:__ this is managed automatically if using Azure Automation DSC pull service.|
 | ConfigurationDownloadManagers| CimInstance[]| Obsolete. Use __ConfigurationRepositoryWeb__ and __ConfigurationRepositoryShare__ blocks to define configuration pull service endpoints.|
 | ConfigurationID| string| For backwards compatibility with older pull service versions. A GUID that identifies the configuration file to get from a pull service. The node will pull configurations on the pull service if the name of the configuration MOF is named ConfigurationID.mof.<br> __Note:__ If you set this property, registering the node with a pull service by using __RegistrationKey__ does not work. For more information, see [Setting up a pull client with configuration names](pullClientConfigNames.md).|
-| ConfigurationMode| string | Specifies how the LCM actually applies the configuration to the target nodes. Possible values are __"ApplyOnly"__,__"ApplyandMonitior"__, and __"ApplyandAutoCorrect"__. <ul><li>__ApplyOnly__: DSC applies the configuration and does nothing further unless a new configuration is pushed to the target node or when a new configuration is pulled from a service. After initial application of a new configuration, DSC does not check for drift from a previously configured state. Note that DSC will attempt to apply the configuration until it is successful before __ApplyOnly__ takes effect. </li><li> __ApplyAndMonitor__: This is the default value. The LCM applies any new configurations. After initial application of a new configuration, if the target node drifts from the desired state, DSC reports the discrepancy in logs. Note that DSC will attempt to apply the configuration until it is successful before __ApplyAndMonitor__ takes effect.</li><li>__ApplyAndAutoCorrect__: DSC applies any new configurations. After initial application of a new configuration, if the target node drifts from the desired state, DSC reports the discrepancy in logs, and then re-applies the current configuration.</li></ul>|
+| ConfigurationMode| string | Specifies how the LCM actually applies the configuration to the target nodes. Possible values are __"ApplyOnly"__,__"ApplyAndMonitor"__, and __"ApplyAndAutoCorrect"__. <ul><li>__ApplyOnly__: DSC applies the configuration and does nothing further unless a new configuration is pushed to the target node or when a new configuration is pulled from a service. After initial application of a new configuration, DSC does not check for drift from a previously configured state. Note that DSC will attempt to apply the configuration until it is successful before __ApplyOnly__ takes effect. </li><li> __ApplyAndMonitor__: This is the default value. The LCM applies any new configurations. After initial application of a new configuration, if the target node drifts from the desired state, DSC reports the discrepancy in logs. Note that DSC will attempt to apply the configuration until it is successful before __ApplyAndMonitor__ takes effect.</li><li>__ApplyAndAutoCorrect__: DSC applies any new configurations. After initial application of a new configuration, if the target node drifts from the desired state, DSC reports the discrepancy in logs, and then re-applies the current configuration.</li></ul>|
 | ConfigurationModeFrequencyMins| UInt32| How often, in minutes, the current configuration is checked and applied. This property is ignored if the ConfigurationMode property is set to ApplyOnly. The default value is 15.|
 | DebugMode| string| Possible values are __None__, __ForceModuleImport__, and __All__. <ul><li>Set to __None__ to use cached resources. This is the default and should be used in production scenarios.</li><li>Setting to __ForceModuleImport__, causes the LCM to reload any DSC resource modules, even if they have been previously loaded and cached. This impacts the performance of DSC operations as each module is reloaded on use. Typically you would use this value while debugging a resource</li><li>In this release, __All__ is same as __ForceModuleImport__</li></ul> |
 | RebootNodeIfNeeded| bool| Set this to __$true__ to automatically reboot the node after a configuration that requires reboot is applied. Otherwise, you will have to manually reboot the node for any configuration that requires it. The default value is __$false__. To use this setting when a reboot condition is enacted by something other than DSC (such as Windows Installer), combine this setting with the [xPendingReboot](https://github.com/powershell/xpendingreboot) module.|

gallery/TOC.md

@@ -11,6 +11,7 @@
 ### [Creating a PowerShellGallery Account](psgallery/psgallery_creating_an_account.md)
 ### [Creating and publishing items](psgallery/Creating-and-Publishing-an-item.md)
 ### [Publishing guidelines and best practices](psgallery/psgallery-PublishingGuidelines.md)
+### [Item manifest and Gallery UI](psgallery/psgallery_ItemManifestAffectingUI.md)
 ### [Unlisting items](psgallery/psgallery_unlist_items.md)
 ### [Deleting items](psgallery/Deleting-Items.md)
 ### [Managing item owners](psgallery/Managing-Item-Owners.md)

gallery/psgallery/psgallery_ItemManifestAffectingUI.md

@@ -0,0 +1,139 @@
+# Item manifest values that impact the PowerShell Gallery UI
+
+This topic provides publishers with summary information on how to modify the manifest for their PowerShell Gallery publications so that features of PowerShellGet cmdlets and the PowerShell Gallery UI will be affected. 
+This content is organized by where the change will appear, starting with the center section, then the navigation area on the left. There is a detail section covering tags, which identifies important tags, as well as some of the more commonly used tags. 
+There are two topics that provide manifest examples: 
+
+* For modules, see [Update Module Manifest](https://docs.microsoft.com/en-us/powershell/gallery/psget/module/psget_update-modulemanifest)
+* For scripts, see [Create Script File with Metadata](https://docs.microsoft.com/en-us/powershell/gallery/psget/script/psget_new-scriptfileinfo)
+
+## PowerShell Gallery Feature Elements Controlled by the Manifest
+
+The table below shows the elements of the PowerShell Gallery item page UI that are controlled by the publisher.
+Each item indicates if it may be controlled by the module or script manifest.
+
+| UI Element | Description | Module | Script | 
+| --- | --- | --- | --- |
+| **Title** | This is the name of the item that is published to the Gallery  | No | No |
+| **Version** | The version displayed is the version string in the metadata, and a prerelease if is specified. The primary portion of the version in a Module manifest is the ModuleVersion. For a script, it is identified as .VERSION. If a prerelease version string is specified, it will be appended to the ModuleVersion for modules, or specified as part of .VERSION for scripts. There is documentation for specifying prerelease strings in [modules](https://docs.microsoft.com/en-us/powershell/gallery/psget/module/prereleasemodule), and in [scripts](https://docs.microsoft.com/en-us/powershell/gallery/psget/script/prereleasescript) | Yes | Yes |
+| **Description** | This is the Description in the module manifest, and in a script file manifest it is .DESCRIPTION | Yes | Yes |
+| **Require license acceptance** | A module can require that the user accept a license, by modifying the module manifest with RequireLicenseAcceptance = $true, supplying a LicenseURI, and providing a license.txt file in the root of the module folder. Additional information is available in the [Require License Acceptance](https://docs.microsoft.com/en-us/powershell/gallery/psgallery/psgallery_requires_license_acceptance) topic. | Yes | No |
+| **Release notes** | For modules, this information is drawn from the ReleaseNotes section, under PSData\PrivateData. In script manifests, it is the .RELEASENOTES element. | Yes | Yes |
+| **Owners** | Owners are the list of users in the PowerShell Gallery who can update an item. The owner list is not included in the item manifest. Additional documentation describes how to [manage item owners](https://docs.microsoft.com/en-us/powershell/gallery/psgallery/managing-item-owners). | No | No |
+| **Author** | This is included in the module manifest as the Author, and in a script manifest as .AUTHOR. The Author field is often used to specify a company or organization associated with an item. | Yes | Yes |
+| **Copyright** | This is the Copyright field in the module manifest, and .COPYRIGHT in a script manifest. | Yes | Yes |
+| **FileList** | The file list is drawn from the package when it is published to the PowerShell Gallery. It is not controllable by the manifest information. Note: there is an additional .nuspec file listed with each item in the PowerShell Gallery that is not present after installing the item on a system. This is the Nuget package manifest for the item, and may be ignored. | No | No |
+| **Tags** | For modules, Tags are included under PSData\PrivateData. For scripts, the section is labelled .TAGS. Note that tags cannot contain spaces, even when they are in quotes. Tags have additional requirements and meanings, which are described later in this topic in the Tag Details section. | Yes | Yes |
+| **Cmdlets** | This is provided in the module manifest using CmdletsToExport. Note that the best practice is to explicitly list the items, rather than using the wildcard “*”, as that will improve the load-module performance for users. | Yes | No |
+| **Functions** | This is provided in the module manifest using FunctionsToExport. Note that the best practice is to explicitly list the items, rather than using the wildcard “*”, as that will improve the load-module performance for users. | Yes | No |
+| **DSC Resources** | For modules that will be used on PowerShell version 5.0 and above, this is provided in the manifest using DscResourcesToExport. If the module is to be used in PowerShell 4, the DSCResourcesToExport should not be used as it is not a supported manifest key. (DSC was not available prior to PowerShell 4.) | Yes | No |
+| **Workflows** | Workflows are published to the PowerShell Gallery as scripts, and identified as workflows (see [Connect-AzureVM](https://www.powershellgallery.com/packages/Connect-AzureVM/1.0/Content/Connect-AzureVM.ps1) for an example) in the code. This is not controlled by the manifest. | No | No |
+| **Role capabilities** | This will be listed when the module published to the PowerShell Gallery contains one or more role capability (.psrc) files, which are used by JEA. See the JEA documentation for more details on [role capabilities](https://docs.microsoft.com/en-us/powershell/jea/role-capabilities). | Yes | No |
+| **PowerShell Editions** | This is specified in a script or module manifest. For modules designed to be used with PowerShell 5.0 and below, this is controlled using Tags. For Desktop, use the tag PSEdition_Desktop, and for core, use the tag PSEdition_Core. For modules that will be used only on PowerShell 5.1 and above, there is a CompatiblePSEditions key in the main manifest. For additional detail, review the PS Edition feature in [the PowerShell Get documentation](https://docs.microsoft.com/en-us/powershell/gallery/psget/module/modulewithpseditionsupport). | Yes | Yes |
+| **Dependencies** | Dependencies are the modules in the PowerShell Gallery that are declared in either the module as RequiredModules, or in the script manifest as #Requires –Module (name). | Yes | Yes |
+| **Minimum Powershell version** | This can be specified in a module manifest as PowerShellVersion | Yes | No |
+| **Version History** | The version history reflects the updates made to a module in the PowerShell Gallery. If a version of an item is hidden using the Delete feature, it will not be displayed in the version history, except to the item owners. | No | No |
+| **Project Site** | The project site is provided for modules in the Privatedata\PSData section of the module manifest by specifying a ProjectURI. In the script manifest, it is controlled by specifying .PROJECTURI. | Yes | Yes |
+| **License** | A license link is provided for modules in the Privatedata\PSData section of the module manifest by specifying a LicenseURI. In the script manifest, it is controlled by specifying .LICENSEURI. It is important to note that if a license is not provided via the LicenseURI, or within a module, then the terms of use for the PowerShell Gallery specify the terms of use for the item. See the terms of use for details. | Yes | Yes |
+
+## Editing item details
+
+The PowerShell Gallery Edit item page allows publishers to change several of the fields displayed for an item, specifically:
+
+* Title
+* Description
+* Summary
+* Icon URL
+* Project home page URL
+* Authors
+* Copyright
+* Tags
+* Release notes
+* Require license
+
+This approach is not generally recommended, except when needed to correct what is displayed for an older version of a module. 
+Users who acquire the module will see the metadata does not match what is displayed in the PowerShell Gallery, which raises concerns about the item. 
+This will frequently result in inquiries going to to the item owners to confirm the change. 
+It is strongly recommended that any time this approach is used, a new version of the item should be published with the same changes. 
+
+## Tag Details
+
+Tags are simple strings consumers use to find items. 
+Tags are most valuable when they are used consistently across many items related to the same topic. Using multiple flavors of the same word (for example database and databases, or test and testing) typically provides little benefit. 
+Tags are single-word case-insensitive strings and cannot include blanks. If there is a phrase you believe users will search for, add that to the item description and it will be found in the search results. Use Pascal casing, hyphen, underscore, or period if you are trying to improve readability. Be cautious about creating long, complex, and unusual tags, as they are often misspelled. 
+
+There are tags that are important to note, as the PowerShell Gallery and PowerShellGet cmdlets treat them uniquely. PSEdition_Desktop and PSEdition_Core are the specific examples, and are described above. 
+
+As noted above, tags provide the most value when they are specific, and used consistently across many items. 
+As a publisher trying to locate the best tags to use, the easiest approach is to search the PowerShell Gallery for tags you are considering. 
+Ideally, there will be many items returned, and the item descriptions will align with your use of that key word. 
+
+For reference, here are some most commonly used tags as of 12/14/2017. 
+In some cases, there are similar but perhaps less ideal options listed beside the tag.
+It is a best practice to use the Preferred Tag, as that will result in less noise, and better search results for consumers. 
+
+
+| **Preferred tag** | **Alternatives and notes** |
+| --- | --- |
+| **Azure** |  |
+| **DSC** | DesiredStateConfiguration is less desirable, it’s too long |
+| **ResourceManager** | ARM is used to describe group of processors, and should not be used for Azure Resource Manager | **DSCResourceKit** |  |
+| **SQL** |  |
+| **AWS** |  |
+| **DSCResource** |  |
+| **Automation** |  |
+| **REST** |  |
+| **ActiveDirectory** | AD is not currently used by itself  |
+| **SQLServer** |  |
+| **DBA** |  |
+| **Security** | Defense is less precise |
+| **Database** | Databases (plural) is less desirable |
+| **DevOps** |  |
+| **Windows** |  |
+| **Build** |  |
+| **Deployment** | Deploy is used somewhat less often |
+| **Cloud** |  |
+| **GIT** |  |
+| **Test** | Testing is less desirable |
+| **VersionControl** | Version is less precise, although used more frequently  |
+| **Logging** | Preferred use of logging as an action |
+| **Log** | Preferred use of Log as a thing |
+| **Backup** |  |
+| **IaaS** |  |
+| **Linux** |  |
+| **IIS** |  |
+| **AzureAutomation** |  |
+| **Storage** |  |
+| **GitHub** |  |
+| **Json** |  |
+| **Exchange** |  |
+| **Network** | Networking is similar, less often used |
+| **SharePoint** |  |
+| **Reporting** | Reporting is an action, report is a thing |
+| **Report** | Report is a thing |
+| **WinRM** |  |
+| **Monitoring** |  |
+| **VSTS** |  |
+| **Excel** |  |
+| **Google** |  |
+| **Color** |  |
+| **DNS** |  |
+| **Office365** | Spelling out Office is preferable. O365 is less commonly used, although shorter | **Gitlab** |  |
+| **Pester** |  |
+| **AzureAD** |  |
+| **HTML** |  |
+| **Hyper-V** | HyperV is less common as a tag |
+| **Configuration** |  |
+| **ChatOps** |  |
+| **PackageManagement** |  |
+| **WMI** |  |
+| **Firewall** |  |
+| **Docker** |  |
+| **Appveyor** |  |
+| **AzureRm** | Used primarily for the AzureRM modules |
+| **Zip** |  |
+| **MSI** |  |
+| **Mac** |  |
+| **PoshBot** |  |
+
+

reference/3.0/Microsoft.PowerShell.Core/About/about_Hash_Tables.md

@@ -441,7 +441,7 @@ This method works only for classes that have a null constructor, that is, a
 constructor that has no parameters. The object properties must be public and
 settable.
 
-For more information, see [about_Object_Creation(about_Object_Creation.md)].
+For more information, see [about_Object_Creation](about_Object_Creation.md).
 
 ### ConvertFrom-StringData
 

reference/3.0/Microsoft.PowerShell.Core/About/about_Requires.md

@@ -29,7 +29,6 @@ functions, cmdlets, or snap-ins.
 #Requires -PSSnapin <PSSnapin-Name> [-Version <N>[.<n>]]
 #Requires -Modules { <Module-Name> | <Hashtable> }
 #Requires -ShellId <ShellId>
-#Requires -RunAsAdministrator
 ```
 
 ### RULES FOR USE
@@ -40,7 +39,7 @@ functions, cmdlets, or snap-ins.
 
 ### PARAMETERS
 
--Version <N>[.<n>]
+-Version \<N\>[.\<n\>]
 
 Specifies the minimum version of Windows PowerShell that the script requires.
 Enter a major version number and optional minor version number.
@@ -51,7 +50,7 @@ For example:
 #Requires -Version 3.0
 ```
 
--PSSnapin <PSSnapin-Name> [-Version <N>[.<n>]]
+-PSSnapin \<PSSnapin-Name\> [-Version \<N\>[.\<n\>]]
 
 Specifies a Windows PowerShell snap-in that the script requires. Enter the
 snap-in name and an optional version number.
@@ -62,7 +61,7 @@ For example:
 #Requires -PSSnapin DiskSnapin -Version 1.2
 ```
 
--Modules <Module-Name> &#124; <Hashtable>
+-Modules \<Module-Name\> &#124; \<Hashtable\>
 
 Specifies Windows PowerShell modules that the script requires. Enter the
 module name and an optional version number. The Modules parameter is