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