Category Archives: Powershell

DSC Resource Kit Release September 2019

This post was originally published on this site

We just released the DSC Resource Kit!

This release includes updates to 15 DSC resource modules. In the past 6 weeks, 160 pull requests have been merged and 68 issues have been closed, all thanks to our amazing community!

The modules updated in this release are:

  • ActiveDirectoryCSDsc 4.1.0.0
  • ActiveDirectoryDsc 4.1.0.0
  • ComputerManagementDsc 7.0.0.0
  • DFSDsc 4.4.0.0
  • NetworkingDsc 7.4.0.0
  • SecurityPolicyDsc 2.10.0.0
  • SqlServerDsc 13.2.0.0
  • xDnsServer 1.15.0.0
  • xExchange 1.29.0.0
  • xFailOverCluster 1.13.0.0
  • xPSDesiredStateConfiguration 8.10.0.0
  • xRemoteDesktopSessionHost 1.9.0.0
  • xSCSMA 2.1.0.0
  • xWebAdministration 2.8.0.0

For a detailed list of the resource modules and fixes in this release, see the Included in this Release section below.

Our latest community call for the DSC Resource Kit was last Wednesday, September 11. A recording of the call is posted on the PowerShell YouTube channel. You can join us for the next call at 12PM (Pacific time) on August 28th to ask questions and give feedback about your experience with the DSC Resource Kit.

The next DSC Resource Kit release will be on Wednesday, October 9.

We strongly encourage you to update to the newest version of all modules using the PowerShell Gallery, and don’t forget to give us your feedback in the comments below, on GitHub, or on Twitter (@PowerShell_Team)!

Please see our documentation here for information on the support of these resource modules.

Included in this Release

You can see a detailed summary of all changes included in this release in the table below. For past release notes, go to the README.md or CHANGELOG.md file on the GitHub repository page for a specific module (see the How to Find DSC Resource Modules on GitHub section below for details on finding the GitHub page for a specific module).

Module Name Version Release Notes
ActiveDirectoryCSDsc 4.1.0.0
  • AdcsCertificationAuthoritySettings:
    • Fix grammar in the resource README.md.
  • Fix minor style issues in statement case.
ActiveDirectoryDsc 4.1.0.0
    • We could not add the change log to the release notes due to the length of the change log. What have change in this release can be found here

https://github.com/PowerShell/ActiveDirectoryDsc/blob/dev/CHANGELOG.md#4100

    .
ComputerManagementDsc 7.0.0.0
  • ScheduledTask:
    • Better compatibility with Group LogonType when passing BuiltIn groups through ExecuteAsCredential
      • Primary use case is “BUILTINUsers”
      • Use the ExecuteAsCredential property to pass the username The PSCredential needs a non-null that is ignored
    • Delay property not handled properly on AtLogon and AtStartup trigger – Fixes Issue 230
    • Changed Get-ScheduledTask calls to ScheduledTasksGet-ScheduledTask to avoid name clash with Carbon module. Fixes Issue 248
    • Cast MultipleInstances value returned by Get-TargetResource to string – fixes Issue 255
  • PendingReboot:
    • Migrated xPendingReboot from xPendingReboot and renamed to PendingReboot.
    • Converted to meet HQRM guidelines – Fixes Issue 12.
    • Changed SkipCcmClientSDK parameter to default to $true – Fixes Issue 13.
    • Fixed Test-TargetResource so that if ConfigMgr requires a reboot then the pending reboot will be set – Fixes Issue 26.
    • Refactored Test-TargetResource to reduce code duplication and move to a data driven design.
    • Refactored Get-TargetResource by adding a new function Get-PendingRebootState so that Test-TargetResource no longer needed to use Get-TargetResource. This eliminated the need to include write parameters in Get-TargetResource.
    • Converted the call to Invoke-WmiMethod to Invoke-CimMethod.
    • Deleted the code that removes the regRebootLocations variable at the end of the resource as it appears to serve no purpose.
  • Correct all tests to meet Pester 4.0 standards.
  • RemoteDesktopAdmin:
    • New resource for configuring Remote Desktop for Administration – fixes Issue 224.
  • Updated common function Test-DscParameterState to support ordered comparison of arrays by copying function and tests from NetworkingDsc – fixes Issue 250.
  • BREAKING CHANGE: ScheduledTask:
    • Correct output type of DaysInterval,StartTime,WeeksDaysOfWeek, and WeeksInterval parameters from Get-TargetResource to match MOF.
    • Refactored Get-TargetResource to remove parameters that are not key or required – fixes Issue 249.
    • Added function Test-DateStringContainsTimeZone to determine if a string containing a date time includes a time zone.
    • Enable verbose preference to be passed through to Test-DscParameterState.
    • Changed Test-TargetResource so that StartTime is only compared for trigger types Daily,Weekly or Once.
  • Fix minor style issues in statement case.
DFSDsc 4.4.0.0
  • Fix example publish to PowerShell Gallery by adding gallery_api environment variable to AppVeyor.yml – fixes Issue 91.
  • Fix minor style issues in statement case.
NetworkingDsc 7.4.0.0
  • Added Comment Based Help for New-NotImplementedException common function – fixes Issue 411.
  • Added common function “Format-Win32NetworkADapterFilterByNetConnectionID” to properly accept wild cards for Win32_NetworkAdapter filters.
  • Updated MSFT_Netbios to use “Format-Win32NetworkADapterFilterByNetConnectionID”
  • Corrected minor style and consistency issues in NetworkingDsc.Common.tests.ps1 and NetworkingDsc.Common.ps1.
  • Changed verbose messages in Test-DscParameterState to include full type name.
  • Fixed bug in Test-DscParameterState that causes it to return true when both the current array and desired array is empty.
  • Fix minor style issues in statement case.
SecurityPolicyDsc 2.10.0.0
  • Changes to SecurityPolicyDsc
    • Opt-in to the following DSC Resource Common Meta Tests:
      • Common Tests – Validate Module Files
      • Common Tests – Validate Script Files
      • Common Tests – Validate Markdown Files
      • Common Tests – Required Script Analyzer Rules
      • Common Tests – Flagged Script Analyzer Rules
      • Common Tests – New Error-Level Script Analyzer Rules
      • Common Tests – Custom Script Analyzer Rules
      • Common Tests – Validate Markdown Links
      • Common Tests – Relative Path Length
      • Common Tests – Validate Example Files
      • Common Tests – Validate Example Files To Be Published
    • Fix keywords to lower-case to align with guideline.
SqlServerDsc 13.2.0.0
  • Changes to SqlServerDsc
    • Fix keywords to lower-case to align with guideline.
    • Fix keywords to have space before a parenthesis to align with guideline.
xDnsServer 1.15.0.0
xExchange 1.29.0.0
  • Enable Script Analyzer default rules
  • Fixed keywords in upper case
xFailOverCluster 1.13.0.0
  • Updated the xCluster test method to return true if a node is joined to the cluster but is in a Paused state.
xPSDesiredStateConfiguration 8.10.0.0
  • Changes to xPSDesiredStateConfiguration
    • Fix keywords to lower-case to align with guideline.
  • Added SMB PullServer support for publishing.
xRemoteDesktopSessionHost 1.9.0.0
  • Changes to xRDRemoteApp
    • Fixing typo in parameter name when calling the function ValidateCustomModeParameters (issue 50).
  • Changes to xRDSessionDeployment
    • When RDMS service does not exist the Get-TargetResource will no longer throw an error (issue 47).
  • Rename Tests/Unit folder to use upper case on first letter.
  • Update appveyor.yml to use the default template.
  • Added default template files .codecov.yml, .gitattributes, and .gitignore, and .vscode folder.
  • xRDSessionCollectionConfiguration:
    • Changed CollectionName variable validation max length to 256
  • xRDSessionCollection
    • Changed CollectionName variable validation max length to 256
  • xRDRemoteApp
    • Changed CollectionName variable validation max length to 256
xSCSMA 2.1.0.0
  • Update appveyor.yml to use the default template.
  • Added default template files .codecov.yml, .gitattributes, and .gitignore, and .vscode folder.
  • Closed issue 29 – Web bindings fail due to hardcoded WSE
  • Switched from Get-WmiObject Win32_Product to Get-ItemProperty for identifer number
xWebAdministration 2.8.0.0
  • Fix multiple HTTPS bindings on one xWebsite receiving the first binding”s certificate 332
    • Added unit regression test
  • Changes to xWebsite
    • Added ServerAutoStart (controls website autostart) and changed documentation for ServiceAutoStartEnabled (controls application auto-initialization). Fixes 325.
    • Fix multiple HTTPS bindings on one xWebsite receiving the first binding”s certificate 332
      • Added unit regression test
    • Changes to xWebAppPool
      • Fix false Test-TargetResource failure for logEventOnRecycle if items in the Configuration property are specified in a different order than IIS natively stores them 434
    • Changes to xIisModule
      • Fixed the parameters specification for the internal Get-IISHandler and Remove-IISHandler function

How to Find Released DSC Resource Modules

To see a list of all released DSC Resource Kit modules, go to the PowerShell Gallery and display all modules tagged as DSCResourceKit. You can also enter a module’s name in the search box in the upper right corner of the PowerShell Gallery to find a specific module.

Of course, you can also always use PowerShellGet (available starting in WMF 5.0) to find modules with DSC Resources:

# To list all modules that tagged as DSCResourceKit
Find-Module -Tag DSCResourceKit 
# To list all DSC resources from all sources 
Find-DscResource

Please note only those modules released by the PowerShell Team are currently considered part of the ‘DSC Resource Kit’ regardless of the presence of the ‘DSC Resource Kit’ tag in the PowerShell Gallery.

To find a specific module, go directly to its URL on the PowerShell Gallery:
http://www.powershellgallery.com/packages/< module name >
For example:
http://www.powershellgallery.com/packages/xWebAdministration

How to Install DSC Resource Modules From the PowerShell Gallery

We recommend that you use PowerShellGet to install DSC resource modules:

Install-Module -Name < module name >

For example:

Install-Module -Name xWebAdministration

To update all previously installed modules at once, open an elevated PowerShell prompt and use this command:

Update-Module

After installing modules, you can discover all DSC resources available to your local system with this command:

Get-DscResource

How to Find DSC Resource Modules on GitHub

All resource modules in the DSC Resource Kit are available open-source on GitHub.
You can see the most recent state of a resource module by visiting its GitHub page at:
https://github.com/PowerShell/< module name >
For example, for the CertificateDsc module, go to:
https://github.com/PowerShell/CertificateDsc.

All DSC modules are also listed as submodules of the DscResources repository in the DscResources folder and the xDscResources folder.

How to Contribute

You are more than welcome to contribute to the development of the DSC Resource Kit! There are several different ways you can help. You can create new DSC resources or modules, add test automation, improve documentation, fix existing issues, or open new ones.
See our contributing guide for more info on how to become a DSC Resource Kit contributor.

If you would like to help, please take a look at the list of open issues for the DscResources repository.
You can also check issues for specific resource modules by going to:
https://github.com/PowerShell/< module name >/issues
For example:
https://github.com/PowerShell/xPSDesiredStateConfiguration/issues

Your help in developing the DSC Resource Kit is invaluable to us!

Questions, comments?

If you’re looking into using PowerShell DSC, have questions or issues with a current resource, or would like a new resource, let us know in the comments below, on Twitter (@PowerShell_Team), or by creating an issue on GitHub.

Michael Greene
Principal Program Manager
PowerShell DSC Team
@migreene (Twitter)
@mgreenegit (GitHub)

The post DSC Resource Kit Release September 2019 appeared first on PowerShell.

PowerShell 7 Preview 4

This post was originally published on this site

We continue to make progress towards our PowerShell 7 release which currently is targeting December 2019 for a Release Candidate and January 2020 for General Availability and will be our first LTS (Long Term Servicing) release!

Please see the previous blog post on Preview 3 for more details about LTS and also Windows PowerShell compatibility.

Preview 4 contains a number of bug fixes, but also new features which I’ll cover in this blog post.

New Features in Preview 4

This is just a small part of the entire changelog. New experimental features in this preview from the community and also the PowerShell team:

Ternary Operator

The ternary operator is popular among C# developers due to its terseness which can improve readability if you are familiar with this operator.

This operator is completely opt-in so if you prefer to use if..else instead, you can certainly continue to do that.

gif

Start-Job -WorkingDirectory

Those of you familiar with the Start-Job cmdlet will have encountered that the new PowerShell process started to handle the job will have different working directory on Windows PowerShell and PowerShell Core and it can sometimes be not what you expected. This parameter was added to allow you to specify the working directory of the new job process before your script block runs!

gif

$ErrorActionPreference = “Break”

This feature comes from a well known PowerShell MVP Kirk Munro. Basically, if you set $ErrorActionPreference to Break, then when there is an error it will drop you into the debugger immediately!

gif

Invoke-DscResource

With this change, you can now leverage DSC Resources while by-passing the LCM (Local Configuration Manager). This means that you can author your own LCM or simply leverage existing DSC Resources within your scripts and this also works cross platform!

Note that binary DSC Resources are not supported!

gif

DSC Configuration Compilation

Previously if you authored a DSC Configuration script, you would need to use a Windows machine to compile it to a mof file to deploy onto your managed node. Starting with Preview4, you can now perform DSC compilation on non-Windows systems.

Note that this is work in progress with some known issues.

gif

Testing the MSIX package

Recently, we started publishing a MSIX package for Windows. This will eventually allow us to publish PowerShell 7 to the Windows Store. For now, if you wish to try out this package, you must be in Developer Mode and use Add-AppxPackage to install it. Double clicking it from the Windows Shell will not allow you to install the developer signed package.

Closing

Although this blog post focuses on new features, this release also contains many bug fixes as well as targeted performance improvements.

You can always get the latest version of PowerShell from https://aka.ms/get-powershell.

Expect more new features from the community and the PowerShell team in future Preview releases!

Steve Lee
PowerShell Team

The post PowerShell 7 Preview 4 appeared first on PowerShell.

Release of PowerShell Script Analyzer (PSScriptAnalyzer) 1.18.2

This post was originally published on this site

In keeping with the tradition of releasing improvements to PSScriptAnalyzer more often, we’re happy to announce that 1.18.12 is now available! As a dependency of PowerShell Editor Services (a module used by editor extensions like the PowerShell Visual Studio Code extension), this release is motivated by a desire to further stabilize our editor experience. At the moment, the Visual Studio Code PowerShell extension still ships with PSScriptAnalyzer 1.18.0. After fixing some undesirable edge cases between 1.18.1 and 1.18.2, we intend to ship an update to the Visual Studio Code extension that will include 1.18.2.

The blocking issue that it resolves is quite technical and should not concern end-users, but for those who are interested: starting with1.18.1, a performance optimization was added whereby we started to share and cache a PowerShell runspace pool instead of creating a new one for every command invocation. However, it turns out that there is an edge case where, when dealing with specific commands from thePackageManagementmodule, the runspace pool can get into a deadlock, which causes the execution of PSScriptAnalyzer to hang indefinitely. This is due to a bug inPackageManagementitself (a very unfortunate asynchronous API call that leads to the deadlock) but also PowerShell itself, which should be able to handle bad scenarios like this. Therefore, a workaround for this had to be implemented in PSScriptAnalyzer by blacklisting the PackageManagement commands.

Given that the other changes in this release are mainly fixes and small enhancements, we decided to not bump the minor version number. We ask that the community participate in testing and giving feedback on this update before it ships by default in the Visual Studio Code extension. You can make this new update with the Visual Studio Code extension start by executing the following command:

Install-Module -Name PSScriptAnalyzer -Repository PSGallery -Scope CurrentUser

Should you find that there are changes that you are not happy with, please report them here.

Optionally, you can roll back to the default included version of PSScriptAnalyzer by running Uninstall-Module -Name PSScriptAnalyzer.

In this release, we’ve made the following fixes

  • PipelineIndentation: More edge cases when using non-default values of this setting (NoIndentation in the Visual Studio Code extension) were fixed. This feature was only introduced in1.18.0and we hope the be closer to a state now where we could potentially change the default.
  • New compatibility rule profiles were added for non-Windows OSs on PowerShell 7 (preview). Additionally, fixes were made to profile generation to support macOS and Linux.
  • A fix was made to PSCloseBrace to correctly flag the closing brace of a one-line hashtable, correcting some broken formatting.

Enhancements were made in the following areas

  • When using settings files, error messages are now much more actionable.
PS> Invoke-ScriptAnalyzer -Settings /tmp/MySettings.psd1 -ScriptDefinition 'gci'

Invoke-ScriptAnalyzer : includerule is not a valid key in the settings hashtable.
Valid keys are CustomRulePath, ExcludeRules, IncludeRules, IncludeDefaultRules,
RecurseCustomRulePath, Rules and Severity. 
...

  • PSScriptAnalyzer has a logo now thanks to the community member @adilio
  • The formatter was enhanced to also take commented lines into account in multi-line commands
  • The formatter was enhanced to optionally allow correction of aliases as well. With this change, a setting in the Visual Studio Code extension will soon be made available to configure this. By default, this setting will not be on for the moment. We are open to feedback: while there are very likely a few people that would love for it to be enabled, it may upset others.
  • UseDeclaredVarsMoreThanAssignmentsnow also takes into account the usage of Get-Variable with an array of variables and usage of the named parameter -Name

We’ve also made some changes in our GitHub repository and changed the default branch from development to master to simplify the development workflow and be consistent with other repositories in the PowerShell organization. If you have a fork of the project, you will need to make this change in your fork as well or remember to use master as a base and open pull requests against master. This also means that the next version of the Visual Studio Code extension will point tomasterfor the documentation of PSScriptAnalyzer’s rules.

The Changelog has more details if you want to dig further.

Future Directions

We are thinking of following an approach similar to the Visual Studio Code extension where we make a version 2.0 at that drops support for PowerShell version 3 and 4. One of the next changes could be to improve how PowerShellEditorServices calls into PSScriptAnalyzer: currently, Editor Services uses the PSScriptAnalyzer PowerShell cmdlets which means that we have to create an entire instance of PowerShell for these invocations. Knowing that bothPowerShellEditorServicesandPSScriptAnalyzerare binary .NET modules, we could directly call into PSScriptAnalyzer’s .NET code by publishing a NuGet package of PSScriptAnalyzer with suitable public APIs. Given that PSScriptAnalzyer currently performs a conditional compilation for each PowerShell version (3, 4, 5, and 6+), dropping support for version 4 and 5 could help make the aforementioned move to an API model much easier to implement. Please give feedback if your use case ofPSScriptAnalyzerwould be impacted by this.

On behalf of the Script Analyzer team,

Christoph Bergmeister, Project Maintainer from the community, BJSS
Jim Truher, Senior Software Engineer, Microsoft

The post Release of PowerShell Script Analyzer (PSScriptAnalyzer) 1.18.2 appeared first on PowerShell.

PowerShell ForEach-Object Parallel Feature

This post was originally published on this site

PowerShell ForEach-Object Parallel Feature

PowerShell 7.0 Preview 3 is now available with a new ForEach-Object Parallel Experimental feature. This feature is a great new tool for parallelizing work, but like any tool, it has its uses and drawbacks.

This article describes this new feature, how it works, when to use it and when not to.

What is ForEach-Object -Parallel?

ForEach-Object -Parallel is a new parameter set added to the existing PowerShell ForEach cmdlet.

ForEach-Object -Parallel <scriptblock> [-InputObject <psobject>] [-ThrottleLimit <int>] [-TimeoutSeconds <int>] [-AsJob] [-WhatIf] [-Confirm] [<CommonParameters>]

 

Normally, when you use the ForEach-Object cmdlet, each object piped to the cmdlet is processed sequentially.

PS C:> 1..5 | ForEach-Object { "Hello $_"; sleep 1 } Hello 1 Hello 2 Hello 3 Hello 4 Hello 5 PS C:> (Measure-Command { 1..5 | ForEach-Object { "Hello $_"; sleep 1 } }).Seconds 5

But with the new ForEach-Object -Parallel parameter set, you can run all script in parallel for each piped input object.

PS C:> 1..5 | ForEach-Object -Parallel { "Hello $_"; sleep 1; } -ThrottleLimit 5
Hello 1
Hello 3
Hello 2
Hello 4
Hello 5

PS C:> (Measure-Command { 1..5 | ForEach-Object -Parallel { "Hello $_"; sleep 1; } -ThrottleLimit 5 }).Seconds
1

Because each script block in the ForEach-Object example above takes 1 second to run, running all five in parallel takes only one second instead of 5 seconds when run sequentially.

Since the script blocks are run in parallel for each of the 1-5 piped input integers, the order of execution is not guaranteed. The -ThrottleLimit parameter limits the number of script blocks running in parallel at a given time, and its default value is 5.

This new feature also supports jobs, where you can choose to have a job object returned instead of having results written to the console.

PS C:> $Job = 1..5 | ForEach-Object -Parallel { "Hello $_"; sleep 1; } -ThrottleLimit 5 -AsJob PS C:> $job | Wait-Job | Receive-Job Hello 1 Hello 2 Hello 3 Hello 5 Hello 4

ForEach-Object -Parallel is not the same as the foreach language keyword

Don’t confuse ForEach-Object cmdlet with PowerShell’s foreach keyword. The foreach keyword does not handle piped input but instead iterates over an enumerable object. There is currently no parallel support for the foreach keyword.

PS C:> foreach ($item in (1..5)) { "Hello $item" }
Hello 1
Hello 2
Hello 3
Hello 4
Hello 5

How does it work?

The new ForEach-Object -Parallel parameter set uses existing PowerShell APIs for running script blocks in parallel. These APIs have been around since PowerShell v2, but are cumbersome and difficult to use correctly. This new feature makes it much easier to run script blocks in parallel. But there is a fair amount of overhead involved and many times there is no gain in running scripts in parallel, and in fact it can end up being significantly slower than running ForEach-Object normally.

PowerShell currently supports parallelism in three main categories.

  1. PowerShell remoting. Here PowerShell sends script to external machines to run, using PowerShell’s remoting system.
  2. PowerShell jobs. This is the same as remoting except that script is run in separate processes on the local machine, rather than on external machines.
  3. PowerShell runspaces. Here script is run on the local machine within the same process but on separate threads.

This new feature uses the third method for running scripts in parallel. It has the least overhead of the other two methods and does not use the PowerShell remoting system. So it is generally much faster than the other two methods.

However, there is still quite a bit of overhead to run script blocks in parallel. Script blocks run in a context called a PowerShell runspace. The runspace context contains all of the defined variables, functions and loaded modules. So initializing a runspace for script to run in takes time and resources. When scripts are run in parallel they must be run within their own runspace. And each runspace must load whatever module is needed and have any variable be explicitly passed in from the calling script. The only variable that automatically appears in the parallel script block is the piped in object. Other variables are passed in using the $using: keyword.

$computers = 'computerA','computerB','computerC','computerD'
$logsToGet = 'LogA','LogB','LogC'

# Read specified logs on each machine, using custom module
$logs = $computers | ForEach-Object -ThrottleLimit 10 -Parallel {
    Import-Module MyLogsModule
    Get-Logs -ComputerName $_ -LogName $using:logsToGet
}

Given the overhead required to run scripts in parallel, the -ThrottleLimit becomes very useful to prevent the system from being overwhelmed. There are some cases where running a lot of script blocks in parallel makes sense, but also many cases where it does not.

When should it be used?

There are two primary reasons to run script blocks in parallel with the ForEach-Object -Parallel feature (keeping in mind that this feature runs the script on separate system threads).

  1. Highly compute intensive script. If your script is crunching a lot of data over a significant period of time and the scripts can be run independently, then it is worthwhile to run them in parallel. But only if the machine you are running on has multiple cores that can host the script block threads. In this case the -ThrottleLimit parameter should be set approximately to the number of available cores. If you are running on a VM with a single core, then it makes little sense to run high compute script blocks in parallel since the system must serialize them anyway to run on the single core.
  2. Script that must wait on something. If you have script that can run independently and performs long running work that requires waiting for somethings to complete, then it makes sense to run these tasks in parallel. If you have 5 scripts that take 5 minutes each to run but spend most of the time waiting, you can have them all run/wait at the same time, and complete all 5 tasks in 5 minutes instead of 25 minutes. Scripts that do a lot of file operations, or perform operations on external machines can benefit by running in parallel. Since the running script cannot use all of the machine cores, it makes sense to set the -ThrottleLimit parameter to something greater than the number of cores. If one script execution waits many minutes to complete, you may want to allow tens or hundreds of scripts to run in parallel.
$logNames.count
10

PS C:> Measure-Command { $logs = $logNames | ForEach-Object -Parallel { Get-WinEvent -LogName $_ -MaxEvents 5000 2>$null } -ThrottleLimit 10 }
TotalMilliseconds : 115994.3 (1 minute 56 seconds)
$logs.Count
50000

PS C:> Measure-Command { $logs = $logNames | ForEach-Object { Get-WinEvent -LogName $_ -MaxEvents 5000 2>$null } }
TotalMilliseconds : 229768.2364 (3 minutes 50 seconds)
$logs.Count
50000

The script above collects 50,000 log entries on the local machine from 10 system log names. Running this in parallel is almost twice as fast as running sequentially, because it involves some relatively slow disk access and can also take advantage of the machine multiple cores as it processes the log entries.

When should it be avoided?

ForEach-Object -Parallel should not be thought as something that will always speed up script execution. And in fact it can significantly slow down script execution if used heedlessly. For example, if your script block is executing trivial script then running in parallel adds a huge amount of overhead and will run much slower.

PS C:> (measure-command { 1..1000 | ForEach-Object -Parallel { "Hello: $_" } }).TotalMilliseconds
10457.962

PS C:> (measure-command { 1..1000 | ForEach-Object { "Hello: $_" } }).TotalMilliseconds
18.4473

The above example, a trivial script block is run 1000 times. The ThrottleLimit is 5 by default so only 5 runspace/threads are created at a time, but still a runspace and thread is created 1000 times to do a simple string evaluation. Consequently, it takes over 10 seconds to complete. But removing the -Parallel parameter and running the ForEach-Object cmdlet normally, results in completion in about 18 milliseconds.

So, it is important to use this feature wisely.

Implementation details

As previously mentioned, the new ForEach-Object -Parallel feature uses existing PowerShell functionality to run script blocks concurrently. The primary addition is the ability to limit the number of concurrent scripts running at a given time with the -ThrottleLimit parameter. Throttling is accomplished by a PSTaskPool class that holds running tasks (running scripts), and has a settable size limit which is set to the throttle limit value. An Add method allows tasks to be added to the pool, but if it is full then the method blocks until a new slot becomes available. Adding tasks to the task pool was initially performed on the ForEach-Object cmdlet piped input processing thread. But that turned out to be a performance bottleneck, and now a dedicated thread is used to add tasks to the pool.

PowerShell itself imposes conditions on how scripts run concurrently, based on its design and history. Scripts have to run in runspace contexts and only one script thread can run at a time within a runspace. So in order to run multiple scripts simultaneously multiple runspaces must be created. The current implementation of ForEach-Object -Parallel creates a new runspace for each script block execution instance. It may be possible to optimize this by re-using runspaces from a pool, but one concern in doing this is leaking state from one script execution to another.

Runspace contexts are an isolation unit for running scripts, and generally do not allow sharing state between themselves. However, variables can be passed at the beginning of script execution through the $using: keyword, from the calling script to the parallel script block. This was borrowed from the remoting layer which uses the keyword for the same purpose but over a remote connection. But there is a big difference when using the $using: keyword in ForEach-Object -Parallel. And that is for remoting, the variable being passed is a copy sent over the remoting connection. But with ForEach-Object -Parallel, the actual object reference is being passed from one script to another, violating normal isolation restrictions. So it is possible to have a non thread-safe variable used in two scripts running on different threads, which can lead to unpredictable behavior.

# This does not throw an error, but is not guaranteed to work since the dictionary object is not thread safe
$threadUnSafeDictionary = [System.Collections.Generic.Dictionary[string,object]]::new()
Get-Process | ForEach-Object -Parallel {
    $dict = $using:threadUnSafeDictionary
    $dict.TryAdd($_.ProcessName, $_)
}
# This *is* guaranteed to work because the passed in concurrent dictionary object is thread safe
$threadSafeDictionary = [System.Collections.Concurrent.ConcurrentDictionary[string,object]]::new()
Get-Process | ForEach-Object -Parallel {
    $dict = $using:threadSafeDictionary
    $dict.TryAdd($_.ProcessName, $_)
}

$threadSafeDictionary["pwsh"]

 NPM(K)    PM(M)      WS(M)     CPU(s)      Id  SI ProcessName
 ------    -----      -----     ------      --  -- -----------
    112   108.25     124.43      69.75   16272   1 pwsh

Conclusion

This feature can greatly improve your life for many work load scenarios. As long as you understand how it works and what its limitations are, you can experiment with parallelism and make real performance improvements with your scripts.

Paul Higinbotham
Senior Software Engineer
PowerShell Team

The post PowerShell ForEach-Object Parallel Feature appeared first on PowerShell.

New Telemetry in PowerShell 7 Preview 3

This post was originally published on this site

Beginning in PowerShell 7 Preview 3, PowerShell will be sending some additional data points to Microsoft.
This data will allow us to better understand usage of PowerShell and enable us to prioritize our future investments.
These additional points of data were reviewed with the PowerShell community and approved by the PowerShell Committee through the PowerShell RFC process.

What we added

We will continue to use Application Insights to collect the following new telemetry points:

- Count of PowerShell starts by type (API vs console)
    - Count of unique PowerShell usage
    - Count of the following execution types:
        - Application (native commands)
        - ExternalScript
        - Script
        - Function
        - Cmdlet
    - Enabled Microsoft experimental features or experimental features shipped with PowerShell
    - Count of hosted sessions
    - Microsoft owned modules loaded (based on white list)
This data will include the OS name, OS version, the PowerShell version, and the distribution channel when provided.

We will continue to share portions of our aggregated data with the PowerShell community through the
Public PowerBi report.

Why we added it

We want to make PowerShell better and believe this can be achieved by better understanding how PowerShell is being used.
Through these additional data points we will get answers backed by data to the following questions:

  • Is the PowerShell Core user-base growing?
  • How is PowerShell being used? What is the usage distribution across command types and session type?
  • How can we encourage PowerShell Core usage growth?
  • What are issues that customers are hitting in PowerShell Core?
  • What versions of PowerShell tools and services should Microsoft continue to support?
  • Which experimental features are being used and tested? Which experimental features should we invest in?
  • How can we optimize the engine size and efficiency of PowerShell for cloud scenarios?

To ensure we are getting an accurate picture of how everyone uses PowerShell, not just those most
vocal/involved in the community, we made improvements in our telemetry.
PowerShell usage telemetry will allow us to better prioritize testing, support, and investments.

Performance testing

When implementing this telemetry we took special care to ensure that there would not be a discernible performance impact.
The telemetry is collected through Application Insights and is batched and sent on a separate thread in order to reduce impact.
We also conducted tests to verify that there would not be a noticeable difference in PowerShell performance.

In order to test the performance impact of the telemetry we ran our test suite 5 times with and 5 times without the telemetry changes
and compared the average time for test completion.
The tests had a 1% difference in average completion time with the telemetry-enabled test runs actually having the faster average completion. The difference in average completion time, however, was not statistically significant.

We also tested the impact of collecting telemetry on startup time for both cold starts (first start-up of PowerShell) and warm starts (all future starts). We found that on average cold starups were .028 seconds slower with the additional telemetry while warm startups were, on average, .027 slower. The average performance impact was around 4% and all start-ups during the test runs performed faster than .6023 seconds.

How to disable

The telemetry reporting can be disabled by setting the environment variable POWERSHELL_TELEMETRY_OPTOUT to true, yes, or 1.
This should not be done in your profile, as PowerShell reads this value from your system before executing your profile.

Feedback and issues

If you encounter any issues with PowerShell telemetry, the best place to get support is through our GitHub page.

The post New Telemetry in PowerShell 7 Preview 3 appeared first on PowerShell.

PowerShell 7 Preview 3

This post was originally published on this site

PowerShell 7 Preview 3

In May, I published our PowerShell 7 Roadmap. We have been making progress on our roadmap and are currently on track to have a Generally Available (GA)
release by end of this calendar year.

Long Term Servicing

PowerShell 7 GA will also be our first Long Term Servicing (LTS) release which is a change from our current Modern Lifecycle support for PowerShell Core 6.
We will support PowerShell 7 GA for as long as .NET Core 3.1 is supported before you must upgrade to a newer version to continue to be supported by Microsoft.

Windows PowerShell compatibility

One of the main goals of PowerShell 7 is to have a viable replacement for Windows PowerShell 5.1 in production and we’ve made significant progress towards that goal.

PowerShell 7 Preview 3 is built on .NET Core 3.0 Preview 8 and leverages the work from the .NET Team to close the gap between .NET Core and .NET Framework. .NET Core 3.0 reintroduces a large number of .NET Framework APIs, opening up a large number of PowerShell modules shipped with Windows to be validated and marked as compatible by our team. Because the compatibility changes to the modules come as part of Windows, the latest version of Windows 10/Windows Server is required for full module compatibility.

However, on older versions of Windows, some modules may just work if you use:

Import-Module <moduleName> -SkipEditionCheck

If you have issues with a Microsoft PowerShell module, please open an issue in the PowerShellModuleCoverage repository!

Expect more content on this specific topic from Joey Aiello in the near future with more detail on which modules are compatible and where they’re marked as such.

New Features in Preview 3

This is just a small part of the entire changelog.
New features in this preview from the community and also the PowerShell team:

Experimental Features on by default in Preview builds

We decided to enable all Experimental Features by default in order to solicit more feedback for the PowerShell Committee to determine if a feature should continue as experimental, move from experimental to stable (non-experimental), or be withdrawn. On Stable builds (as well as Release Candidates), experimental features will continue to be disabled by default.

Note that if you had previously manually enabled experimental features, your powershell.config.jsonsettings file will take precedence and only experimental features listed within that file will be enabled. You can delete that file or run Get-ExperimentalFeature | Enable-ExperimentalFeature to ensure all experimental features are enabled. However, if you use the pipeline, you’ll have to do it again with a future Preview release that has new experimental features.

gif

Single Apartment Thread as default

In general, you don’t need to worry about a concept called ApartmentState which only applies to Windows.

Prior to this release pwsh would run as a multi-threaded apartment by default. However, graphical user interface (GUI) APIs such as WinForms and WPF require a single-threaded apartment. What is important here is that pwsh is now the same as powershell.exe in regards to apartment state and as such support calling WinForms and WPF APIs from PowerShell script.

gif

Display COM Method Signature Argument Names

On Windows, if you happen to call COM APIs from PowerShell, a new capability by nbkalex will now show the argument names of COM methods instead of just the type information which can be used as simple documentation indicating what arguments should be passed.

gif

Consider DBNull and NullString as $null

If you work with database types, you may get back a [dbnull]::Value which is equivalent to $null within the database, but in PowerShell, this was not equal to $null so you can’t compare it directly. This change from Joel Sallow allows you to compare both [dbnull]::Value and [nullstring]::Value to $null and get $true.

gif

Read-Host -Prompt works for all input

Due to how Read-Host calls into the console host and how the console host prompts for input (such as mandatory parameters that are given a value), you might encounter a situation where using Read-Host to prompt for input in your script exhibits unintended behavior when certain characters are used. This has been fixed so Read-Host will accept input as expected.

gif

Support negative numbers with -Split operator

The -Split operator splits one or more strings into substrings. You can optionally specify a value to indicate the maximum number of substrings you want returned.

This new capability by Jacob Scott now allows you to specify the maximum number of substrings as a negative value signifying that the split should happen right to left instead of the usual left to right.

gif

ForEach-Object -Parallel

We’ve received consistent feedback that PowerShell users use PSWorkflow primarily to easily run scriptblocks in parallel.

We’ve added a -Parallel parameter to ForEach-Object that accepts a scriptblock to execute in parallel. There is an optional -ThrottleLimit parameter to set the maximum threads to use in parallel where it defaults to 5.

gif

Resolve AppX reparse points

On Windows 10, if you have apps installed from the Windows Store and list them in the command line, they show up as 0 byte files. These files are actually a different type of link to the actual executable. With this change, the target executable will now show up when using Get-ChildItem.

gif

pwsh as a login shell

On Linux and macOS systems, there is a concept of a login shell which sets up the environment from which other apps and shells inherit. Prior to this release if you used pwsh as your default login shell, you may have noticed that some environment variables are missing or incomplete.

With this change, pwsh will work the same as sh Bourne Shell in how it sets up the login environment so that everything works correctly.

Additional Telemetry

In this Preview release, we’ve added more telemetry. Please see Sydney Smith‘s blog post on New Telemetry in PowerShell 7 Preview 3.

Closing

Although this blog post focuses on new features, this release also contains many bug fixes as well as targeted performance improvements.

You can always get the latest version of PowerShell from https://aka.ms/get-powershell.

Expect more new features from the community and the PowerShell team in future Preview releases!

Steve Lee
PowerShell Team

The post PowerShell 7 Preview 3 appeared first on PowerShell.

Out-GridView Returns

This post was originally published on this site

Out-GridView Returns!

It’s been almost 3 years since PowerShell Core debuted for Linux and Mac, and as we’ve increased our cmdlet coverage more and more, one cmdlet has always stood out as a top, cross-platform request. Today, we are excited to announce that Out-GridView is debuting on all Core-supported platforms through the GraphicalTools Module.

Linux Windows Mac
linux-gif window-gif macos-gif

Installation

If you want to get right to it:

Install-Module Microsoft.PowerShell.GraphicalTools

Features

Out-GridView is a visualization tool to help you deep dive into objects returned from PowerShell.

Out-GridViewImage Piping Get-Process into Out-GridView

Quick Search

Easily locate data points matching a query.

Filters

Display specific data matching only selected filters. Supports common string comparison operators, such as contains, equals, starts with, etc..

DataGrid

Rearrange, sort, and select columns to display. Auto-generates object columns based on the PowerShell format type data, expands PSObject properties if no format definition is available.

PassThru

One of the most powerful features, the -PassThru parameter lets you use the GUI to select data to send further down the pipeline.

Get-Process | Out-GridView -PassThru | Stop-Process

If you were so inclined the above script uses -PassThru to create a pretty effective emulation of Windows Task Manger.

Show Code

Sometimes, you need to automate infrequent but complex tasks where filters may be error-prone. Out-GridView can be used as a filtering tool for these cases to ensure that your filters will produce the output you expect.

Occasionally, you end up needing to repeat this automation and so it would be useful to port your existing Out-GridView workflow to a script.

Pressing the “Show-Code” button will do this for you. It will generate a PowerShell filtering script that is ready for production.

Out-GridViewImage Using Show Code to find a specific instance of VSCode

Examples of Out-GridView

The Future

We are looking for a community member to help port Show-Command and Show-Object. Check out the repository and post in the issue tracking Show-Command if you’re interested.

With the majority of the brunt work integrating PowerShell & Avalonia done, we are also open to submissions for new graphical commands or packages. A huge thanks to Adam Driscoll for showing the potential of Avalonia + PowerShell with PSAvalonia.

Lastly, check out the great work AvaloniaUI is doing for cross-platform, .NET Core-based GUIs if you haven’t already.


John Zeiders
Software Engineering Intern
PowerShell Team

The post Out-GridView Returns appeared first on PowerShell.

DSC Resource Kit Release July 2019

This post was originally published on this site

We just released the DSC Resource Kit!

This release includes updates to 11 DSC resource modules. In the past 6 weeks, 96 pull requests have been merged and 45 issues have been closed, all thanks to our amazing community!

The modules updated in this release are:

  • ActiveDirectoryDsc
  • ActiveDirectoryCSDsc
  • ComputerManagementDsc
  • SecurityPolicyDsc
  • SharePointDsc
  • SqlServerDsc
  • StorageDsc
  • xDnsServer
  • xExchange
  • xPSDesiredStateConfiguration
  • xWebAdministration

For a detailed list of the resource modules and fixes in this release, see the Included in this Release section below.

Our latest community call for the DSC Resource Kit was last Wednesday, July 31. A recording of the call is posted on the PowerShell YouTube channel. You can join us for the next call at 12PM (Pacific time) on August 28th to ask questions and give feedback about your experience with the DSC Resource Kit.

The next DSC Resource Kit release will be on Wednesday, September 8.

We strongly encourage you to update to the newest version of all modules using the PowerShell Gallery, and don’t forget to give us your feedback in the comments below, on GitHub, or on Twitter (@PowerShell_Team)!

Please see our documentation here for information on the support of these resource modules.

Included in this Release

You can see a detailed summary of all changes included in this release in the table below. For past release notes, go to the README.md or CHANGELOG.md file on the GitHub repository page for a specific module (see the How to Find DSC Resource Modules on GitHub section below for details on finding the GitHub page for a specific module).

Module Name Version Release Notes
ActiveDirectoryCSDsc 4.0.0.0
  • BREAKING CHANGE: ActiveDirectoryCSDsc module minimum requirements updated to WMF 5.0 because newly added AdcsCertificateAuthoritySettings resource requires WMF 5.0.
  • Added new resource AdcsCertificateAuthoritySettings – see Issue 13.
  • Added new resource AdcsTemplate.
  • Replaced switch blocks with if blocks for evaluating “Ensure” parameter because switch was missing break – fixes Issue 87.
  • Added Comment Based Help for New-NotImplementedException common function.
  • Moved code to create the user account for use in integration test into a CommonTestHelper.psm1 function.
  • Removed user account creation code from AppVeyor.yml and into integration tests themselves to make tests execution easier.
  • Updated user account creation code to use local user/group management Powershell cmdlets available in WMF 5.1 – fixes Issue 24.
  • AdcsCertificationAuthority:
    • Integration tests updated to create test user account in administrators group to make test execution easier.
ActiveDirectoryDsc 4.0.0.0
    The change log length exceeds the allowable limit for PowerShell Gallery. For detailed information about the changes to each resource, see the changelog.md file in the GitHub repo.

  • Changes to ActiveDirectoryDsc
  • Changes to ADManagedServiceAccount
  • Changes to ADComputer
  • Changes to ADOrganizationalUnit
  • Changes to ADUser
  • Changes to ADDomain
  • Changes to ADServicePrincipalName
  • Changes to ADDomainTrust
  • Changes to WaitForADDomain
  • Changes to ADDomainController
  • Changes to ADObjectPermissionEntry
  • Changes to ADGroup
  • Changes to ADDomainDefaultPasswordPolicy
ComputerManagementDsc 6.5.0.0
  • Computer:
    • Fix for “directory service is busy” error when joining a domain and renaming a computer when JoinOU is specified – Fixes Issue 221.
  • Added new resource SmbShare
    • Moved and improved from deprecated module xSmbShare.
  • Changes to ComputerManagementDsc.Common
    • Updated Test-DscParameterState so it now can compare zero item collections (arrays).
  • Changes to WindowsEventLog
    • Minor style guideline cleanup.
  • Opt-in to common test to validate localization. Fixed localization strings in resources – Fixes Issue 217.
  • PowerShellExecutionPolicy:
    • Removed SupportsShouldProcess as it cannot be used with DSC – Fixes Issue 219.
  • Combined all ComputerManagementDsc.ResourceHelper module functions into ComputerManagementDsc.Common module – Fixes Issue 218.
    • Minor code cleanup against style guideline.
    • Remove code from New-InvalidOperationException because it was a code path that could never could be used due to the parameter validation preventing the helper function being called that way.
    • Updated all Get-LocalizationData to latest version from DSCResource.Template.
    • Fixed an issue with the helper function Test-IsNanoServer that prevented it to work. Though the helper function is not used, so this issue was not caught until now when unit tests was added.
    • Improved code coverage.
SecurityPolicyDsc 2.9.0.0
  • Bug fix – Max password age fails when setting to 0. Fixes Issue 121
  • Bug fix – Domain_controller_LDAP_server_signing_requirements – Require Signing. Fixes Issue 122
  • Bug fix – Network_security_Restrict_NTLM security options correct parameter validation. This fix could impact your systems.
SqlServerDsc 13.1.0.0
  • Changes to SqlServerDsc
    • New DSC resource SqlAgentFailsafe
    • New DSC resource SqlDatabaseUser (issue 846).
      • Adds ability to create database users with more fine-grained control, e.g. re-mapping of orphaned logins or a different login. Supports creating a user with or without login name, and database users mapped to a certificate or asymmetric key.
    • Changes to helper function Invoke-Query
      • Fixes issues in issue 1355.
      • Works together with Connect-SQL now.
      • Parameters now match that of Connect-SQL (issue 1392).
      • Can now pass in credentials.
      • Can now pass in “Microsoft.SqlServer.Management.Smo.Server” object.
      • Can also pipe in “Microsoft.SqlServer.Management.Smo.Server” object.
      • Can pipe Connect-SQL
StorageDsc 4.7.0.0
  • Removed suppression of PSUseShouldProcessForStateChangingFunctions PSSA rule because it is no longer required.
  • Combined all StorageDsc.ResourceHelper module functions into StorageDsc.Common module and removed StorageDsc.ResourceHelper.
  • Opted into Common Tests “Common Tests – Validate Localization” – fixes Issue 206.
  • Refactored tests for StorageDsc.Common to meet latest standards.
  • Minor style corrections.
  • Removed unused localization strings from resources.
  • DiskAccessPath:
    • Added function to force refresh of disk subsystem at the start of Set-TargetResource to prevent errors occuring when the disk access path is already assigned – See Issue 121
xDnsServer 1.14.0.0
  • Copied enhancements to Test-DscParameterState from NetworkingDsc
  • Put the helper module to its own folder
  • Copied enhancements to Test-DscParameterState from NetworkingDsc
  • Put the helper module to its own folder
  • Added xDnsServerRootHint resource
  • Added xDnsServerClientSubnet resource
  • Added xDnsServerZoneScope resource
xExchange 1.28.0.0
  • Added MSFT_xExchFrontendTransportService resource, based on MSFT_xExchTransportService resource. Issue 283
  • Added unit and integration tests to the MSFT_xExchFrontendTransportService resource.
  • Added comment based help to the MSFT_xExchFrontendTransportService resource.
  • Minor style fix in MSFT_xExchEcpVirtualDirectory to ensure new PowerShell Script Analyzer custom rules pass.
xPSDesiredStateConfiguration 8.9.0.0
  • MSFT_xRemoteFile:
    • Add a retry mechanism when the download fails.
  • Fixes 631, typo in SQL connection string property name
xWebAdministration 2.7.0.0
  • Changes to xWebAdministration
    • Opt-in to the following DSC Resource Common Meta Tests:
      • Common Tests – Relative Path Length
      • Common Tests – Validate Script Files
      • Common Tests – Validate Module Files
      • Common Tests – Validate Markdown Files
      • Common Tests – Validate Markdown Links
      • Common Tests – Custom Script Analyzer Rules
      • Common Tests – Flagged Script Analyzer Rules
      • Common Tests – Required Script Analyzer Rules
      • Common Tests – Validate Example Files
    • Add ConfigurationPath to xIisMimeTypeMapping examples since it is now a required field.

How to Find Released DSC Resource Modules

To see a list of all released DSC Resource Kit modules, go to the PowerShell Gallery and display all modules tagged as DSCResourceKit. You can also enter a module’s name in the search box in the upper right corner of the PowerShell Gallery to find a specific module.

Of course, you can also always use PowerShellGet (available starting in WMF 5.0) to find modules with DSC Resources:

# To list all modules that tagged as DSCResourceKit
Find-Module -Tag DSCResourceKit 
# To list all DSC resources from all sources 
Find-DscResource

Please note only those modules released by the PowerShell Team are currently considered part of the ‘DSC Resource Kit’ regardless of the presence of the ‘DSC Resource Kit’ tag in the PowerShell Gallery.

To find a specific module, go directly to its URL on the PowerShell Gallery:
http://www.powershellgallery.com/packages/< module name >
For example:
http://www.powershellgallery.com/packages/xWebAdministration

How to Install DSC Resource Modules From the PowerShell Gallery

We recommend that you use PowerShellGet to install DSC resource modules:

Install-Module -Name < module name >

For example:

Install-Module -Name xWebAdministration

To update all previously installed modules at once, open an elevated PowerShell prompt and use this command:

Update-Module

After installing modules, you can discover all DSC resources available to your local system with this command:

Get-DscResource

How to Find DSC Resource Modules on GitHub

All resource modules in the DSC Resource Kit are available open-source on GitHub.
You can see the most recent state of a resource module by visiting its GitHub page at:
https://github.com/PowerShell/< module name >
For example, for the CertificateDsc module, go to:
https://github.com/PowerShell/CertificateDsc.

All DSC modules are also listed as submodules of the DscResources repository in the DscResources folder and the xDscResources folder.

How to Contribute

You are more than welcome to contribute to the development of the DSC Resource Kit! There are several different ways you can help. You can create new DSC resources or modules, add test automation, improve documentation, fix existing issues, or open new ones.
See our contributing guide for more info on how to become a DSC Resource Kit contributor.

If you would like to help, please take a look at the list of open issues for the DscResources repository.
You can also check issues for specific resource modules by going to:
https://github.com/PowerShell/< module name >/issues
For example:
https://github.com/PowerShell/xPSDesiredStateConfiguration/issues

Your help in developing the DSC Resource Kit is invaluable to us!

Questions, comments?

If you’re looking into using PowerShell DSC, have questions or issues with a current resource, or would like a new resource, let us know in the comments below, on Twitter (@PowerShell_Team), or by creating an issue on GitHub.

Michael Greene
Principal Program Manager
PowerShell DSC Team
@migreene (Twitter)
@mgreenegit (GitHub)

The post DSC Resource Kit Release July 2019 appeared first on PowerShell.

Introducing PowerShell as .NET Global Tool

This post was originally published on this site

PowerShell is very suitable for CI/CD scenarios due to its easy and well understood scripting paradigm,
and its cross-platform support makes it great for building and testing cross-platform applications.
A .NET Global Tool is a special NuGet package that contains a console application.

A .NET Core application can be developed for various platforms like Windows, various distributions of Linux and macOS, while the same PowerShell scripts can be used for building, testing and deployment across all platforms.

Installing PowerShell Global tool

If you already have the .NET Core SDK installed, it’s easy to install PowerShell as a .NET global tool!

dotnet tool install --global PowerShell

Once installed, you can run it with pwsh.

PowerShell in .NET SDK docker containers

PowerShell has already been included as a global tool within the .NET Core 3.0 Preview Docker images since Preview.4.
These images are a great starting point for building a .NET Core CI/CD image
(you can find some awesome samples
over at the dotnet-docker repo.)

Docker files with PowerShell syntax

As PowerShell comes pre-installed, Docker files can have PowerShell syntax.
This allows you to run scripts or cmdlets as part of your Docker file.

FROM mcr.microsoft.com/dotnet/core/sdk:3.0
RUN pwsh -c Get-Date
RUN pwsh -c "Get-Module -ListAvailable | Select-Object -Property Name, Path"

Build scenarios in Docker

In addition to enabling PowerShell syntax, PowerShell scripts in the container can be easily invoked through Docker:

docker run -it -v c:myrepo:/myrepo -w /myrepo mcr.microsoft.com/dotnet/core/sdk:3.0 pwsh ./build.ps1

The NuGet package for the global tool can be found at: https://www.nuget.org/packages/PowerShell/

Please report issues or suggestions at: https://github.com/PowerShell/PowerShell/issues/new/choose

Thank you!

Aditya Patwardhan
Senior Software Engineer
PowerShell Team
@adityapatward13

The post Introducing PowerShell as .NET Global Tool appeared first on PowerShell.

DSC Resource Kit Release June 2019

This post was originally published on this site

We just released the DSC Resource Kit!

This release includes updates to 8 DSC resource modules. In the past 6 weeks, 95 pull requests have been merged and 55 issues have been closed, all thanks to our amazing community!

The modules updated in this release are:

  • CertificateDsc
  • NetworkingDsc
  • PSDscResources
  • SharePointDsc
  • SqlServerDsc
  • xActiveDirectory
  • xDnsServer
  • xPSDesiredStateConfiguration

For a detailed list of the resource modules and fixes in this release, see the Included in this Release section below.

Our latest community call for the DSC Resource Kit was last Wednesday, June 19. A recording of the call with be posted on the PowerShell YouTube channel soon. You can join us for the next call at 12PM (Pacific time) on July 31 to ask questions and give feedback about your experience with the DSC Resource Kit.

The next DSC Resource Kit release will be on Wednesday, August 7.

We strongly encourage you to update to the newest version of all modules using the PowerShell Gallery, and don’t forget to give us your feedback in the comments below, on GitHub, or on Twitter (@PowerShell_Team)!

Please see our documentation here for information on the support of these resource modules.

Included in this Release

You can see a detailed summary of all changes included in this release in the table below. For past release notes, go to the README.md or CHANGELOG.md file on the GitHub repository page for a specific module (see the How to Find DSC Resource Modules on GitHub section below for details on finding the GitHub page for a specific module).

Module Name Version Release Notes
CertificateDsc 4.7.0.0
  • Opted into Common Tests “Common Tests – Validate Localization” – fixes Issue 195.
  • Combined all CertificateDsc.ResourceHelper module functions into CertificateDsc.Common module and renamed to CertificateDsc.CommonHelper module.
  • CertReq:
    • Fix error when ProviderName parameter is not encapsulated in double quotes – fixes Issue 185.
  • Refactor integration tests to update to latest standards.
  • Refactor unit tests to update to latest standards.
  • CertificateImport:
    • Refactor to use common functions and share more code with PfxImport resource.
    • Resource will now only throw an exception if the PFX file does not exist and it needs to be imported.
    • Removed file existence check from Path parameter to enable the resource to remove a certificate from the store without the need to have the access to the certificate file.
    • Removed ShouldProcess because it is not required by DSC Resources.
  • CertificatePfx:
    • Refactor to use common functions and share more code with CertificateImport resource.
    • Resource will now only throw an exception if the certificate file does not exist and it needs to be imported.
  • CertificateImport:
    • Added FriendlyName parameter to allow setting the certificate friendly name of the imported certificate – fixes Issue 194.
  • CertificatePfx:
    • Added FriendlyName parameter to allow setting the certificate friendly name of the imported certificate – fixes Issue 194.
NetworkingDsc 7.3.0.0
  • DnsClientGlobalSettings:
    • Fixed SuffixSearchList Empty String Handling – fixes Issue 398.
  • NetAdapterAdvancedProperty:
    • Removed validation from RegistryKeyword parameter because the list of valid registry keywords is not fixed and will depend on adapter driver – fixes Issue 388.
  • MSFT_WinsServerAddress Added MSFT_WinsServerAddress to control the WINS servers for a given network adapter.
  • Test-DscParameterState:
    • This function was enhanced with an optional reversecheck, optional internal sorting for arrays.
    • The functions ConvertTo-CimInstance and ConvertTo-Hashtable were added required by Test-DscParameterState.
  • Fix missing context message content in unit tests – fixes Issue 405.
  • Correct style violations in unit tests:
    • Adding Get, Set and Test tags to appropriate describe blocks.
    • Removing uneccesary region blocks.
    • Conversion of double quotes to single quotes where possible.
    • Replace variables with string litterals in describe block description.
  • Firewall:
    • Fix bug when LocalAddress or RemoteAddress is specified using CIDR notation with number of bits specified in subnet mask (e.g. 10.0.0.1/8) rather than using CIDR subnet mask notation (e.g 10.0.0.1/255.0.0.0) – fixes Issue 404.
PSDscResources 2.12.0.0
  • Ports style fixes that were recently made in xPSDesiredStateConfiguration on test related files.
  • Ports most of the style upgrades from xPSDesiredStateConfiguration that have been made in files in the DscResources folder.
  • Ports fixes for the following issues: Issue 505 Issue 590 Changes to test helper Enter-DscResourceTestEnvironment so that it only updates DSCResource.Tests when it is longer than 120 minutes since it was last pulled. This is to improve performance of test execution and reduce the likelihood of connectivity issues caused by inability to pull DSCResource.Tests.
  • Fixes issue where MsiPackage Integration tests fail if the test HttpListener fails to start. Moves the test HttpListener objects to dynamically assigned, higher numbered ports to avoid conflicts with other services, and also checks to ensure that the ports are available before using them. Adds checks to ensure that no outstanding HTTP server jobs are running before attempting to setup a new one. Also adds additional instrumentation to make it easier to troubleshoot issues with the test HttpListener objects in the future. Specifically fixes Issue 142
  • Improved speed of Test-IsNanoServer function
  • Remove the Byte Order Mark (BOM) from all affected files
  • Opt-in to “Validate Module Files” and “Validate Script Files” common meta-tests
  • Opt-in to “Common Tests – Relative Path Length” common meta-test
  • Fix README markdownlint validation failures
  • Move change log from README.md to CHANGELOG.md
SharePointDsc 3.5.0.0
  • SharePointDsc generic
    • Improved logging in all resource. They are now outputting the current and targeted values in the Test method.
    • Updated various resources to comply with coding style guidelines.
    • Updated the following resources to not return Null from the Get method anymore, but an hashtable which contains null values: SPDesignerSettings, SPDiagnosticLoggingSettings, SPFarmAdministrators, SPHealthAnalyzerRuleState, SPIrmSettings, SPOutgoingEmailSettings, SPPasswordChangeSettings, SPSearchTopology, SPServiceAppProxyGroup, SPTimerJobState, SPUserProfileSection, SPUserProfileSyncConnection, SPWebAppBlockedFileTypes, SPWebApplicationAppDomain, SPWebAppPolicy, SPWebAppSiteUseAndDeletion, SPWebAppThrottlingSettings, SPWordAutomationServiceApp.
  • SPConfigWizard
    • Added check to make sure the Config Wizard is only executed when all servers have the binaries installed.
  • SPDistributedCacheService
    • Added ability to check for incorrect service account.
  • SPExcelServiceApp
    • Fixes issue where Get method throws an error when the value of PrivateBytesMax and UnusedObjectAgeMax are negative values.
  • SPFarm
    • Throw error in Get method if CentralAdministrationUrl is HTTP.
  • SPInstallPrereqs
    • Fixed bug in version check, where lower versions would be detected as higher versions.
  • SPProductUpdate
    • Updated Readme to reflect the new patching possibilities added in v3.3.
  • SPSecureStore
    • Fixed issue where the test issue returned false is the service application didn’t exist, but the database name/server parameter was specified.
  • SPUserProfileSyncConnection
    • Fixed issue where the parameter Server was checked in SP2016 but isn’t used there and therefore always fails.
  • SPWebAppAuthentication
    • Updated the documentation to better explain the use of this resource when using Classic authentication.
SqlServerDsc 13.0.0.0
  • Changes to SqlServerDsc
    • Added SqlAgentAlert resource.
    • Opt-in to the common test “Common Test – Validation Localization”.
    • Opt-in to the common test “Common Test – Flagged Script Analyzer Rules” (issue 1101).
    • Removed the helper function New-TerminatingError, New-WarningMessage and New-VerboseMessage in favor of the the new localization helper functions.
    • Combine DscResource.LocalizationHelper and DscResource.Common into SqlServerDsc.Common (issue 1357).
    • Update Assert-TestEnvironment.ps1 to not error if strict mode is enabled and there are no missing dependencies (issue 1368).
  • Changes to SqlServerDsc.Common
    • Added StatementTimeout to function “Connect-SQL” with default 600 seconds (10mins).
    • Added StatementTimeout to function “Invoke-Query” with default 600 seconds (10mins) (issue 1358).
    • Changes to helper function Connect-SQL
      • The function now make it more clear that when using the parameter SetupCredential is impersonates that user, and by default it does not impersonates a user but uses the credential that the resource is run as (for example the built-in credential parameter PsDscRunAsCredential). @kungfu71186
      • Added parameter alias -DatabaseCredential for the parameter -SetupCredential. @kungfu71186
  • Changes to SqlAG
    • Added en-US localization.
  • Changes to SqlAGReplica
    • Added en-US localization.
    • Improved verbose message output when creating availability group replica, removing a availability group replica, and joining the availability group replica to the availability group.
  • Changes to SqlAlwaysOnService
    • Now outputs the correct verbose message when restarting the service.
  • Changes to SqlServerMemory
    • Now outputs the correct verbose messages when calculating the dynamic memory, and when limiting maximum memory.
  • Changes to SqlServerRole
    • Now outputs the correct verbose message when the members of a role is not in desired state.
  • Changes to SqlAgentOperator
    • Fix minor issue that when unable to connect to an instance. Instead of showing a message saying that connect failed another unrelated error message could have been shown, because of an error in the code.
    • Fix typo in test it block.
  • Changes to SqlDatabaseRole
  • Changes to SqlSetup
    • Add an Action type of “Upgrade”. This will ask setup to do a version upgrade where possible (issue 1368).
    • Fix an error when testing for DQS installation (issue 1368).
    • Changed the logic of how default value of FailoverClusterGroupName is set since that was preventing the resource to be able to be debugged (issue 448).
    • Added RSInstallMode parameter (issue 1163).
  • Changes to SqlWindowsFirewall
    • Where a version upgrade has changed paths for a database engine, the existing firewall rule for that instance will be updated rather than another one created (issue 1368). Other firewall rules can be fixed to work in the same way later.
  • Changes to SqlAGDatabase
    • Added new parameter “ReplaceExisting” with default false. This allows forced restores when a database already exists on secondary.
    • Added StatementTimeout to Invoke-Query to fix Issue1358
    • Fix issue where calling Get would return an error because the database name list may have been returned as a string instead of as a string array (issue 1368).
xActiveDirectory 3.0.0.0
  • Changes to xActiveDirectory
    • Added new helper functions in xADCommon, see each functions comment-based help for more information.
      • Convert-PropertyMapToObjectProperties
      • Compare-ResourcePropertyState
      • Test-DscPropertyState
    • Move the examples in the README.md to Examples folder.
    • Fix Script Analyzer rule failures.
    • Opt-in to the following DSC Resource Common Meta Tests:
      • Common Tests – Custom Script Analyzer Rules
      • Common Tests – Required Script Analyzer Rules
      • Common Tests – Flagged Script Analyzer Rules
      • Common Tests – Validate Module Files (issue 282)
      • Common Tests – Validate Script Files (issue 283)
      • Common Tests – Relative Path Length (issue 284)
      • Common Tests – Validate Markdown Links (issue 280)
      • Common Tests – Validate Localization (issue 281)
      • Common Tests – Validate Example Files (issue 279)
      • Common Tests – Validate Example Files To Be Published (issue 311)
    • Move resource descriptions to Wiki using auto-documentation (issue 289)
    • Move helper functions from MSFT_xADCommon to the module xActiveDirectory.Common (issue 288).
      • Removed helper function Test-ADDomain since it was not used. The helper function had design flaws too.
      • Now the helper function Test-Members outputs all the members that are not in desired state when verbose output is enabled.
    • Update all unit tests to latest unit test template.
    • Deleted the obsolete xActiveDirectory_TechNetDocumentation.html file.
    • Added new resource xADObjectEnabledState. This resource should be used to enforce the Enabled property of computer accounts. This resource replaces the deprecated Enabled property in the resource xADComputer.
    • Cleanup of code
      • Removed semicolon throughout where it is not needed.
      • Migrate tests to Pester syntax v4.x (issue 322).
      • Removed -MockWith {} in unit tests.
      • Use fully qualified type names for parameters and variables (issue 374).
    • Removed unused legacy test files from the root of the repository.
    • Updated Example List README with missing resources.
    • Added missing examples for xADReplicationSubnet, xADServicePrincipalName and xWaitForADDomain. (issue 395).
  • Changes to xADComputer
    • Refactored the resource and the unit tests.
    • BREAKING CHANGE: The Enabled property is DEPRECATED and is no longer set or enforces with this resource. If this parameter is used in a configuration a warning message will be outputted saying that the Enabled parameter has been deprecated. The new resource xADObjectEnabledState can be used to enforce the Enabled property.
    • BREAKING CHANGE: The default value of the enabled property of the computer account will be set to the default value of the cmdlet New-ADComputer.
    • A new parameter was added called EnabledOnCreation that will control if the computer account is created enabled or disabled.
    • Moved examples from the README.md to separate example files in the Examples folder.
    • Fix the RestoreFromRecycleBin description.
    • Fix unnecessary cast in Test-TargetResource (issue 295).
    • Fix ServicePrincipalNames property empty string exception (issue 382).
  • Changes to xADGroup
    • Change the description of the property RestoreFromRecycleBin.
    • Code cleanup.
  • Changes to xADObjectPermissionEntry
    • Change the description of the property IdentityReference.
    • Fix failure when applied in the same configuration as xADDomain.
    • Localize and Improve verbose messaging.
    • Code cleanup.
  • Changes to xADOrganizationalUnit
    • Change the description of the property RestoreFromRecycleBin.
    • Code cleanup.
    • Fix incorrect verbose message when this resource has Ensure set to Absent (issue 276).
  • Changes to xADUser
    • Change the description of the property RestoreFromRecycleBin.
    • Added ServicePrincipalNames property (issue 153).
    • Added ChangePasswordAtLogon property (issue 246).
    • Code cleanup.
    • Added LogonWorkstations property
    • Added Organization property
    • Added OtherName property
    • Added AccountNotDelegated property
    • Added AllowReversiblePasswordEncryption property
    • Added CompoundIdentitySupported property
    • Added PasswordNotRequired property
    • Added SmartcardLogonRequired property
    • Added ProxyAddresses property (Issue 254).
    • Fix Password property being updated whenever another property is changed (issue 384).
    • Replace Write-Error with the correct helper function (Issue 331).
  • Changes to xADDomainController
    • Change the Requires statement in the Examples to require the correct module.
    • Suppressing the Script Analyzer rule PSAvoidGlobalVars since the resource is using the $global:DSCMachineStatus variable to trigger a reboot.
    • Code cleanup.
  • Changes to xADDomain
    • Suppressing the Script Analyzer rule PSAvoidGlobalVars since the resource is using the $global:DSCMachineStatus variable to trigger a reboot.
    • Code cleanup.
  • Changes to xADDomainTrust
    • Replaced New-TerminatingError with Standard Function.
    • Code cleanup.
  • Changes to xWaitForADDomain
    • Suppressing the Script Analyzer rule PSAvoidGlobalVars since the resource is using the $global:DSCMachineStatus variable to trigger a reboot.
    • Added missing property schema descriptions (issue 369).
    • Code cleanup.
  • Changes to xADRecycleBin
    • Remove unneeded example and resource designer files.
    • Added missing property schema descriptions (issue 368).
    • Code cleanup.
    • It now sets back the $ErrorActionPreference that was set prior to setting it to "Stop".
    • Replace Write-Error with the correct helper function (issue 327).
  • Changes to xADReplicationSiteLink
    • Fix ADIdentityNotFoundException when creating a new site link.
    • Code cleanup.
  • Changes to xADReplicationSubnet
    • Remove `{ Present
xDnsServer 1.13.0.0
  • Added resource xDnsServerConditionalForwarder
  • Added xDnsServerDiagnostics resource to this module.
xPSDesiredStateConfiguration 8.8.0.0
  • Ports fix for the following issue: Issue 142 Fixes issue where MsiPackage Integration tests fail if the test HttpListener fails to start. Moves the test HttpListener objects to dynamically assigned, higher numbered ports to avoid conflicts with other services, and also checks to ensure that the ports are available before using them. Adds checks to ensure that no outstanding HTTP server jobs are running before attempting to setup a new one. Also adds additional instrumentation to make it easier to troubleshoot issues with the test HttpListener objects in the future.

How to Find Released DSC Resource Modules

To see a list of all released DSC Resource Kit modules, go to the PowerShell Gallery and display all modules tagged as DSCResourceKit. You can also enter a module’s name in the search box in the upper right corner of the PowerShell Gallery to find a specific module.

Of course, you can also always use PowerShellGet (available starting in WMF 5.0) to find modules with DSC Resources:

# To list all modules that tagged as DSCResourceKit
Find-Module -Tag DSCResourceKit
# To list all DSC resources from all sources
Find-DscResource

Please note only those modules released by the PowerShell Team are currently considered part of the ‘DSC Resource Kit’ regardless of the presence of the ‘DSC Resource Kit’ tag in the PowerShell Gallery.

To find a specific module, go directly to its URL on the PowerShell Gallery:
http://www.powershellgallery.com/packages/< module name >
For example:
http://www.powershellgallery.com/packages/xWebAdministration

How to Install DSC Resource Modules From the PowerShell Gallery

We recommend that you use PowerShellGet to install DSC resource modules:

Install-Module -Name

For example:

Install-Module -Name xWebAdministration

To update all previously installed modules at once, open an elevated PowerShell prompt and use this command:

Update-Module

After installing modules, you can discover all DSC resources available to your local system with this command:

Get-DscResource

How to Find DSC Resource Modules on GitHub

All resource modules in the DSC Resource Kit are available open-source on GitHub.
You can see the most recent state of a resource module by visiting its GitHub page at:
https://github.com/PowerShell/< module name >
For example, for the CertificateDsc module, go to:
https://github.com/PowerShell/CertificateDsc.

All DSC modules are also listed as submodules of the DscResources repository in the DscResources folder and the xDscResources folder.

How to Contribute

You are more than welcome to contribute to the development of the DSC Resource Kit! There are several different ways you can help. You can create new DSC resources or modules, add test automation, improve documentation, fix existing issues, or open new ones.
See our contributing guide for more info on how to become a DSC Resource Kit contributor.

If you would like to help, please take a look at the list of open issues for the DscResources repository.
You can also check issues for specific resource modules by going to:
https://github.com/PowerShell/< module name >/issues
For example:
https://github.com/PowerShell/xPSDesiredStateConfiguration/issues

Your help in developing the DSC Resource Kit is invaluable to us!

Questions, comments?

If you’re looking into using PowerShell DSC, have questions or issues with a current resource, or would like a new resource, let us know in the comments below, on Twitter (@PowerShell_Team), or by creating an issue on GitHub.

Katie Kragenbrink
Software Engineer
PowerShell DSC Team
@katiedsc (Twitter)
@kwirkykat (GitHub)

The post DSC Resource Kit Release June 2019 appeared first on PowerShell.