Carbon 2.0-alpha.26 Released

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.
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.
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.
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.
Set-SslCertificateBinding now returns Carbon.Certificates.SslCertificateBinding objects instead of netsh output. Update any code that uses the old Set-SslCertificateBinding 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.
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'.
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.
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'.
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.
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.
Rename usages of [Carbon.AdvApi32] class to [Carbon.Service.ServiceSecurity].
Rename usages of [Carbon.Lsa] class to [Carbon.Security.Privilege].
Rename usages of [Carbon.Win32] class to [Carbon.FileSystem.Path].
Rename usages of [Carbon.HandleInfo] class to [Carbon.Win32.HandleInfo].
Remove usages of [Carbon.Lsa]::LookupPrivilegeValue 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.
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.
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.
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.
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.
Enable-NtfsCompression now writes messages with Write-Verbose instead of Write-Host. 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.
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.
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.
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.
Install-Service now returns a System.ServiceProcess.ServiceController object when installation/configuration is successful.

Users and Groups

Re-wrote Install-User to use .NET’s System.DirectoryServices.AccountManagement API (introduced with .NET 3.5) instead of the net.exe command-line program.
Added PasswordNeverExpires switch to Install-User for creating accounts with passwords that expire. This is a breaking change: this flag used to set this flag by default.
Added UserCannotChangePassword switch to Install-User to prevent user from changing his password.
Added Get-User function for getting a local user or all local users.
Added Get-Group function for getting a local group or all local groups.
Renamed Install-Group’s Members parameter to Member (with backwards-compatible alias).
Install-Group re-written to use .NET’s System.DirectoryServices.AccountManagement API (introduced with .NET 3.5).
Install-Group now returns the group added or updated.
Add-MemberToGroup re-written to use .NET’s System.DirectoryServices.AccountManagement API (introduced with .NET 3.5).
Resolve-IdentityName now writes an error if it can’t resolve a name. Use -ErrorAction SilentlyContinue or -ErrorAction Ignore to preserve old behavior.
Uninstall-User re-written to use .NET’s System.DirectoryServices.AccountManagement API (introduced with .NET 3.5).
Test-User re-written to use .NET’s System.DirectoryServices.AccountManagement API (introduced with .NET 3.5).
Created Test-Group function for checking if a local group exists.
Resolve-IdentityName renamed to Resolve-Identity, but it has a backwards-compatible alias, so you shouldn’t have to do anything.
Resolve-Identity (nAce Resolve-IdentityName) now returns a Carbon.Identity object instead of the identity’s name. Update scripts to use the FullName property to get the old return value, e.g. Resolve-Identity -Name $userName -PassThru | Select-Object -Expand 'FullName'.
Resolve-Identity (nAce Resolve-IdentityName) now writes an error if it can’t resolve a name. Use -ErrorAction SilentlyContinue or -ErrorAction Ignore to preserve old behavior.
Test-Identity now returns a Carbon.Identity object if the identity exists and you use the -PassThru switch. It used to return the identity’s name. Update scripts to use the FullName property to get the old return value, e.g. Test-Identity -Name $userName -PassThru | Select-Object -Expand 'FullName'.
Added Remove-GroupMember function. Thanks to Philip Kluss for the contribution.