Overview

Our first public alpha release of Carbon 2.0 is out (version 2.0-alpha.26).  The focus of version 2.0 is on making necessary, backwards-incompatible changes and adding DSC resources and functions.  We still have some backwards-incompatible changes to make.  before we get to the final version of 2.0. 

Download from BitBucket. 

The highlight of this release are seven new DSC resources:

and these DSC-related functions:

Enjoy! 

Upgrade Instructions

This is a backwards-incompatible release. 

Upgrade to PowerShell 4. ( PowerShell 3 might work.  We don’t know because we don’t have any computers available to test on.) 

Remove usages of Complete-Job .  We removed it because it was total crap.  Use PowerShell’s Wait-Job cmdlet instead. 

.  We removed it because it was total crap.  Use PowerShell’s cmdlet instead.  Grant-Permission now only grants permissions on an object if those permissions aren’t present.  To preserve previous behaviour, add the -Force switch to all Grant-Permission usages. 

switch to all usages.  The following commands now return objects to the pipeline.  Depending on your usage, you may need to pipe their output to Out-Null , assign their return values to $null , or do nothing.  Grant-Permission Install-Group Install-Junction Install-User Grant-ComPermissions Install-Service

, assign their return values to , or do nothing.  The following commands no longer return the stdout from various console applications.  To see that output, use the -Verbose switch.  Remove any usage of the output you were processing.  Disable-FirewallStatefulFtp Enable-FirewallStatefulFtp Remove-SslCertificateBinding

switch.  Remove any usage of the output you were processing.  Set-SslCertificateBinding now returns Carbon. Certificates. SslCertificateBinding objects instead of netsh output.  Update any code that uses the old Set-SslCertificateBinding output. 

objects instead of netsh output.  Update any code that uses the old output.  Ensure that all thumbprints passed to Set-SslCertificateBinding are valid (40 character hex strings). 

Add the new -PasswordNeverExpires switch to usages of Install-User: it no longer sets the PasswordNeverExpires flag for a user by default. 

switch to usages of Install-User: it no longer sets the flag for a user by default.  Use the FullName property on objects returned by Resolve-Identity (nAce Resolve-IdentityName ): it now returns a Carbon. Identity object instead of the identity’s name, e.g. Resolve-Identity -Name $userName | Select-Object -Expand 'FullName' . 

property on objects returned by Resolve-Identity (nAce ): it now returns a object instead of the identity’s name, e.g. .  Add -ErrorAction SilentlyContinue or -ErrorAction Ignore to usages of Resolve-Identity (nAce Resolve-IdentityName ): it now writes an error if it can’t resolve a name. 

or to usages of Resolve-Identity (nAce ): it now writes an error if it can’t resolve a name.  Use the Sid property on objects returned by Test-Identity when using the PassThru switch: it now returns a Carbon. Identity object if the identity exists and you use the -PassThru switch, e.g. Test-Identity -Name $userName -PassThru | Select-Object -Expand 'Sid' . 

property on objects returned by Test-Identity when using the switch: it now returns a object if the identity exists and you use the switch, e.g. .  Check that all IP addresses passed to Set-HostsEntry are valid IP v4 or v6 addresses.  Set-HostsEntry’s IPAddress parameter is now a System. Net. IPAddress object.  Previously it was a string validated with a regular expression, so you should be OK. 

object.  Previously it was a string validated with a regular expression, so you should be OK.  Remove the Exportable switch from any usages of Install-Certificate when installing from an X509Certificate2 object, since that switch only gets used when installing a certificate from a file. 

switch from any usages of Install-Certificate when installing from an object, since that switch only gets used when installing a certificate from a file.  Rename usages of [Carbon. AdvApi32] class to [Carbon. Service. ServiceSecurity] . 

class to .  Rename usages of [Carbon. Lsa] class to [Carbon. Security. Privilege] . 

class to .  Rename usages of [Carbon. Win32] class to [Carbon. FileSystem. Path] . 

class to .  Rename usages of [Carbon. HandleInfo] class to [Carbon. Win32.HandleInfo] . 

class to .  Remove usages of [Carbon. Lsa]::LookupPrivilegeValue class method.  It was incorrectly exposed as a public method. 

class method.  It was incorrectly exposed as a public method.  Remove usages of [Carbon. Kernel32]::LocalFree class method.  It was incorrectly exposed as a public method. 

Enhancements

Certificates

Remove-SslCertificateBinding now writes messages with Write-Verbose instead of Write-Host .  Improved error handling. 

instead of .  Improved error handling.  Set-SslCertificateBinding now returns Carbon. Certificates. SslCertificateBinding object for the binding instead of netsh output.  Improved error handling.  Writes messages with Write-Verbose instead of Write-Host .  Thumbprints are now validated. 

object for the binding instead of output.  Improved error handling.  Writes messages with instead of .  Thumbprints are now validated.  The Exportable switch is now only allowed by Install-Certificate when installing a certificate from a file.  Previously, you could supply the switch when installing from an X509Certificate2 object but it was ignored. 

COM

Grant-ComPermission now returns a Carbon. Security. ComAccessRule .  Also, it now writes messages with Write-Verbose instead of Write-Host . 

.  Also, it now writes messages with instead of .  Revoke-ComPermission now writes messages with Write-Verbose instead of Write-Host . 

Computer

Changed Test-OSIs32Bit and Test-OSIs64Bit functions to use the Environment class’s new Is64BitOperatingSystem property. 

DSC

Created Carbon_EnvironmentVariable resource for creating/removing machine-level environment variables. 

New Clear-DscLocalResourceCache function for clearing the local LCM’s DSC resource.  This makes developing resources easier. 

Created Carbon_IniFile resource for managing settings in INI files. 

Created Carbon_FirewallRule resource for configuring firewall rules. 

New Test-DscTargetResource function for comparing target/desired resource states across DSC resources. 

Created Carbon_Privilege resource for configuring and identity’s privileges. 

Created Carbon_Permission resource for configuring file, directory, registry, and certificate permissions. 

Created Carbon_Service resource for configuring Windows services. 

Created Carbon_Script resource for running custom PowerShell scripts, with support for passing arguments. 

Created Copy-DscResource function for copying DSC resources (ZIP files, MSI archives, MOF files, etc.),  including timestamps, checksums, and copying only changed files. 

Created Clear-MofAuthoringMetadata function for removing authoring metadata from .mof files. 

Created Get-DscWinEvent function for getting DSC events written to a computer’s DSC event log. 

Created Get-DscError function for getting any DSC errors written to a computer’s DSC event log. 

Created Write-DscError function for writing DSC ErrorLogRecord objects as errors. 

objects as errors.  Created Start-DscPullConfiguration function for starting a configuration check on a computer whose computer is configured to use the PULL refresh mode. 

Created Initialize-Lcm function for configuring the DSC Local Configuration Manager on computers, including installing the private key needed for decrypting credentials. 

File System

Disable-NtfsCompression now writes messages with Write-Verbose instead of Write-Host .  Improved error handling. 

instead of .  Improved error handling.  Enable-NtfsCompression now writes messages with Write-Verbose instead of Write-Host .  Improved error handling. 

instead of .  Improved error handling.  Install-Junction now returns System. IO.DirectoryInfo objects for any new target directories and any new/updated junctions. 

Firewall

Disable-FirewallStatefulFtp no longer returns netsh output.  Use the -Verbose switch to see the output. 

output.  Use the switch to see the output.  Enable-FirewallStatefulFtp no longer returns netsh output.  Use the -Verbose switch to see the output. 

Hosts File

Set-HostsEntry’s IPAddress parameter is now a System. Net. IPAddress object.  Previously it was a string validated with a regular expression. 

PowerShell

Changed Test-PowerShellIs32Bit and Test-PowerShellIs64Bit functions to use the Environment class’s new Is64BitProcess property. 

Removed Complete-Job function.  It was total crap. 

function.  It was total crap.  Created Get-PowerShellModuleInstallPath function for getting the path where new module’s should be installed.  Beginning with PowerShell 4, modules should get installed into $env:ProgramFiles\Windows PowerShell\Modules .  Under PowerShell 3, it is $PSHome\Modules .  This function returns the correct location for the version of PowerShell you’re using. 

Security

Grant-Permission now only grants permissions on an object if those permissions aren’t present.  To preserve previous behaviour, add the -Force switch to all Grant-Permission usages. 

switch to all usages.  Grant-Permission returns System. Security. AccessControl. FileSystemRule or System. Security. AccessControl. RegistryRule whenever it updates an item’s permissions.  It no longer writes a message to the host. 

Service

Install-Service now writes messages with Write-Verbose instead of Write-Host . 

instead of .  Install-Service now returns a System. ServiceProcess. ServiceController object when installation/configuration is successful. 

Users and Groups