diff --git a/dsc/pullClient.md b/dsc/pullClient.md index 4f323d7be9f7..a2f66073ccf0 100644 --- a/dsc/pullClient.md +++ b/dsc/pullClient.md @@ -4,13 +4,17 @@ ms.topic: conceptual keywords: dsc,powershell,configuration,setup title: Setting up a DSC pull client --- - # Setting up a DSC pull client > Applies To: Windows PowerShell 4.0, Windows PowerShell 5.0 -Each target node has to be told to use pull mode and given the URL or file location where it can contact the pull server to get configurations and resources, and where it should send report data. +> [!IMPORTANT] +> The Pull Server (Windows Feature *DSC-Service*) will be deprecated in a future version of Windows Server. It is recommended to +> begin transitioning managed clients to [Azure Automation DSC](/azure/automation/automation-dsc-getting-started) +> (includes features beyond Pull Server on Windows Server) or one of the community solutions +> listed [here](pullserver.md#community-solutions-for-pull-service). +Each target node has to be told to use pull mode and given the URL or file location where it can contact the pull server to get configurations and resources, and where it should send report data. The following topics explain how to set up pull clients: diff --git a/dsc/pullClientConfigID.md b/dsc/pullClientConfigID.md index c6633f26bc0b..a0e5144719b2 100644 --- a/dsc/pullClientConfigID.md +++ b/dsc/pullClientConfigID.md @@ -4,11 +4,16 @@ ms.topic: conceptual keywords: dsc,powershell,configuration,setup title: Setting up a pull client using configuration ID --- - # Setting up a pull client using configuration ID > Applies To: Windows PowerShell 5.0 +> [!IMPORTANT] +> The Pull Server (Windows Feature *DSC-Service*) will be deprecated in a future version of Windows Server. It is recommended to +> begin transitioning managed clients to [Azure Automation DSC](/azure/automation/automation-dsc-getting-started) +> (includes features beyond Pull Server on Windows Server) or one of the community solutions +> listed [here](pullserver.md#community-solutions-for-pull-service). + Each target node has to be told to use pull mode and given the URL where it can contact the pull server to get configurations. To do this, you have to configure the Local Configuration Manager (LCM) with the necessary information. To configure the LCM, you create a special type of configuration, decorated with the **DSCLocalConfigurationManager** attribute. For more information about configuring the LCM, see [Configuring the Local Configuration Manager](metaConfig.md). > **Note**: This topic applies to PowerShell 5.0. For information on setting up a pull client in PowerShell 4.0, see [Setting up a pull client using configuration ID in PowerShell 4.0](pullClientConfigID4.md) diff --git a/dsc/pullClientConfigNames.md b/dsc/pullClientConfigNames.md index 68dc7dc7ec96..37c7927f09fc 100644 --- a/dsc/pullClientConfigNames.md +++ b/dsc/pullClientConfigNames.md @@ -4,11 +4,16 @@ ms.topic: conceptual keywords: dsc,powershell,configuration,setup title: Setting up a pull client using configuration names --- - # Setting up a pull client using configuration names > Applies To: Windows PowerShell 5.0 +> [!IMPORTANT] +> The Pull Server (Windows Feature *DSC-Service*) will be deprecated in a future version of Windows Server. It is recommended to +> begin transitioning managed clients to [Azure Automation DSC](/azure/automation/automation-dsc-getting-started) +> (includes features beyond Pull Server on Windows Server) or one of the community solutions +> listed [here](pullserver.md#community-solutions-for-pull-service). + Each target node has to be told to use pull mode and given the URL where it can contact the pull server to get configurations. To do this, you have to configure the Local Configuration Manager (LCM) with the necessary information. To configure the LCM, you create a special type of configuration, decorated with the **DSCLocalConfigurationManager** attribute. diff --git a/dsc/pullServer.md b/dsc/pullServer.md index 84dc8a8bc86e..5df2cfd1f2bd 100644 --- a/dsc/pullServer.md +++ b/dsc/pullServer.md @@ -8,6 +8,12 @@ title: DSC Pull Service > Applies To: Windows PowerShell 5.0 +> [!IMPORTANT] +> The Pull Server (Windows Feature *DSC-Service*) will be deprecated in a future version of Windows Server. It is recommended to +> begin transitioning managed clients to [Azure Automation DSC](/azure/automation/automation-dsc-getting-started) +> (includes features beyond Pull Server on Windows Server) or one of the community solutions +> listed [here](pullserver.md#community-solutions-for-pull-service). + Local Configuration Manager can be centrally managed by a Pull Service solution. When using this approach, the node that is being managed is registered with a service and assigned a configuration in LCM settings. @@ -16,17 +22,17 @@ for the configuration are downloaded to the machine and used by LCM to manage the configuration. Information about the state of the machine being managed is uploaded to the service for reporting. -This concept is referred to as "pull service". +This concept is referred to as "pull service." The current options for pull service include: - Azure Automation Desired State Configuration service - A pull service running on Windows Server -- Community maintained open source solutions +- Community maintained open-source solutions - An SMB share **The recommended solution**, and the option with the most features available, -is [Azure Automation DSC](https://docs.microsoft.com/en-us/azure/automation/automation-dsc-getting-started). +is [Azure Automation DSC](/azure/automation/automation-dsc-getting-started). The Azure service can manage nodes on-premises in private datacenters, or in public clouds such as Azure and AWS. @@ -37,20 +43,20 @@ consider limiting outbound traffic to only the published Azure IP range Features of the online service that are not currently available in the pull service on Windows Server include: - All data is encrypted in transit and at rest - Client certificates are created and managed automatically -- Secrets store for centrally managing [passwords/credentials](https://docs.microsoft.com/en-us/azure/automation/automation-credentials), or [variables](https://docs.microsoft.com/en-us/azure/automation/automation-variables) such as server names or connection strings +- Secrets store for centrally managing [passwords/credentials](/azure/automation/automation-credentials), or [variables](/azure/automation/automation-variables) such as server names or connection strings - Centrally manage node [LCM configuration](metaConfig.md#basic-settings) - Centrally assign configurations to client nodes - Release configuration changes to "canary groups" for testing before reaching production - Graphical reporting - Status detail at the DSC resource level of granularity - Verbose error messages from client machines for troubleshooting -- [Integration with Azure Log Analytics](https://docs.microsoft.com/en-us/azure/automation/automation-dsc-diagnostics) for alerting, automated tasks, Android/iOS app for reporting and alerting +- [Integration with Azure Log Analytics](/azure/automation/automation-dsc-diagnostics) for alerting, automated tasks, Android/iOS app for reporting and alerting ## DSC pull service in Windows Server It is possible to configuring a pull service to run on Windows Server. -Please be advised that the pull service solution included in Windows Server +Be advised that the pull service solution included in Windows Server includes only capabilities of storing configurations/modules for download and capturing report data in to database. It does not include many of the capabilities offered by the service in Azure @@ -73,123 +79,147 @@ The best way to configure Windows Server to host pull service is to use a DSC configuration. An example script is provided below. -### Using the xDSCWebService resource +### Supported database systems + +|WMF 4.0 |WMF 5.0 |WMF 5.1 |WMF 5.1 (Windows Server Insider Preview 17090)| +|---------|---------|---------|---------| +|MDB |ESENT (Default), MDB |ESENT (Default), MDB|ESENT (Default), SQL Server, MDB + +Starting in release 17090 of [Windows Server Insider Preview](https://www.microsoft.com/en-us/software-download/windowsinsiderpreviewserver), SQL Server +is a supported option for the Pull Service (Windows Feature *DSC-Service*). This provides a new +option for scaling large DSC environments that have not migrated to [Azure Automation DSC](/azure/automation/automation-dsc-getting-started). + +> **Note**: SQL Server support will not be added to previous versions of WMF 5.1 (or earlier) +> and will only be available on Windows Server versions greater than or equal to 17090. -The easiest way to set up a web pull server is to use the xWebService resource, -included in the xPSDesiredStateConfiguration module. +To configure the pull server to use SQL Server, set **SqlProvider** to `$true` and **SqlConnectionString** +to a valid SQL Server Connection String. For more information, see [SqlClient Connection Strings](/dotnet/framework/data/adonet/connection-string-syntax#sqlclient-connection-strings). +For an example of SQL Server configuration with **xDscWebService**, first read [Using the xDscWebService resource](#using-the-xdscwebservice-resource) and then review [Sample_xDscWebServiceRegistration_UseSQLProvider.ps1 on GitHub](https://github.com/PowerShell/xPSDesiredStateConfiguration/blob/master/Examples/Sample_xDscWebServiceRegistration_UseSQLProvider.ps1). + +### Using the xDscWebService resource + +The easiest way to set up a web pull server is to use the **xDscWebService** resource, +included in the **xPSDesiredStateConfiguration** module. The following steps explain how to use the resource in a configuration that sets up the web service. -1. Call the [Install-Module](https://technet.microsoft.com/en-us/library/dn807162.aspx) cmdlet to install the **xPSDesiredStateConfiguration** module. **Note**: **Install-Module** is included in the **PowerShellGet** module, which is included in PowerShell 5.0. You can download the **PowerShellGet** module for PowerShell 3.0 and 4.0 at [PackageManagement PowerShell Modules Preview](https://www.microsoft.com/en-us/download/details.aspx?id=49186). -1. Get an SSL certificate for the DSC Pull server from a trusted Certificate Authority, either within your organization or a public authority. The certificate received from the authority is usually in the PFX format. Install the certificate on the node that will become the DSC Pull server in the default location which should be CERT:\LocalMachine\My. Make a note of the certificate thumbprint. -1. Select a GUID to be used as the Registration Key. To generate one using PowerShell enter the following at the PS prompt and press enter: '``` [guid]::newGuid()```' or '```New-Guid```'. This key will be used by client nodes as a shared key to authenticate during registration. For more information see the Registration Key section below. -1. In the PowerShell ISE, start (F5) the following configuration script (included in the Example folder of the **xPSDesiredStateConfiguration** module as Sample_xDscWebService.ps1). This script sets up the pull server. +1. Call the [Install-Module](/powershell/module/PowershellGet/Install-Module) cmdlet to install the **xPSDesiredStateConfiguration** module. **Note**: **Install-Module** is included in the **PowerShellGet** module, which is included in PowerShell 5.0. You can download the **PowerShellGet** module for PowerShell 3.0 and 4.0 at [PackageManagement PowerShell Modules Preview](https://www.microsoft.com/en-us/download/details.aspx?id=49186). +1. Get an SSL certificate for the DSC Pull server from a trusted Certificate Authority, either within your organization or a public authority. The certificate received from the authority is usually in the PFX format. Install the certificate on the node that will become the DSC Pull server in the default location, which should be CERT:\LocalMachine\My. Make a note of the certificate thumbprint. +1. Select a GUID to be used as the Registration Key. To generate one using PowerShell enter the following at the PS prompt and press enter: '``` [guid]::newGuid()```' or '```New-Guid```'. This key will be used by client nodes as a shared key to authenticate during registration. For more information, see the Registration Key section below. +1. In the PowerShell ISE, start (F5) the following configuration script (included in the Examples folder of the **xPSDesiredStateConfiguration** module as Sample_xDscWebServiceRegistration.ps1). This script sets up the pull server. ```powershell - configuration Sample_xDscPullServer +configuration Sample_xDscWebServiceRegistration +{ + param + ( + [string[]]$NodeName = 'localhost', + + [ValidateNotNullOrEmpty()] + [string] $certificateThumbPrint, + + [Parameter(HelpMessage='This should be a string with enough entropy (randomness) to protect the registration of clients to the pull server. We will use new GUID by default.')] + [ValidateNotNullOrEmpty()] + [string] $RegistrationKey # A guid that clients use to initiate conversation with pull server + ) + + Import-DSCResource -ModuleName xPSDesiredStateConfiguration + + Node $NodeName { - param - ( - [string[]]$NodeName = 'localhost', - - [ValidateNotNullOrEmpty()] - [string] $certificateThumbPrint, - - [Parameter(Mandatory)] - [ValidateNotNullOrEmpty()] - [string] $RegistrationKey - ) - - Import-DSCResource -ModuleName xPSDesiredStateConfiguration - Import-DSCResource –ModuleName PSDesiredStateConfiguration - - Node $NodeName - { - WindowsFeature DSCServiceFeature - { - Ensure = 'Present' - Name = 'DSC-Service' - } - - xDscWebService PSDSCPullServer - { - Ensure = 'Present' - EndpointName = 'PSDSCPullServer' - Port = 8080 - PhysicalPath = "$env:SystemDrive\inetpub\PSDSCPullServer" - CertificateThumbPrint = $certificateThumbPrint - ModulePath = "$env:PROGRAMFILES\WindowsPowerShell\DscService\Modules" - ConfigurationPath = "$env:PROGRAMFILES\WindowsPowerShell\DscService\Configuration" - State = 'Started' - DependsOn = '[WindowsFeature]DSCServiceFeature' - UseSecurityBestPractices = $false - } - - File RegistrationKeyFile - { - Ensure = 'Present' - Type = 'File' - DestinationPath = "$env:ProgramFiles\WindowsPowerShell\DscService\RegistrationKeys.txt" - Contents = $RegistrationKey - } + WindowsFeature DSCServiceFeature + { + Ensure = "Present" + Name = "DSC-Service" } - } + xDscWebService PSDSCPullServer + { + Ensure = "Present" + EndpointName = "PSDSCPullServer" + Port = 8080 + PhysicalPath = "$env:SystemDrive\inetpub\PSDSCPullServer" + CertificateThumbPrint = $certificateThumbPrint + ModulePath = "$env:PROGRAMFILES\WindowsPowerShell\DscService\Modules" + ConfigurationPath = "$env:PROGRAMFILES\WindowsPowerShell\DscService\Configuration" + State = "Started" + DependsOn = "[WindowsFeature]DSCServiceFeature" + RegistrationKeyPath = "$env:PROGRAMFILES\WindowsPowerShell\DscService" + AcceptSelfSignedCertificates = $true + Enable32BitAppOnWin64 = $false + } + + File RegistrationKeyFile + { + Ensure = 'Present' + Type = 'File' + DestinationPath = "$env:ProgramFiles\WindowsPowerShell\DscService\RegistrationKeys.txt" + Contents = $RegistrationKey + } + } +} ``` 1. Run the configuration, passing the thumbprint of the SSL certificate as the **certificateThumbPrint** parameter and a GUID registration key as the **RegistrationKey** parameter: ```powershell - # To find the Thumbprint for an installed SSL certificate for use with the pull server list all certificates in your local store - # and then copy the thumbprint for the appropriate certificate by reviewing the certificate subjects - dir Cert:\LocalMachine\my +# To find the Thumbprint for an installed SSL certificate for use with the pull server list all certificates in your local store +# and then copy the thumbprint for the appropriate certificate by reviewing the certificate subjects +dir Cert:\LocalMachine\my - # Then include this thumbprint when running the configuration - Sample_xDSCPullServer -certificateThumbprint 'A7000024B753FA6FFF88E966FD6E19301FAE9CCC' -RegistrationKey '140a952b-b9d6-406b-b416-e0f759c9c0e4' -OutputPath c:\Configs\PullServer - - # Run the compiled configuration to make the target node a DSC Pull Server - Start-DscConfiguration -Path c:\Configs\PullServer -Wait -Verbose +# Then include this thumbprint when running the configuration +Sample_xDSCPullServer -certificateThumbprint 'A7000024B753FA6FFF88E966FD6E19301FAE9CCC' -RegistrationKey '140a952b-b9d6-406b-b416-e0f759c9c0e4' -OutputPath c:\Configs\PullServer +# Run the compiled configuration to make the target node a DSC Pull Server +Start-DscConfiguration -Path c:\Configs\PullServer -Wait -Verbose ``` #### Registration Key -To allow client nodes to register with the server so that they can use configuration names instead of a configuration ID, a registration key which was created by the above configuration is saved in a file named `RegistrationKeys.txt` in `C:\Program Files\WindowsPowerShell\DscService`. The registration key functions as a shared secret used during the initial registration by the client with the pull server. The client will generate a self-signed certificate which is used to uniquely authenticate to the pull server once registration is successfully completed. The thumbprint of this certificate is stored locally and associated with the URL of the pull server. +To allow client nodes to register with the server so that they can use configuration names instead of a configuration ID, a registration key that was created by the above configuration is saved in a file named `RegistrationKeys.txt` in `C:\Program Files\WindowsPowerShell\DscService`. The registration key functions as a shared secret used during the initial registration by the client with the pull server. The client will generate a self-signed certificate that is used to uniquely authenticate to the pull server once registration is successfully completed. The thumbprint of this certificate is stored locally and associated with the URL of the pull server. > **Note**: Registration keys are not supported in PowerShell 4.0. -In order to configure a node to authenticate with the pull server the registration key needs to be in the metaconfiguration for any target node that will be registering with this pull server. Note that the **RegistrationKey** in the metaconfiguration below is removed after the target machine has successfully registered, and that the value '140a952b-b9d6-406b-b416-e0f759c9c0e4' must match the value stored in the RegistrationKeys.txt file on the pull server. Always treat the registration key value securely, because knowing it allows any target machine to register with the pull server. +In order to configure a node to authenticate with the pull server, the registration key needs to be in the metaconfiguration for any target node that will be registering with this pull server. Note that the **RegistrationKey** in the metaconfiguration below is removed after the target machine has successfully registered, and that the value '140a952b-b9d6-406b-b416-e0f759c9c0e4' must match the value stored in the RegistrationKeys.txt file on the pull server. Always treat the registration key value securely, because knowing it allows any target machine to register with the pull server. ```powershell [DSCLocalConfigurationManager()] -configuration PullClientConfigID +configuration Sample_MetaConfigurationToRegisterWithLessSecurePullServer { - Node localhost + param + ( + [ValidateNotNullOrEmpty()] + [string] $NodeName = 'localhost', + + [ValidateNotNullOrEmpty()] + [string] $RegistrationKey, #same as the one used to setup pull server in previous configuration + + [ValidateNotNullOrEmpty()] + [string] $ServerName = 'localhost' #node name of the pull server, same as $NodeName used in previous configuration + ) + + Node $NodeName { Settings { - RefreshMode = 'Pull' - RefreshFrequencyMins = 30 - RebootNodeIfNeeded = $true + RefreshMode = 'Pull' } ConfigurationRepositoryWeb CONTOSO-PullSrv { - ServerURL = 'https://CONTOSO-PullSrv:8080/PSDSCPullServer.svc' - RegistrationKey = '140a952b-b9d6-406b-b416-e0f759c9c0e4' + ServerURL = "https://$ServerName`:8080/PSDSCPullServer.svc" # notice it is https + RegistrationKey = $RegistrationKey ConfigurationNames = @('ClientConfig') } ReportServerWeb CONTOSO-PullSrv { - ServerURL = 'https://CONTOSO-PullSrv:8080/PSDSCPullServer.svc' - RegistrationKey = '140a952b-b9d6-406b-b416-e0f759c9c0e4' + ServerURL = "https://$ServerName`:8080/PSDSCPullServer.svc" # notice it is https + RegistrationKey = $RegistrationKey } } } -PullClientConfigID -OutputPath c:\Configs\TargetNodes - - +Sample_MetaConfigurationToRegisterWithLessSecurePullServer -RegistrationKey $RegistrationKey -OutputPath c:\Configs\TargetNodes ``` > **Note**: The **ReportServerWeb** section allows reporting data to be sent to the pull server. @@ -200,7 +230,7 @@ of the pull server protocol so an initial registration is required. Conversely, the presence of a **ConfigurationID** means that the V1 version of the pull server protocol is used and there is no registration processing. ->**Note**: In a PUSH scenario, a bug exists in the current relase that makes it necessary to define a ConfigurationID property in the metaconfiguration file for nodes that have never registered with a pull server. This will force the V1 Pull Server protocol and avoid registration failure messages. +>**Note**: In a PUSH scenario, a bug exists in the current release that makes it necessary to define a ConfigurationID property in the metaconfiguration file for nodes that have never registered with a pull server. This will force the V1 Pull Server protocol and avoid registration failure messages. ## Placing configurations and resources @@ -214,32 +244,32 @@ to correctly process them. ### DSC resource module package format Each resource module needs to be zipped and named -according the following pattern `{Module Name}_{Module Version}.zip`. +according to the following pattern `{Module Name}_{Module Version}.zip`. For example, a module named xWebAdminstration with a module version of 3.1.2.0 would be named 'xWebAdministration_3.2.1.0.zip'. Each version of a module must be contained in a single zip file. -Since there is only a single version of a resource in each zip file +Since there is only a single version of a resource in each zip file, the module format added in WMF 5.0 with support for multiple module versions in a single directory is not supported. This means that before packaging up DSC resource modules for use with pull server you will need to make a small change to the directory structure. The default format of modules containing DSC resource in WMF 5.0 is '{Module Folder}\{Module Version}\DscResources\{DSC Resource Folder}\'. -Before packaging up for the pull server simply +Before packaging up for the pull server, remove the **{Module version}** folder so the path becomes '{Module Folder}\DscResources\{DSC Resource Folder}\'. With this change, zip the folder as described above and place these zip files in the **ModulePath** folder. -Use `new-dscchecksum {module zip file}` to create a checksum file -for the newly-added module. +Use `New-DscChecksum {module zip file}` to create a checksum file +for the newly added module. ### Configuration MOF format A configuration MOF file needs to be paired with a checksum file so that an LCM on a target node can validate the configuration. To create a checksum, call the -[New-DSCCheckSum](https://technet.microsoft.com/en-us/library/dn521622.aspx) cmdlet. +[New-DscChecksum](/powershell/module/PSDesiredStateConfiguration/New-DscChecksum) cmdlet. The cmdlet takes a **Path** parameter that specifies the folder where the configuration MOF is located. The cmdlet creates a checksum file named `ConfigurationMOFName.mof.checksum`, @@ -257,24 +287,24 @@ In order to make setting up, validating and managing the pull server easier, the following tools are included as examples in the latest version of the xPSDesiredStateConfiguration module: -1. A module that will help with packaging DSC resource modules and configuration files for use on the pull server. [PublishModulesAndMofsToPullServer.psm1](https://github.com/PowerShell/xPSDesiredStateConfiguration/blob/dev/DSCPullServerSetup/PublishModulesAndMofsToPullServer.psm1). Examples below: +1. A module that will help with packaging DSC resource modules and configuration files for use on the pull server. [PublishModulesAndMofsToPullServer.psm1](https://github.com/PowerShell/xPSDesiredStateConfiguration/blob/master/DSCPullServerSetup/PublishModulesAndMofsToPullServer.psm1). Examples below: ```powershell # Example 1 - Package all versions of given modules installed locally and MOF files are in c:\LocalDepot - $moduleList = @("xWebAdministration", "xPhp") + $moduleList = @('xWebAdministration', 'xPhp') Publish-DSCModuleAndMof -Source C:\LocalDepot -ModuleNameList $moduleList # Example 2 - Package modules and mof documents from c:\LocalDepot Publish-DSCModuleAndMof -Source C:\LocalDepot -Force ``` -1. A script that validates the pull server is configured correctly. [PullServerSetupTests.ps1](https://github.com/PowerShell/xPSDesiredStateConfiguration/blob/dev/DSCPullServerSetup/PullServerDeploymentVerificationTest/PullServerSetupTests.ps1). +1. A script that validates the pull server is configured correctly. [PullServerSetupTests.ps1](https://github.com/PowerShell/xPSDesiredStateConfiguration/blob/master/DSCPullServerSetup/PullServerDeploymentVerificationTest/PullServerSetupTests.ps1). ## Community Solutions for Pull Service The DSC community has authored multiple solutions to implement the pull service protocol. -For on-premises environments these offer pull service capabilities +For on-premises environments, these offer pull service capabilities and an opportunity to contribute back to the community with incremental enhancements. diff --git a/dsc/pullServerSMB.md b/dsc/pullServerSMB.md index 0fec8e54a2fe..8213f3e219d0 100644 --- a/dsc/pullServerSMB.md +++ b/dsc/pullServerSMB.md @@ -4,11 +4,16 @@ ms.topic: conceptual keywords: dsc,powershell,configuration,setup title: Setting up a DSC SMB pull server --- - # Setting up a DSC SMB pull server >Applies To: Windows PowerShell 4.0, Windows PowerShell 5.0 +> [!IMPORTANT] +> The Pull Server (Windows Feature *DSC-Service*) will be deprecated in a future version of Windows Server. It is recommended to +> begin transitioning managed clients to [Azure Automation DSC](/azure/automation/automation-dsc-getting-started) +> (includes features beyond Pull Server on Windows Server) or one of the community solutions +> listed [here](pullserver.md#community-solutions-for-pull-service). + A DSC [SMB](https://technet.microsoft.com/library/hh831795.aspx) pull server is a computer hosting SMB file shares that make DSC configuration files and DSC resources available to target nodes when those nodes ask for them. diff --git a/dsc/registryResource.md b/dsc/registryResource.md index 5d3380e536de..7bad7e5a9974 100644 --- a/dsc/registryResource.md +++ b/dsc/registryResource.md @@ -18,7 +18,7 @@ Registry [string] #ResourceName { Key = [string] ValueName = [string] - [ Ensure = [string] { Enable | Disable } ] + [ Ensure = [string] { Present | Absent } ] [ Force = [bool] ] [ Hex = [bool] ] [ DependsOn = [string[]] ] @@ -71,4 +71,4 @@ Configuration RegistryTest ``` >**Note:** Changing a registry setting in the **HKEY\_CURRENT\_USER** hive requires that the configuration runs with user credentials, rather than as the system. ->You can use the **PsDscRunAsCredential** property to specify user credentials for the configuration. For an example, see [Running DSC with user credentials](runAsUser.md) \ No newline at end of file +>You can use the **PsDscRunAsCredential** property to specify user credentials for the configuration. For an example, see [Running DSC with user credentials](runAsUser.md) diff --git a/dsc/reportServer.md b/dsc/reportServer.md index d67a40376e69..feb1d67404bc 100644 --- a/dsc/reportServer.md +++ b/dsc/reportServer.md @@ -4,11 +4,16 @@ ms.topic: conceptual keywords: dsc,powershell,configuration,setup title: Using a DSC report server --- - # Using a DSC report server > Applies To: Windows PowerShell 5.0 +> [!IMPORTANT] +> The Pull Server (Windows Feature *DSC-Service*) will be deprecated in a future version of Windows Server. It is recommended to +> begin transitioning managed clients to [Azure Automation DSC](/azure/automation/automation-dsc-getting-started) +> (includes features beyond Pull Server on Windows Server) or one of the community solutions +> listed [here](pullserver.md#community-solutions-for-pull-service). + >**Note:** The report server described in this topic is not available in PowerShell 4.0. The Local Configuration Manager (LCM) of a node can be configured to send reports about its configuration status to a pull server, which can then be queried to retrieve that data. Each time the node checks and applies diff --git a/dsc/secureServer.md b/dsc/secureServer.md index 9f9f3a0db7be..b298d2edaa2a 100644 --- a/dsc/secureServer.md +++ b/dsc/secureServer.md @@ -4,11 +4,16 @@ ms.topic: conceptual keywords: dsc,powershell,configuration,setup title: Pull server best practices --- - # Pull server best practices >Applies To: Windows PowerShell 4.0, Windows PowerShell 5.0 +> [!IMPORTANT] +> The Pull Server (Windows Feature *DSC-Service*) will be deprecated in a future version of Windows Server. It is recommended to +> begin transitioning managed clients to [Azure Automation DSC](/azure/automation/automation-dsc-getting-started) +> (includes features beyond Pull Server on Windows Server) or one of the community solutions +> listed [here](pullserver.md#community-solutions-for-pull-service). + Summary: This document is intended to include process and extensibility to assist engineers who are preparing for the solution. Details should provide best practices as identified by customers and then validated by the product team to ensure recommendations are future facing and considered stable. diff --git a/gallery/TOC.yml b/gallery/TOC.yml index cd9234e172e7..ee3dab6f949d 100644 --- a/gallery/TOC.yml +++ b/gallery/TOC.yml @@ -47,6 +47,8 @@ href: psgallery/psgallery_requires_license_acceptance.md - name: Require License Acceptance on Deploy to Azure Automation href: psgallery/psgallery_deploy_to_azure_automation_requireLicenseAcceptance.md + - name: PowerShell Gallery GDPR Compliance + href: psgallery/psgallery_gdpr_dsr.md - name: PowerShellGet href: psget/overview.md items: diff --git a/gallery/psgallery/psgallery_gdpr_dsr.md b/gallery/psgallery/psgallery_gdpr_dsr.md new file mode 100644 index 000000000000..df49385de515 --- /dev/null +++ b/gallery/psgallery/psgallery_gdpr_dsr.md @@ -0,0 +1,90 @@ +--- +ms.date: 03/27/2018 +contributor: JKeithB +ms.topic: conceptual +keywords: gallery,powershell,psgallery,GDPR +title: PowerShell Gallery GDPR Compliance +--- + +# PowerShell Gallery GDPR Compliance + +## Overview + +In May 2018, a European privacy law, the General Data Protection Regulation (GDPR), will take effect. +The GDPR imposes new rules on companies, government agencies, non-profits, and other organizations that offer goods and services to people in the European Union (EU), or that collect and analyze data tied to EU residents. The GDPR applies no matter where you are located. + +Microsoft products and services are available today to help you meet the GDPR requirements. +Read more about Microsoft Privacy policy at [Trust Center](https://www.microsoft.com/trustcenter). + +The PowerShell Gallery meets GDPR requirements. + +The Powershell Gallery stores the following information that may be provided by users, which may contain personal information: + +* PowerShell Gallery account +* Items published to the PowerShell Gallery +* Email correspondence with the PowerShell Gallery team + +Most users do not create a PowerShell Gallery account, as it is not required unless the user is going to publish an item, or use the "Contact Owner" feature in the PowerShell Gallery. +The PowerShell Gallery does not store EUII data for users who have not created a PowerShell Gallery account, other than email correspondence initiated by the user. + +Users who create a PowerShell Gallery account can publish items to the PowerShell Gallery. +Those items are expected to be PowerShell code, but may contain other information including personal information. The information below will show how you can get all the items you have published to the PowerShell Gallery. + + +## DSR Export of PowerShell Gallery Data + +The following sections describe the PowerShell Gallery supports a GDPR Data Subject Request (DSR) by explaining how to export information stored in the PowerShell Gallery, and how to request deletion of this information. + +__Email__ + +Email correspondence may include any of the following: + +* Email sent to the owners of PowerShell Gallery items if the code analysis scans detected an issue with any item they have published to the PowerShell Gallery +* Email sent by anyone to the PowerShell Gallery team using the email address in the "Contact Us" page (cgadmin@microsoft.com) +* Registered users who use the "Contact Owner" feature in the PowerShell Gallery to send email to the owner of an item in the PowerShell Gallery + +Emails sent by or to the PowerShell Gallery have a retention policy of 90 days, in order to support possible security investigations should malicious code be discovered on the PowerShell Gallery. +Emails are deleted by policy after 90 days. + +Users may request copies of all emails that sent within the previous 90 days to or from the PowerShell Gallery to their email account. This can be done by sending an email to cgadmin@microsoft.com, with the title: "DSR Request for emails relating to this account", and stating in the body what they are seeking (for example: Please send all emails sent to or received from this email address that you currently have.) All emails involving that email address within 90 days of the request will be sent to the requesting email account within 7 business days. + + +__PowerShell Gallery Account Information__ + +If you have created a PowerShell Gallery account, you can find all personal information that has been stored in PowerShell Gallery by taking the following steps: + +1. Sign in to the PowerShell Gallery, then click on your username +2. The next page displayed is the Account page, which shows the email address used for the PowerShell Gallery account + +If you have created more than one account in the PowerShell Gallery, you will need to repeat these steps for each account. + +__Items in the PowerShell Gallery__ + +To facilitate exporting all versions of all items published to the PowerShell Gallery by an user, users may download the script "GetPSGalleryItemsForAuthor" from the PowerShell Gallery, or from https://github.com/powershell/powershellgallery. This script will export a copy of every version of every item put onto the PowerShell Gallery based on the author information stored in the item. It is important to note that the Author is stored in the item manifest when you publish your item,and is not guaranteed to be the same as the account you use in the PowerShell Gallery. If you use some other value in the Author field, you will need to supply that value when using this script. + +You may download the script by using the following PowerShell command: + +```powershell +Save-Script GetPSGalleryItemsForAuthor -path -repository psgallery +``` + + +You can then run the script directly, by running the following PowerShell commands: + +```powershell +cd +.\GetPSGalleryItemsForAuthor.ps1 +``` + +You will be prompted to supply the Author and a folder on your system where you want the items to be saved. + +## Deleting Personal Data From The PowerShell Gallery + +Users who wish to delete either their PowerShell Gallery account or an item in the PowerShell Gallery must send email to cgadmin with the title: "GDPR Request for items relating to this account", and stating in the body what they are seeking, for example: + +* Please delete version x.y.z of my item "item name" _or_ +* Please delete all versions of my item "item name" _or_ +* Please delete my PowerShell Gallery account + +The PowerShell Gallery administrators will reply to the email within 7 business days, and items specified will be deleted within 30 days after the request is sent. + diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_Comment_Based_Help.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_Comment_Based_Help.md index 7bc4e70086d5..dcdce243b7d4 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_Comment_Based_Help.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_Comment_Based_Help.md @@ -124,8 +124,8 @@ or ```powershell <# -.< help keyword> -< help content> +. + #> function Get-Function { } ``` @@ -138,7 +138,7 @@ locations in the script. - At the beginning of the script file. Script help can be preceded in the script only by comments and blank lines. -- If the first item in the script body (after the help) is a function + If the first item in the script body (after the help) is a function declaration, there must be at least two blank lines between the end of the script help and the function declaration. Otherwise, the help is interpreted as being help for the function, not help for the script. @@ -155,6 +155,7 @@ For example: #> + function Get-Function { } ``` @@ -164,8 +165,8 @@ or function Get-Function { } <# -.< help keyword> -< help content> +. + #> ``` @@ -180,11 +181,10 @@ XML-based help files for the functions in a script module, you must add an "ExternalHelp" comment to each function. ```powershell -.ExternalHelp +# .ExternalHelp function { -# ... - + ... } ``` diff --git a/reference/3.0/Microsoft.PowerShell.Core/Receive-Job.md b/reference/3.0/Microsoft.PowerShell.Core/Receive-Job.md index ddb7953b09d1..eb78f029b3f4 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/Receive-Job.md +++ b/reference/3.0/Microsoft.PowerShell.Core/Receive-Job.md @@ -337,6 +337,8 @@ If the job has more results, the job is still deleted, but **Receive-Job** displ This parameter works only on custom job types. It is designed for instances of job types that save the job or the type outside of the session, such as instances of scheduled jobs. +This parameter cannot be used without the **Wait** parameter. + This parameter is introduced in Windows PowerShell 3.0. ```yaml diff --git a/reference/3.0/Microsoft.PowerShell.Utility/ConvertFrom-Json.md b/reference/3.0/Microsoft.PowerShell.Utility/ConvertFrom-Json.md index 9aff8837745a..5a756463ab7f 100644 --- a/reference/3.0/Microsoft.PowerShell.Utility/ConvertFrom-Json.md +++ b/reference/3.0/Microsoft.PowerShell.Utility/ConvertFrom-Json.md @@ -7,10 +7,12 @@ online version: http://go.microsoft.com/fwlink/?LinkID=217031 external help file: Microsoft.PowerShell.Commands.Utility.dll-Help.xml title: ConvertFrom-Json --- - # ConvertFrom-Json + ## SYNOPSIS + Converts a JSON-formatted string to a custom object. + ## SYNTAX ``` @@ -18,15 +20,18 @@ ConvertFrom-Json [-InputObject] [] ``` ## DESCRIPTION + The **ConvertFrom-Json** cmdlet converts a JSON-formatted string to a custom object (PSCustomObject) that has a property for each field in the JSON string. JSON is commonly used by web sites to provide a textual representation of objects. To generate a JSON string from any object, use the **ConvertTo-Json** cmdlet. -This cmdlet is introduced in Windows PowerShell 3.0. +This cmdlet is introduced in PowerShell 3.0. + ## EXAMPLES ### Example 1 + ``` PS C:\> Get-Date | Select-Object -Property * | ConvertTo-Json | ConvertFrom-Json @@ -65,29 +70,37 @@ This command uses the ConvertTo-Json and **ConvertFrom-Json** cmdlets to convert The command uses the Select-Object cmdlet to get all of the properties of the **DateTime** object. It uses the **ConvertTo-Json** cmdlet to convert the **DateTime** object to a JSON-formatted string and the **ConvertFrom-Json** cmdlet to convert the JSON-formatted string to a JSON object.. -### Example 2 -``` -PS C:\> $j = Invoke-WebRequest -Uri http://search.twitter.com/search.json?q=PowerShell | ConvertFrom-Json + +### Example 2: Get JSON strings from a web service and convert them to PowerShell objects + +```powershell +# Ensures that Invoke-WebRequest uses TLS 1.2 +[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12 +$j = Invoke-WebRequest 'https://api.github.com/repos/PowerShell/PowerShell/issues' | ConvertFrom-Json ``` -This command uses the Invoke-WebRequest cmdlet to get JSON strings from a web service and then it uses the **ConvertFrom-Json** cmdlet to convert JSON content to objects that can be managed in Windows PowerShell. +This command uses the Invoke-WebRequest cmdlet to get JSON strings from a web service and then it uses the **ConvertFrom-Json** cmdlet to convert JSON content to objects that can be managed in PowerShell. You can also use the Invoke-RestMethod cmdlet, which automatically converts JSON content to objects. -### Example 3 -``` -PS C:\> (Get-Content JsonFile.JSON) -join "`n" | ConvertFrom-Json + +### Example 3: Convert a JSON string to a custom object + +```powershell +(Get-Content JsonFile.JSON) -join '`n' | ConvertFrom-Json ``` -This example shows how to use the **ConvertFrom-Json** cmdlet to convert a JSON file to a Windows PowerShell custom object. +This example shows how to use the **ConvertFrom-Json** cmdlet to convert a JSON file to a PowerShell custom object. The command uses Get-Content cmdlet to get the strings in a JSON file. It uses the Join operator to join the strings in the file into a single string that is delimited by newline characters (\`n). Then it uses the pipeline operator to send the delimited string to the **ConvertFrom-Json** cmdlet, which converts it to a custom object. The Join operator is required, because the **ConvertFrom-Json** cmdlet expects a single string. + ## PARAMETERS ### -InputObject + Specifies the JSON strings to convert to JSON objects. Enter a variable that contains the string, or type a command or expression that gets the string. You can also pipe a string to **ConvertFrom-Json**. @@ -109,17 +122,22 @@ Accept wildcard characters: False ``` ### CommonParameters + This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). + ## INPUTS ### System.String + You can pipe a JSON string to **ConvertFrom-Json**. + ## OUTPUTS ### PSCustomObject ## NOTES -* The **ConvertFrom-Json** cmdlet is implemented by using the [JavaScriptSerializer class](https://msdn.microsoft.com/library/system.web.script.serialization.javascriptserializer). + +- The **ConvertFrom-Json** cmdlet is implemented by using the [JavaScriptSerializer class](https://msdn.microsoft.com/library/system.web.script.serialization.javascriptserializer). ## RELATED LINKS diff --git a/reference/3.0/Microsoft.PowerShell.Utility/Set-Variable.md b/reference/3.0/Microsoft.PowerShell.Utility/Set-Variable.md index cc4019567083..4372b2ea39f1 100644 --- a/reference/3.0/Microsoft.PowerShell.Utility/Set-Variable.md +++ b/reference/3.0/Microsoft.PowerShell.Utility/Set-Variable.md @@ -213,7 +213,7 @@ Accept wildcard characters: False Determines the scope of the variable. Valid values are "Global", "Local", or "Script", or a number relative to the current scope (0 through the number of scopes, where 0 is the current scope and 1 is its parent). "Local" is the default. -For more information, see about_Scopes. +For more information, see [about_Scopes](../Microsoft.PowerShell.Core/About/about_scopes.md). ```yaml Type: String @@ -319,4 +319,4 @@ Otherwise, this cmdlet does not generate any output. [New-Variable](New-Variable.md) -[Remove-Variable](Remove-Variable.md) \ No newline at end of file +[Remove-Variable](Remove-Variable.md) diff --git a/reference/4.0/Microsoft.PowerShell.Core/About/about_Comment_Based_Help.md b/reference/4.0/Microsoft.PowerShell.Core/About/about_Comment_Based_Help.md index 7bc4e70086d5..dcdce243b7d4 100644 --- a/reference/4.0/Microsoft.PowerShell.Core/About/about_Comment_Based_Help.md +++ b/reference/4.0/Microsoft.PowerShell.Core/About/about_Comment_Based_Help.md @@ -124,8 +124,8 @@ or ```powershell <# -.< help keyword> -< help content> +. + #> function Get-Function { } ``` @@ -138,7 +138,7 @@ locations in the script. - At the beginning of the script file. Script help can be preceded in the script only by comments and blank lines. -- If the first item in the script body (after the help) is a function + If the first item in the script body (after the help) is a function declaration, there must be at least two blank lines between the end of the script help and the function declaration. Otherwise, the help is interpreted as being help for the function, not help for the script. @@ -155,6 +155,7 @@ For example: #> + function Get-Function { } ``` @@ -164,8 +165,8 @@ or function Get-Function { } <# -.< help keyword> -< help content> +. + #> ``` @@ -180,11 +181,10 @@ XML-based help files for the functions in a script module, you must add an "ExternalHelp" comment to each function. ```powershell -.ExternalHelp +# .ExternalHelp function { -# ... - + ... } ``` diff --git a/reference/4.0/Microsoft.PowerShell.Core/Receive-Job.md b/reference/4.0/Microsoft.PowerShell.Core/Receive-Job.md index 959fa0050bac..620c28aa7cf3 100644 --- a/reference/4.0/Microsoft.PowerShell.Core/Receive-Job.md +++ b/reference/4.0/Microsoft.PowerShell.Core/Receive-Job.md @@ -159,6 +159,8 @@ If the job has more results, the job is still deleted, but **Receive-Job** displ This parameter works only on custom job types. It is designed for instances of job types that save the job or the type outside of the session, such as instances of scheduled jobs. +This parameter cannot be used without the **Wait** parameter. + This parameter is introduced in Windows PowerShell 3.0. ```yaml diff --git a/reference/4.0/Microsoft.PowerShell.Utility/ConvertFrom-Json.md b/reference/4.0/Microsoft.PowerShell.Utility/ConvertFrom-Json.md index ec7acd7a8b9e..c8b894a8ceb0 100644 --- a/reference/4.0/Microsoft.PowerShell.Utility/ConvertFrom-Json.md +++ b/reference/4.0/Microsoft.PowerShell.Utility/ConvertFrom-Json.md @@ -7,10 +7,10 @@ online version: http://go.microsoft.com/fwlink/p/?linkid=293947 external help file: Microsoft.PowerShell.Commands.Utility.dll-Help.xml title: ConvertFrom-Json --- - # ConvertFrom-Json ## SYNOPSIS + Converts a JSON-formatted string to a custom object. ## SYNTAX @@ -20,16 +20,18 @@ ConvertFrom-Json [-InputObject] [] ``` ## DESCRIPTION + The **ConvertFrom-Json** cmdlet converts a JSON-formatted string to a custom object (PSCustomObject) that has a property for each field in the JSON string. JSON is commonly used by web sites to provide a textual representation of objects. To generate a JSON string from any object, use the **ConvertTo-Json** cmdlet. -This cmdlet is introduced in Windows PowerShell 3.0. +This cmdlet is introduced in PowerShell 3.0. ## EXAMPLES ### Example 1 + ``` PS C:\> Get-Date | Select-Object -Property * | ConvertTo-Json | ConvertFrom-Json @@ -69,21 +71,25 @@ This command uses the ConvertTo-Json and **ConvertFrom-Json** cmdlets to convert The command uses the Select-Object cmdlet to get all of the properties of the **DateTime** object. It uses the **ConvertTo-Json** cmdlet to convert the **DateTime** object to a JSON-formatted string and the **ConvertFrom-Json** cmdlet to convert the JSON-formatted string to a JSON object.. -### Example 2 -``` -PS C:\> $j = Invoke-WebRequest -Uri http://search.twitter.com/search.json?q=PowerShell | ConvertFrom-Json +### Example 2: Get JSON strings from a web service and convert them to PowerShell objects + +```powershell +# Ensures that Invoke-WebRequest uses TLS 1.2 +[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12 +$j = Invoke-WebRequest 'https://api.github.com/repos/PowerShell/PowerShell/issues' | ConvertFrom-Json ``` -This command uses the Invoke-WebRequest cmdlet to get JSON strings from a web service and then it uses the **ConvertFrom-Json** cmdlet to convert JSON content to objects that can be managed in Windows PowerShell. +This command uses the Invoke-WebRequest cmdlet to get JSON strings from a web service and then it uses the **ConvertFrom-Json** cmdlet to convert JSON content to objects that can be managed in PowerShell. You can also use the Invoke-RestMethod cmdlet, which automatically converts JSON content to objects. ### Example 3 -``` -PS C:\> (Get-Content JsonFile.JSON) -join "`n" | ConvertFrom-Json + +```powershell +(Get-Content JsonFile.JSON) -join '`n' | ConvertFrom-Json ``` -This example shows how to use the **ConvertFrom-Json** cmdlet to convert a JSON file to a Windows PowerShell custom object. +This example shows how to use the **ConvertFrom-Json** cmdlet to convert a JSON file to a PowerShell custom object. The command uses Get-Content cmdlet to get the strings in a JSON file. It uses the Join operator to join the strings in the file into a single string that is delimited by newline characters (\`n). @@ -94,6 +100,7 @@ The Join operator is required, because the **ConvertFrom-Json** cmdlet expects a ## PARAMETERS ### -InputObject + Specifies the JSON strings to convert to JSON objects. Enter a variable that contains the string, or type a command or expression that gets the string. You can also pipe a string to **ConvertFrom-Json**. @@ -115,11 +122,13 @@ Accept wildcard characters: False ``` ### CommonParameters + This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). ## INPUTS ### System.String + You can pipe a JSON string to **ConvertFrom-Json**. ## OUTPUTS @@ -127,7 +136,8 @@ You can pipe a JSON string to **ConvertFrom-Json**. ### PSCustomObject ## NOTES -* The **ConvertFrom-Json** cmdlet is implemented by using the [JavaScriptSerializer class](https://msdn.microsoft.com/library/system.web.script.serialization.javascriptserializer). + +- The **ConvertFrom-Json** cmdlet is implemented by using the [JavaScriptSerializer class](https://msdn.microsoft.com/library/system.web.script.serialization.javascriptserializer). ## RELATED LINKS diff --git a/reference/4.0/Microsoft.PowerShell.Utility/Set-Variable.md b/reference/4.0/Microsoft.PowerShell.Utility/Set-Variable.md index c03f5389306e..7483ea76d8fb 100644 --- a/reference/4.0/Microsoft.PowerShell.Utility/Set-Variable.md +++ b/reference/4.0/Microsoft.PowerShell.Utility/Set-Variable.md @@ -219,7 +219,7 @@ Accept wildcard characters: False Determines the scope of the variable. Valid values are "Global", "Local", or "Script", or a number relative to the current scope (0 through the number of scopes, where 0 is the current scope and 1 is its parent). "Local" is the default. -For more information, see about_Scopes. +For more information, see [about_Scopes](../Microsoft.PowerShell.Core/About/about_scopes.md). ```yaml Type: String @@ -328,4 +328,4 @@ Otherwise, this cmdlet does not generate any output. [New-Variable](New-Variable.md) -[Remove-Variable](Remove-Variable.md) \ No newline at end of file +[Remove-Variable](Remove-Variable.md) diff --git a/reference/5.0/Microsoft.PowerShell.Core/About/about_Comment_Based_Help.md b/reference/5.0/Microsoft.PowerShell.Core/About/about_Comment_Based_Help.md index 7bc4e70086d5..dcdce243b7d4 100644 --- a/reference/5.0/Microsoft.PowerShell.Core/About/about_Comment_Based_Help.md +++ b/reference/5.0/Microsoft.PowerShell.Core/About/about_Comment_Based_Help.md @@ -124,8 +124,8 @@ or ```powershell <# -.< help keyword> -< help content> +. + #> function Get-Function { } ``` @@ -138,7 +138,7 @@ locations in the script. - At the beginning of the script file. Script help can be preceded in the script only by comments and blank lines. -- If the first item in the script body (after the help) is a function + If the first item in the script body (after the help) is a function declaration, there must be at least two blank lines between the end of the script help and the function declaration. Otherwise, the help is interpreted as being help for the function, not help for the script. @@ -155,6 +155,7 @@ For example: #> + function Get-Function { } ``` @@ -164,8 +165,8 @@ or function Get-Function { } <# -.< help keyword> -< help content> +. + #> ``` @@ -180,11 +181,10 @@ XML-based help files for the functions in a script module, you must add an "ExternalHelp" comment to each function. ```powershell -.ExternalHelp +# .ExternalHelp function { -# ... - + ... } ``` diff --git a/reference/5.0/Microsoft.PowerShell.Core/Receive-Job.md b/reference/5.0/Microsoft.PowerShell.Core/Receive-Job.md index 9d1bc7aa633e..9f68df711697 100644 --- a/reference/5.0/Microsoft.PowerShell.Core/Receive-Job.md +++ b/reference/5.0/Microsoft.PowerShell.Core/Receive-Job.md @@ -158,6 +158,8 @@ If the job has more results, the job is still deleted, but **Receive-Job** displ This parameter works only on custom job types. It is designed for instances of job types that save the job or the type outside of the session, such as instances of scheduled jobs. +This parameter cannot be used without the **Wait** parameter. + This parameter was introduced in Windows PowerShell 3.0. ```yaml diff --git a/reference/5.0/Microsoft.PowerShell.Utility/ConvertFrom-Json.md b/reference/5.0/Microsoft.PowerShell.Utility/ConvertFrom-Json.md index 7030180db7e0..22a5bf906f97 100644 --- a/reference/5.0/Microsoft.PowerShell.Utility/ConvertFrom-Json.md +++ b/reference/5.0/Microsoft.PowerShell.Utility/ConvertFrom-Json.md @@ -7,10 +7,10 @@ online version: http://go.microsoft.com/fwlink/?LinkId=821753 external help file: Microsoft.PowerShell.Commands.Utility.dll-Help.xml title: ConvertFrom-Json --- - # ConvertFrom-Json ## SYNOPSIS + Converts a JSON-formatted string to a custom object. ## SYNTAX @@ -20,16 +20,18 @@ ConvertFrom-Json [-InputObject] [] ``` ## DESCRIPTION + The **ConvertFrom-Json** cmdlet converts a JavaScript Object Notation (JSON) formatted string to a custom **PSCustomObject** object that has a property for each field in the JSON string. JSON is commonly used by web sites to provide a textual representation of objects. To generate a JSON string from any object, use the ConvertTo-Json cmdlet. -This cmdlet was introduced in Windows PowerShell 3.0. +This cmdlet was introduced in PowerShell 3.0. ## EXAMPLES ### Example 1: Convert a DateTime object to a JSON object + ``` PS C:\> Get-Date | Select-Object -Property * | ConvertTo-Json | ConvertFrom-Json @@ -69,21 +71,25 @@ This command uses the ConvertTo-Json and **ConvertFrom-Json** cmdlets to convert The command uses the Select-Object cmdlet to get all of the properties of the **DateTime** object. It uses the **ConvertTo-Json** cmdlet to convert the **DateTime** object to a JSON-formatted string and the **ConvertFrom-Json** cmdlet to convert the JSON-formatted string to a JSON object.. -### Example 2: Get JSON strings from a web service and convert them to Windows PowerShell objects -``` -PS C:\> $J = Invoke-WebRequest -Uri http://search.twitter.com/search.json?q=PowerShell | ConvertFrom-Json +### Example 2: Get JSON strings from a web service and convert them to PowerShell objects + +```powershell +# Ensures that Invoke-WebRequest uses TLS 1.2 +[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12 +$j = Invoke-WebRequest 'https://api.github.com/repos/PowerShell/PowerShell/issues' | ConvertFrom-Json ``` -This command uses the Invoke-WebRequest cmdlet to get JSON strings from a web service and then it uses the **ConvertFrom-Json** cmdlet to convert JSON content to objects that can be managed in Windows PowerShell. +This command uses the Invoke-WebRequest cmdlet to get JSON strings from a web service and then it uses the **ConvertFrom-Json** cmdlet to convert JSON content to objects that can be managed in PowerShell. You can also use the Invoke-RestMethod cmdlet, which automatically converts JSON content to objects. ### Example 3: Convert a JSON string to a custom object -``` -PS C:\> (Get-Content JsonFile.JSON) -Join "`n" | ConvertFrom-Json + +```powershell +(Get-Content JsonFile.JSON) -Join '`n' | ConvertFrom-Json ``` -This example shows how to use the **ConvertFrom-Json** cmdlet to convert a JSON file to a Windows PowerShell custom object. +This example shows how to use the **ConvertFrom-Json** cmdlet to convert a JSON file to a PowerShell custom object. The command uses Get-Content cmdlet to get the strings in a JSON file. It uses the Join operator to join the strings in the file into a single string that is delimited by newline characters (\`n). @@ -94,6 +100,7 @@ The Join operator is required, because the **ConvertFrom-Json** cmdlet expects a ## PARAMETERS ### -InputObject + Specifies the JSON strings to convert to JSON objects. Enter a variable that contains the string, or type a command or expression that gets the string. You can also pipe a string to **ConvertFrom-Json**. @@ -115,11 +122,13 @@ Accept wildcard characters: False ``` ### CommonParameters + This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). ## INPUTS ### System.String + You can pipe a JSON string to **ConvertFrom-Json**. ## OUTPUTS @@ -127,7 +136,8 @@ You can pipe a JSON string to **ConvertFrom-Json**. ### PSCustomObject ## NOTES -* The **ConvertFrom-Json** cmdlet is implemented by using the [JavaScriptSerializer class](https://msdn.microsoft.com/library/system.web.script.serialization.javascriptserializer). + +- The **ConvertFrom-Json** cmdlet is implemented by using the [JavaScriptSerializer class](https://msdn.microsoft.com/library/system.web.script.serialization.javascriptserializer). ## RELATED LINKS diff --git a/reference/5.0/Microsoft.PowerShell.Utility/Set-Variable.md b/reference/5.0/Microsoft.PowerShell.Utility/Set-Variable.md index b7ef13d0f9eb..ba1759a665bd 100644 --- a/reference/5.0/Microsoft.PowerShell.Utility/Set-Variable.md +++ b/reference/5.0/Microsoft.PowerShell.Utility/Set-Variable.md @@ -243,7 +243,7 @@ The acceptable values for this parameter are: Local is the default. -For more information, see about_Scopes. +For more information, see [about_Scopes](../Microsoft.PowerShell.Core/About/about_scopes.md). ```yaml Type: String @@ -340,4 +340,4 @@ Otherwise, this cmdlet does not generate any output. [New-Variable](New-Variable.md) -[Remove-Variable](Remove-Variable.md) \ No newline at end of file +[Remove-Variable](Remove-Variable.md) diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Comment_Based_Help.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Comment_Based_Help.md index 7bc4e70086d5..dcdce243b7d4 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Comment_Based_Help.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Comment_Based_Help.md @@ -124,8 +124,8 @@ or ```powershell <# -.< help keyword> -< help content> +. + #> function Get-Function { } ``` @@ -138,7 +138,7 @@ locations in the script. - At the beginning of the script file. Script help can be preceded in the script only by comments and blank lines. -- If the first item in the script body (after the help) is a function + If the first item in the script body (after the help) is a function declaration, there must be at least two blank lines between the end of the script help and the function declaration. Otherwise, the help is interpreted as being help for the function, not help for the script. @@ -155,6 +155,7 @@ For example: #> + function Get-Function { } ``` @@ -164,8 +165,8 @@ or function Get-Function { } <# -.< help keyword> -< help content> +. + #> ``` @@ -180,11 +181,10 @@ XML-based help files for the functions in a script module, you must add an "ExternalHelp" comment to each function. ```powershell -.ExternalHelp +# .ExternalHelp function { -# ... - + ... } ``` diff --git a/reference/5.1/Microsoft.PowerShell.Core/Receive-Job.md b/reference/5.1/Microsoft.PowerShell.Core/Receive-Job.md index a14b02c81c2c..52a620716036 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/Receive-Job.md +++ b/reference/5.1/Microsoft.PowerShell.Core/Receive-Job.md @@ -158,6 +158,8 @@ If the job has more results, the job is still deleted, but **Receive-Job** displ This parameter works only on custom job types. It is designed for instances of job types that save the job or the type outside of the session, such as instances of scheduled jobs. +This parameter cannot be used without the **Wait** parameter. + This parameter was introduced in Windows PowerShell 3.0. ```yaml diff --git a/reference/5.1/Microsoft.PowerShell.Security/Protect-CmsMessage.md b/reference/5.1/Microsoft.PowerShell.Security/Protect-CmsMessage.md index 0be1649acfb1..6cd23d019010 100644 --- a/reference/5.1/Microsoft.PowerShell.Security/Protect-CmsMessage.md +++ b/reference/5.1/Microsoft.PowerShell.Security/Protect-CmsMessage.md @@ -92,11 +92,11 @@ The *To* parameter uses the value of the Subject line in the certificate. ### Example 3: View document encryption certificates ``` -PS C:\> 58 [Cert:\currentuser\my] ->> Get-ChildItem -DocumentEncryptionCert +PS C:\> cd Cert:\currentuser\my +Get-ChildItem -DocumentEncryptionCert ``` -To view document encryption certificates in the certificate provider, you can add the *DocumentEncryptionCert* dynamic parameter of Get-ChildItemhttp://technet.microsoft.com/library/hh847761.aspx, available only when the certificate provider is loaded. +To view document encryption certificates in the certificate provider, you can add the *DocumentEncryptionCert* dynamic parameter of [Get-ChildItem](Providers/get-childitem-for-certificate.md), available only when the certificate provider is loaded. ## PARAMETERS @@ -202,4 +202,4 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable [Get-CmsMessage](Get-CmsMessage.md) -[Unprotect-CmsMessage](Unprotect-CmsMessage.md) \ No newline at end of file +[Unprotect-CmsMessage](Unprotect-CmsMessage.md) diff --git a/reference/5.1/Microsoft.PowerShell.Utility/ConvertFrom-Json.md b/reference/5.1/Microsoft.PowerShell.Utility/ConvertFrom-Json.md index fc28ab77f7a4..842611dda337 100644 --- a/reference/5.1/Microsoft.PowerShell.Utility/ConvertFrom-Json.md +++ b/reference/5.1/Microsoft.PowerShell.Utility/ConvertFrom-Json.md @@ -7,10 +7,10 @@ online version: http://go.microsoft.com/fwlink/?LinkId=821753 external help file: Microsoft.PowerShell.Commands.Utility.dll-Help.xml title: ConvertFrom-Json --- - # ConvertFrom-Json ## SYNOPSIS + Converts a JSON-formatted string to a custom object. ## SYNTAX @@ -20,16 +20,18 @@ ConvertFrom-Json [-InputObject] [] ``` ## DESCRIPTION + The **ConvertFrom-Json** cmdlet converts a JavaScript Object Notation (JSON) formatted string to a custom **PSCustomObject** object that has a property for each field in the JSON string. JSON is commonly used by web sites to provide a textual representation of objects. To generate a JSON string from any object, use the ConvertTo-Json cmdlet. -This cmdlet was introduced in Windows PowerShell 3.0. +This cmdlet was introduced in PowerShell 3.0. ## EXAMPLES ### Example 1: Convert a DateTime object to a JSON object + ``` PS C:\> Get-Date | Select-Object -Property * | ConvertTo-Json | ConvertFrom-Json DisplayHint : 2 @@ -54,21 +56,25 @@ This command uses the ConvertTo-Json and **ConvertFrom-Json** cmdlets to convert The command uses the Select-Object cmdlet to get all of the properties of the **DateTime** object. It uses the **ConvertTo-Json** cmdlet to convert the **DateTime** object to a JSON-formatted string and the **ConvertFrom-Json** cmdlet to convert the JSON-formatted string to a JSON object. -### Example 2: Get JSON strings from a web service and convert them to Windows PowerShell objects -``` -PS C:\> $j = Invoke-WebRequest -Uri http://search.twitter.com/search.json?q=PowerShell | ConvertFrom-Json +### Example 2: Get JSON strings from a web service and convert them to PowerShell objects + +```powershell +# Ensures that Invoke-WebRequest uses TLS 1.2 +[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12 +$j = Invoke-WebRequest 'https://api.github.com/repos/PowerShell/PowerShell/issues' | ConvertFrom-Json ``` -This command uses the Invoke-WebRequest cmdlet to get JSON strings from a web service and then it uses the **ConvertFrom-Json** cmdlet to convert JSON content to objects that can be managed in Windows PowerShell. +This command uses the Invoke-WebRequest cmdlet to get JSON strings from a web service and then it uses the **ConvertFrom-Json** cmdlet to convert JSON content to objects that can be managed in PowerShell. You can also use the Invoke-RestMethod cmdlet, which automatically converts JSON content to objects. ### Example 3: Convert a JSON string to a custom object -``` -PS C:\> (Get-Content JsonFile.JSON) -join "`n" | ConvertFrom-Json + +```powershell +(Get-Content JsonFile.JSON) -join '`n' | ConvertFrom-Json ``` -This example shows how to use the **ConvertFrom-Json** cmdlet to convert a JSON file to a Windows PowerShell custom object. +This example shows how to use the **ConvertFrom-Json** cmdlet to convert a JSON file to a PowerShell custom object. The command uses Get-Content cmdlet to get the strings in a JSON file. It uses the Join operator to join the strings in the file into a single string that is delimited by newline characters (\`n). @@ -79,6 +85,7 @@ The Join operator is required, because the **ConvertFrom-Json** cmdlet expects a ## PARAMETERS ### -InputObject + Specifies the JSON strings to convert to JSON objects. Enter a variable that contains the string, or type a command or expression that gets the string. You can also pipe a string to **ConvertFrom-Json**. @@ -100,11 +107,13 @@ Accept wildcard characters: False ``` ### CommonParameters + This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). ## INPUTS ### System.String + You can pipe a JSON string to **ConvertFrom-Json**. ## OUTPUTS @@ -112,7 +121,8 @@ You can pipe a JSON string to **ConvertFrom-Json**. ### PSCustomObject ## NOTES -* The **ConvertFrom-Json** cmdlet is implemented by using the [JavaScriptSerializer class](https://msdn.microsoft.com/library/system.web.script.serialization.javascriptserializer). + +- The **ConvertFrom-Json** cmdlet is implemented by using the [JavaScriptSerializer class](https://msdn.microsoft.com/library/system.web.script.serialization.javascriptserializer). ## RELATED LINKS diff --git a/reference/5.1/Microsoft.PowerShell.Utility/Set-Variable.md b/reference/5.1/Microsoft.PowerShell.Utility/Set-Variable.md index 84742695befb..c114bff5590e 100644 --- a/reference/5.1/Microsoft.PowerShell.Utility/Set-Variable.md +++ b/reference/5.1/Microsoft.PowerShell.Utility/Set-Variable.md @@ -241,7 +241,7 @@ Specifies the scope of the variable.The acceptable values for this parameter are Local is the default. -For more information, see about_Scopes. +For more information, see [about_Scopes](../Microsoft.PowerShell.Core/About/about_scopes.md). ```yaml Type: String @@ -338,4 +338,4 @@ Otherwise, this cmdlet does not generate any output. [New-Variable](New-Variable.md) -[Remove-Variable](Remove-Variable.md) \ No newline at end of file +[Remove-Variable](Remove-Variable.md) diff --git a/reference/5.1/PowershellGet/Install-Script.md b/reference/5.1/PowershellGet/Install-Script.md index 734fc1f5ef91..c2cb6a734f5b 100644 --- a/reference/5.1/PowershellGet/Install-Script.md +++ b/reference/5.1/PowershellGet/Install-Script.md @@ -43,14 +43,17 @@ When operating against multiple repositories, **Install-Script** installs the fi PS C:\> Find-Script -Repository "Local1" -Name "Required-Script2" Version Name Type Repository Description ------- ---- ---- ---------- ----------- -2.5 Required-Script2 Script local1 Description for the Required-Script2 script PS C:\> Find-Script -Repository "Local1" -Name "Required-Script2" | Install-Script +2.5 Required-Script2 Script local1 Description for the Required-Script2 script +PS C:\> Find-Script -Repository "Local1" -Name "Required-Script2" | Install-Script PS C:\> Get-Command -Name "Required-Script2" CommandType Name Version Source ----------- ---- ------- ------ -ExternalScript Required-Script2.ps1 2.0 C:\Users\pattif\Documents\WindowsPowerShell\Scripts\Required-Script2.ps1 PS C:\> Get-InstalledScript -Name "Required-Script2" +ExternalScript Required-Script2.ps1 2.0 C:\Users\pattif\Documents\WindowsPowerShell\Scripts\Required-Script2.ps1 +PS C:\> Get-InstalledScript -Name "Required-Script2" Version Name Type Repository Description ------- ---- ---- ---------- ----------- -2.5 Required-Script2 Script local1 Description for the Required-Script2 script PS C:\> Get-InstalledScript -Name "Required-Script2" | Format-List * +2.5 Required-Script2 Script local1 Description for the Required-Script2 script +PS C:\> Get-InstalledScript -Name "Required-Script2" | Format-List * Name : Required-Script2 Version : 2.5 Type : Script @@ -89,7 +92,8 @@ PS C:\> Install-Script -Repository "Local1" -Name "Required-Script3" -Scope "All PS C:\> Get-InstalledScript -Name "Required-Script3" Version Name Type Repository Description ------- ---- ---- ---------- ----------- -2.5 Required-Script3 Script local1 Description for the Required-Script3 script PS C:\> Get-InstalledScript -Name "Required-Script3" | Format-List * +2.5 Required-Script3 Script local1 Description for the Required-Script3 script +PS C:\> Get-InstalledScript -Name "Required-Script3" | Format-List * Name : Required-Script3 Version : 2.5 Type : Script @@ -129,24 +133,28 @@ Version Name Type Repository D 2.5 RequiredModule3 Module local1 RequiredModule3 module 2.5 Required-Script1 Script local1 Description for the Required-Script1 script 2.5 Required-Script2 Script local1 Description for the Required-Script2 script -2.5 Required-Script3 Script local1 Description for the Required-Script3 script PS C:\> Install-Script -Repository "Local1" -Name "Script-WithDependencies2" +2.5 Required-Script3 Script local1 Description for the Required-Script3 script +PS C:\> Install-Script -Repository "Local1" -Name "Script-WithDependencies2" PS C:\> Get-InstalledScript Version Name Type Repository Description ------- ---- ---- ---------- ----------- 2.5 Required-Script1 Script local1 Description for the Required-Script1 script 2.5 Required-Script2 Script local1 Description for the Required-Script2 script 2.5 Required-Script3 Script local1 Description for the Required-Script3 script -2.0 Script-WithDependencies2 Script local1 Description for the Script-WithDependencies2 script PS C:\> Get-InstalledModule +2.0 Script-WithDependencies2 Script local1 Description for the Script-WithDependencies2 script +PS C:\> Get-InstalledModule Version Name Type Repository Description ------- ---- ---- ---------- ----------- 2.5 RequiredModule1 Module local1 RequiredModule1 module 2.5 RequiredModule2 Module local1 RequiredModule2 module -2.5 RequiredModule3 Module local1 RequiredModule3 module PS C:\> Find-Script -Repository "Local1" -Name "Required-Script*" +2.5 RequiredModule3 Module local1 RequiredModule3 module +PS C:\> Find-Script -Repository "Local1" -Name "Required-Script*" Version Name Type Repository Description ------- ---- ---- ---------- ----------- 2.5 Required-Script1 Script local1 Description for the Required-Script1 script 2.5 Required-Script2 Script local1 Description for the Required-Script2 script -2.5 Required-Script3 Script local1 Description for the Required-Script3 script PS C:\> Install-Script -Repository "Local1" -Name "Required-Script*" +2.5 Required-Script3 Script local1 Description for the Required-Script3 script +PS C:\> Install-Script -Repository "Local1" -Name "Required-Script*" PS C:\> Get-InstalledScript Version Name Type Repository Description ------- ---- ---- ---------- ----------- @@ -411,4 +419,4 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable [Uninstall-Script](Uninstall-Script.md) -[Update-Script](Update-Script.md) \ No newline at end of file +[Update-Script](Update-Script.md) diff --git a/reference/6/Microsoft.PowerShell.Core/About/about_Comment_Based_Help.md b/reference/6/Microsoft.PowerShell.Core/About/about_Comment_Based_Help.md index 7bc4e70086d5..dcdce243b7d4 100644 --- a/reference/6/Microsoft.PowerShell.Core/About/about_Comment_Based_Help.md +++ b/reference/6/Microsoft.PowerShell.Core/About/about_Comment_Based_Help.md @@ -124,8 +124,8 @@ or ```powershell <# -.< help keyword> -< help content> +. + #> function Get-Function { } ``` @@ -138,7 +138,7 @@ locations in the script. - At the beginning of the script file. Script help can be preceded in the script only by comments and blank lines. -- If the first item in the script body (after the help) is a function + If the first item in the script body (after the help) is a function declaration, there must be at least two blank lines between the end of the script help and the function declaration. Otherwise, the help is interpreted as being help for the function, not help for the script. @@ -155,6 +155,7 @@ For example: #> + function Get-Function { } ``` @@ -164,8 +165,8 @@ or function Get-Function { } <# -.< help keyword> -< help content> +. + #> ``` @@ -180,11 +181,10 @@ XML-based help files for the functions in a script module, you must add an "ExternalHelp" comment to each function. ```powershell -.ExternalHelp +# .ExternalHelp function { -# ... - + ... } ``` diff --git a/reference/6/Microsoft.PowerShell.Core/Receive-Job.md b/reference/6/Microsoft.PowerShell.Core/Receive-Job.md index e4ebcf7fc93c..1f5b6cf2256d 100644 --- a/reference/6/Microsoft.PowerShell.Core/Receive-Job.md +++ b/reference/6/Microsoft.PowerShell.Core/Receive-Job.md @@ -158,6 +158,8 @@ If the job has more results, the job is still deleted, but **Receive-Job** displ This parameter works only on custom job types. It is designed for instances of job types that save the job or the type outside of the session, such as instances of scheduled jobs. +This parameter cannot be used without the **Wait** parameter. + This parameter was introduced in Windows PowerShell 3.0. ```yaml diff --git a/reference/6/Microsoft.PowerShell.Utility/ConvertFrom-Json.md b/reference/6/Microsoft.PowerShell.Utility/ConvertFrom-Json.md index 9652e4e63076..b767e4472daf 100644 --- a/reference/6/Microsoft.PowerShell.Utility/ConvertFrom-Json.md +++ b/reference/6/Microsoft.PowerShell.Utility/ConvertFrom-Json.md @@ -7,7 +7,6 @@ online version: http://go.microsoft.com/fwlink/?LinkId=821753 external help file: Microsoft.PowerShell.Commands.Utility.dll-Help.xml title: ConvertFrom-Json --- - # ConvertFrom-Json ## SYNOPSIS @@ -32,7 +31,7 @@ See other examples below. To generate a JSON string from any object, use the ConvertTo-Json cmdlet. -This cmdlet was introduced in Windows PowerShell 3.0. +This cmdlet was introduced in PowerShell 3.0. ## EXAMPLES @@ -64,22 +63,24 @@ The command uses the Select-Object cmdlet to get all of the properties of the ** It uses the `ConvertTo-Json` cmdlet to convert the **DateTime** object to a JSON-formatted string and the `ConvertFrom-Json` cmdlet to convert the JSON-formatted string to a JSON object. -### Example 2: Get JSON strings from a web service and convert them to Windows PowerShell objects +### Example 2: Get JSON strings from a web service and convert them to PowerShell objects ```powershell -PS C:\> $j = Invoke-WebRequest -Uri http://search.twitter.com/search.json?q=PowerShell | ConvertFrom-Json +# Ensures that Invoke-WebRequest uses TLS 1.2 +[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12 +$j = Invoke-WebRequest 'https://api.github.com/repos/PowerShell/PowerShell/issues' | ConvertFrom-Json ``` This command uses the `Invoke-WebRequest` cmdlet to get JSON strings from a web service and then it uses the `ConvertFrom-Json` cmdlet to convert JSON content to objects -that can be managed in Windows PowerShell. +that can be managed in PowerShell. You can also use the Invoke-RestMethod cmdlet, which automatically converts JSON content to objects. ### Example 3: Convert a JSON string to a custom object ```powershell -PS C:\> (Get-Content JsonFile.JSON) -join "`n" | ConvertFrom-Json +(Get-Content JsonFile.JSON) -join '`n' | ConvertFrom-Json ``` This example shows how to use the `ConvertFrom-Json` cmdlet to convert a JSON file to a PowerShell custom object. @@ -95,7 +96,7 @@ The Join operator is required, because the `ConvertFrom-Json` cmdlet expects a s ### Example 4: Convert a JSON string to a hash table ```powershell -PS C:\> '{ "key":"value1", "Key":"value2" }' | ConvertFrom-Json -AsHashtable +'{ "key":"value1", "Key":"value2" }' | ConvertFrom-Json -AsHashtable ``` This command shows an example where the `-AsHashtable` switch can overcome limitations of the command. @@ -127,6 +128,7 @@ Accept wildcard characters: False ``` ### -AsHashtable + Converts the JSON to a hash table object. This switch was introduced in PowerShell 6.0. There are several scenarios where it can overcome some limitations of the `ConvertFrom-Json` cmdlet. @@ -148,6 +150,7 @@ Accept wildcard characters: False ``` ### CommonParameters + This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). @@ -155,6 +158,7 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## INPUTS ### System.String + You can pipe a JSON string to `ConvertFrom-Json`. ## OUTPUTS diff --git a/reference/6/Microsoft.PowerShell.Utility/Invoke-WebRequest.md b/reference/6/Microsoft.PowerShell.Utility/Invoke-WebRequest.md index f359b14c5176..8f82b9c0f386 100644 --- a/reference/6/Microsoft.PowerShell.Utility/Invoke-WebRequest.md +++ b/reference/6/Microsoft.PowerShell.Utility/Invoke-WebRequest.md @@ -727,7 +727,7 @@ Accept wildcard characters: False ``` ### -UseBasicParsing -This parameter has been deprecated. Beginning with PowerShell 6.0.0, all Web requests use basic parsing only. This parameter is included for backwards compatibility only and any use of it will have no affect on the operation of the cmdlet. +This parameter has been deprecated. Beginning with PowerShell 6.0.0, all Web requests use basic parsing only. This parameter is included for backwards compatibility only and any use of it will have no effect on the operation of the cmdlet. ```yaml Type: SwitchParameter @@ -835,4 +835,4 @@ Beginning with PowerShell 6.0.0 `Invoke-WebRequest` supports basic parsing only. [ConvertFrom-Json](ConvertFrom-Json.md) -[ConvertTo-Json](ConvertTo-Json.md) \ No newline at end of file +[ConvertTo-Json](ConvertTo-Json.md) diff --git a/reference/6/Microsoft.PowerShell.Utility/Set-Variable.md b/reference/6/Microsoft.PowerShell.Utility/Set-Variable.md index bc14d0f69f91..46a8b84b66c1 100644 --- a/reference/6/Microsoft.PowerShell.Utility/Set-Variable.md +++ b/reference/6/Microsoft.PowerShell.Utility/Set-Variable.md @@ -226,7 +226,7 @@ Specifies the scope of the variable.The acceptable values for this parameter are Local is the default. -For more information, see about_Scopes. +For more information, see [about_Scopes](../Microsoft.PowerShell.Core/About/about_scopes.md). ```yaml Type: String @@ -338,4 +338,4 @@ Otherwise, this cmdlet does not generate any output. [New-Variable](New-Variable.md) -[Remove-Variable](Remove-Variable.md) \ No newline at end of file +[Remove-Variable](Remove-Variable.md) diff --git a/reference/6/PackageManagement/Register-PackageSource.md b/reference/6/PackageManagement/Register-PackageSource.md index 87ee3f95e8d9..f9d5ae15bdd7 100644 --- a/reference/6/PackageManagement/Register-PackageSource.md +++ b/reference/6/PackageManagement/Register-PackageSource.md @@ -55,7 +55,7 @@ If you do not add the *Trusted* parameter, by default, the package is not truste ## PARAMETERS ### -Credential -Specifies a user account that has permission to install package providers. +Specifies a user account that has permission to access the authenticated location. ```yaml Type: PSCredential @@ -328,4 +328,4 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable [Set-PackageSource](Set-PackageSource.md) -[Unregister-PackageSource](Unregister-PackageSource.md) \ No newline at end of file +[Unregister-PackageSource](Unregister-PackageSource.md) diff --git a/reference/docs-conceptual/PowerShell-Core-on-ARM.md b/reference/docs-conceptual/PowerShell-Core-on-ARM.md new file mode 100644 index 000000000000..f7b790a25a56 --- /dev/null +++ b/reference/docs-conceptual/PowerShell-Core-on-ARM.md @@ -0,0 +1,11 @@ +# PowerShell Core on ARM + +Today, PowerShell Core works on some ARM devices, +including both Windows 10 ARM32/ARM64 and Raspbian, in an experimental, unsupported state. + +For more information on installing these unsupported, experimental builds, +check out our installation instructions on GitHub for [Windows 10 IoT](https://github.com/PowerShell/PowerShell/blob/master/docs/installation/windows.md#deploying-on-windows-iot) +and [Raspbian](https://github.com/PowerShell/PowerShell/blob/master/docs/installation/linux.md#raspbian). + +More information will be available here as our ARM64 story progresses. +Stay tuned! \ No newline at end of file diff --git a/reference/docs-conceptual/setup/Installing-PowerShell-Core-on-macOS-and-Linux.md b/reference/docs-conceptual/setup/Installing-PowerShell-Core-on-macOS-and-Linux.md index 228ef0ae05dd..d5ea22eda37a 100644 --- a/reference/docs-conceptual/setup/Installing-PowerShell-Core-on-macOS-and-Linux.md +++ b/reference/docs-conceptual/setup/Installing-PowerShell-Core-on-macOS-and-Linux.md @@ -606,10 +606,10 @@ When new versions of PowerShell are released, simply update Homebrew's formulae ```sh brew update -brew cask reinstall powershell +brew cask upgrade powershell ``` -> Note: because of [this issue in Cask](https://github.com/caskroom/homebrew-cask/issues/29301), you currently have to do a reinstall to upgrade. +> Note: The commands above can be called from within a PowerShell (pwsh) host, but then the PowerShell shell must be exited and re-entered to complete the upgrade and refresh the values shown in $PSVersionTable. [brew]: http://brew.sh/ [cask]: https://caskroom.github.io/ @@ -804,4 +804,4 @@ On Linux and macOS, the [XDG Base Directory Specification][xdg-bds] is respected Note that because macOS is a derivation of BSD, instead of `/opt`, the prefix used is `/usr/local`. Thus, `$PSHOME` is `/usr/local/microsoft/powershell/6.0.0/`, and the symlink is placed at `/usr/local/bin/pwsh`. [releases]: https://github.com/PowerShell/PowerShell/releases/latest -[xdg-bds]: https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html \ No newline at end of file +[xdg-bds]: https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html diff --git a/reference/docs-conceptual/toc.yml b/reference/docs-conceptual/toc.yml index d87713a4e833..1bef785fe89e 100644 --- a/reference/docs-conceptual/toc.yml +++ b/reference/docs-conceptual/toc.yml @@ -11,6 +11,8 @@ href: setup/Installing-PowerShell-Core-on-Windows.md - name: Installing PowerShell Core on macOS and Linux href: setup/Installing-PowerShell-Core-on-macOS-and-Linux.md + - name: PowerShell Core on ARM + href: PowerShell-Core-on-ARM.md - name: Windows PowerShell href: '' items: diff --git a/wmf/5.0/feedback_moduleversionranges.md b/wmf/5.0/feedback_moduleversionranges.md index dd2c9adb9c1b..a83e6ef1cac5 100644 --- a/wmf/5.0/feedback_moduleversionranges.md +++ b/wmf/5.0/feedback_moduleversionranges.md @@ -8,9 +8,9 @@ keywords: wmf,powershell,setup # Modules support for declaring version ranges (1.*, etc) Combined with **-MinimumVersion**, **-MaximumVersion** now allows user to get/import module within specific range. The parameter also support **.**\*. The following example shows how it works: -```powershell Now, you can combine **-MinimumVersion** and **-MaximumVersion** to import module within specific range: +```powershell PS C:\> Import-Module psreadline -Verbose -MinimumVersion 1.0 -MaximumVersion 1.2.* VERBOSE: Loading module from path 'C:\Program Files\WindowsPowerShell\Modules\psreadline\1.1\psreadline.psd1'. @@ -20,4 +20,4 @@ VERBOSE: Importing cmdlet 'Remove-PSReadlineKeyHandler'. VERBOSE: Importing cmdlet 'Set-PSReadlineKeyHandler'. VERBOSE: Importing cmdlet 'Set-PSReadlineOption'. VERBOSE: Importing function 'PSConsoleHostReadline'. -``` \ No newline at end of file +```