Carbon 2.0.0 is out. You can download Carbon as a .ZIP archive, NuGet package, Chocolatey package, or from the PowerShell Gallery. It may take a week or two for the package to show up at chocolatey.org.

Overview

Carbon version 2.0 is a huge release, with lots of new enhancements and bug fixes. We hope you like them. Carbon 2.0 now requires PowerShell 4, so it is not backwards-compatabile with Carbon 1.x. Because of this, we made some additional backwards-incompatible changes. See the Upgrade Instructions section for things to look out for.

If you’re upgrading from a previous 2.0 alpha release, you’ll want to review the changes since your alpha version (found after the Upgrade Instructions section). We improved backwards-compatability with Carbon 1.x since the last alpha release, but that broke compatability with the alphas.

Upgrade Instructions

Make sure you’re running PowerShell 4.

Install-Certificate ’s parameters have changed:

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.

Some functions now return different objects and/or the objects returned have changed:

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 when using the switch: it now returns a object if the identity exists and you use the switch, e.g. . Update usages of Carbon.Computer.ProgramInstallInfo ’s Version property (returned by Get-ProgramInstallInfo ). It was an int and is now a Version object.

The Carbon assembly was re-organized. If you were reaching into Carbon.dll (NOT RECOMMENDED), you’ll want to:

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.

The following commands no longer return the stdout output from the console applications each one calls. To see the old output, use the -Verbose switch. Remove any usage of the output you were processing.

All IIS functions.

Disable-FirewallStatefulFtp

Enable-FirewallStatefulFtp

Install-Service

Install-SmbShare

Remove-SslCertificateBinding

Set-SslCertificateBinding

Uninstall-Service

The following functions' internal behavior has changed. This may or may not impact you.

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

now only grants permissions on an object if those permissions aren’t present. To preserve previous behavior, add the switch to all usages. Grant-Permission now writes an error if you don’t have access to a private key. Previously, it would skip the key without any messages.

now writes an error if you don’t have access to a private key. Previously, it would skip the key without any messages. Install-Msi (fka Invoke-WindowsInstaller ) now only installs the MSI if it isn’t already installed. To preserve the previous behavior and always install, add the -Force switch to all Invoke-WindowsInstaller `Install-Msi` usages.

(fka ) now only installs the MSI if it isn’t already installed. To preserve the previous behavior and always install, add the switch to all `Install-Msi` usages. All IIS functions were re-written to use the Microsoft.Web.Administration API instead of appcmd.exe .

API instead of . Install-IisWebsite no longer deletes and re-creates websites. If a website exists, it updates its configuration to match parameters passed in. To preserve previous behavior and delete the website before installing, use the -Force switch.

no longer deletes and re-creates websites. If a website exists, it updates its configuration to match parameters passed in. To preserve previous behavior and delete the website before installing, use the switch. Install-IisVirtualDirectory no longer deletes and re-creates virtual directories. If a virtual directory exists, its configuration is updated in place. To preserve previous behavior and delete the virtual directory before installing, use the Force switch.

no longer deletes and re-creates virtual directories. If a virtual directory exists, its configuration is updated in place. To preserve previous behavior and delete the virtual directory before installing, use the switch. Install-FileShare (fka Install-SmbShare ) no longer deletes and re-creates the share, instead it modifies existing shares in place. To preserve previous behavior and delete existing shares before re-creating, use the Force switch.

(fka ) no longer deletes and re-creates the share, instead it modifies existing shares in place. To preserve previous behavior and delete existing shares before re-creating, use the switch. Set-RegistryKeyValue only sets the value if the value doesn’t exist or the current value is different than the desired value.

We’ve added parameter validation to some functions. This shouldn’t impact anybody, since if you were passing data that breaks this new validation, the function wouldn’t have worked even in previous versions of Carbon.

Ensure that all thumbprints passed to Set-SslCertificateBinding are valid (40 character hex strings), since it now validates thumbprints.

are valid (40 character hex strings), since it now validates thumbprints. 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.

All Carbon functions now respect each caller’s common parameters (e.g. -Verbose , -ErrorAction , etc.). This means if you pass a common parameter to a script that calls a Carbon function, that Carbon function will use that common parameter. This may or may not impact you.

Bug Fixes

Carbon’s System.ServiceProcess.ServiceController extended type data causes errors when PowerShell formats System.ServiceProcess.ServiceController objects that represent services on remote computers.

extended type data causes errors when PowerShell formats objects that represent services on remote computers. Compress-Item doesn’t remove handled errors from global error array.

doesn’t remove handled errors from global error array. Grant-Permission fails with an unhelpful error message if it is unable to get the ACL on a private key.

fails with an unhelpful error message if it is unable to get the ACL on a private key. Install-Msi didn’t properly detect when installation failed.

didn’t properly detect when installation failed. Install-ScheduledTask fails under PowerShell 5 to create a scheduled task to run on Sunday.

fails under PowerShell 5 to create a scheduled task to run on Sunday. Install-Service : No longer writes a warning about being unable to stop an already stopped service (fixes issue #158). Starting the service now respects caller’s error action preference. Before, Start-Service would write an error even if somone called Install-Service with an Ignore or SilentlyContinue error action preference. Service arguments that are quoted still get quoted. Now, quotes are trimmed before arguments are quoted.

: Set-EnvironmentVariable fails to set process-level environment variable.

fails to set process-level environment variable. Set-HostsEntry fails to preserve whitespace if existing lines end with a comment/description. Thanks to Konstantin Ushenin for the fix.

Enhancements

General

Carbon now requires PowerShell 4.

Import-Carbon.ps1 is more intelligent about when it tries to re-load Carbon. It will force a re-import of Carbon if any of Carbon’s files have changed or the version has changed.

is more intelligent about when it tries to re-load Carbon. It will force a re-import of Carbon if any of Carbon’s files have changed or the version has changed. Added new FileIndex , LinkCount , and VolumeSerialNumber extended type data on System.IO.FileInfo objects for getting a file’s index, its hard link count, and volume serial number, respectively.

, , and extended type data on objects for getting a file’s index, its hard link count, and volume serial number, respectively. The product version of the Carbon assembly now includes pre-release version information, as defined by the Semantic Versioning specification. To get this version, run Get-Item Carbon.dll | Select-Object -ExpandProperty 'VersionInfo' | Select-Object -ExpandProperty 'ProductVersion' .

. The Carbon NuGet package now supports installing and uninstalling under Chocolatey.

All IIS functions were re-written to use the Microsoft.Web.Administration API instead of appcmd.exe . As a side effect, they no longer return appcmd.exe console output.

API instead of . As a side effect, they no longer return console output. The following functions no longer use Write-Host . Instead, they use Write-Verbose : Disable-NtfsCompression Enable-NtfsCompression Grant-ComPermission Grant-Permission Install-Service Remove-SslCertificateBinding Revoke-ComPermission

. Instead, they use : Created default, table-based display formats for System.DirectoryServices.AccountManagement.UserPrincipal , System.DirectoryServices.AccountManagement.GroupPrincipal , Microsoft.Web.Administration.ApplicationPool , Microsoft.Web.Administration.Site , and Microsoft.Web.Administration.Application objects.

, , , , and objects. Re-organized Carbon’s internal directory structure. You shouldn’t be reaching into Carbon’s internals, so this shouldn’t matter, but wanted to let everyone know just in case.

New Functions

Clear-DscLocalResourceCache clears the local LCM’s DSC resource. This makes developing resources easier.

clears the local LCM’s DSC resource. This makes developing resources easier. Clear-MofAuthoringMetadata removes authoring metadata from .mof files.

removes authoring metadata from .mof files. Copy-DscResource copies DSC resources (ZIP files, MSI archives, MOF files, etc.), including timestamps, checksums, and copying only changed files.

copies DSC resources (ZIP files, MSI archives, MOF files, etc.), including timestamps, checksums, and copying only changed files. ConvertTo-SecurityIdentifer converts a binary, string, or System.Security.Principal.SecurityIdentifier object into a System.Security.Principal.SecurityIdentifier object.

converts a binary, string, or object into a object. Get-DscError gets any DSC errors that were written to a computer’s DSC event log.

gets any DSC errors that were written to a computer’s DSC event log. Get-DscWinEvent gets DSC events that were written to a computer’s DSC event log.

gets DSC events that were written to a computer’s DSC event log. Get-FileSharePermission gets the sharing permissions on a file/SMB share (not the NTFS file system permissions).

gets the sharing permissions on a file/SMB share (not the NTFS file system permissions). Get-FileShare uses WMI to get Win32_Share objects for the file shares installed on the local computer.

uses WMI to get objects for the file shares installed on the local computer. Get-Group gets a local group or all local groups.

gets a local group or all local groups. Get-Msi reads installer information and properties from an MSI file.

reads installer information and properties from an MSI file. Get-PowerShellModuleInstallPath gets 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.

gets the path where new module’s should be installed. Beginning with PowerShell 4, modules should get installed into . Under PowerShell 3, it is . This function returns the correct location for the version of PowerShell you’re using. Get-User gets a local user or all local users.

gets a local user or all local users. Initialize-Lcm configures the DSC Local Configuration Manager on computers, including installing the private key needed for decrypting credentials.

configures the DSC Local Configuration Manager on computers, including installing the private key needed for decrypting credentials. Remove-GroupMember removes a user/group from a local group. Thanks to Philip Kluss for the contribution.

removes a user/group from a local group. Thanks to Philip Kluss for the contribution. Resolve-Identity converts a system, local, or domain principal name or a SID (as a SecurityIdentifer , string SDDL, or byte array) into its canonical representation and includes extended identity information: domain, type, and SID.

converts a system, local, or domain principal name or a SID (as a , string SDDL, or byte array) into its canonical representation and includes extended identity information: domain, type, and SID. Start-DscPullConfiguration starts a configuration check on a computer that is configured to use the PULL refresh mode.

starts a configuration check on a computer that is configured to use the PULL refresh mode. Test-DscTargetResource compares target resource with desired resource. Helpful when writing Test-TargetResource functions.

compares target resource with desired resource. Helpful when writing functions. Test-Group checks if a local group exists.

checks if a local group exists. Test-FileShare uses WMI to check if a file/SMB share exists on the local computer.

uses WMI to check if a file/SMB share exists on the local computer. Test-TypeDataMember tests if a type has an extended type member defined.

tests if a type has an extended type member defined. Uninstall-FileShare uninstalls/removes a file share, if it exists.

uninstalls/removes a file share, if it exists. Write-DscError writes DSC ErrorLogRecord objects as errors.

New DSC Resources

Carbon_EnvironmentVariable creates/removes machine-level environment variables.

creates/removes machine-level environment variables. Carbon_FirewallRule configures firewall rules.

configures firewall rules. Carbon_IniFile manages the contents of INI files.

manages the contents of INI files. Carbon_Permission configures file, directory, registry, and certificate permissions.

configures file, directory, registry, and certificate permissions. Carbon_Privilege configures an identity’s privileges.

configures an identity’s privileges. Carbon_ScheduledTask configures scheduled tasks with schtasks.exe .

configures scheduled tasks with . Carbon_Service configures Windows services.

Added PassThru Switches

Added a PassThru switch to the following functions, which will return objects of the given type:

Grant-ComPermission : Carbon.Security.ComAccessRule , representing the granted permission.

: , representing the granted permission. Grant-Permission : System.Security.AccessControl.AccessRule , representing the granted permission.

: , representing the granted permission. Install-Group : System.DirectoryServices.AccountManagement.GroupPrincipal , representing the group.

: , representing the group. Install-IisApplication : Microsoft.Web.Administration.Application , representing the application.

: , representing the application. Install-IisWebsite : Microsoft.Web.Administration.Site , representing the website.

: , representing the website. Install-Junction : System.IO.DirectoryInfo , representing new target directories and any new/updated junctions.

: , representing new target directories and any new/updated junctions. Install-Service : System.ServiceProcess.ServiceController , representing the service.

: , representing the service. Install-User : System.DirectoryServices.AccountManagement.UserPrincipal , representing the user.

: , representing the user. Set-SslCertificateBinding : Carbon.Certificates.SslCertificateBinding , representing the configured binding.

No More Console Output

The following functions no longer return the console output of the program each one runs. Instead, the output is written to the verbose stream (i.e. use the -Verbose switch to see it).

Disable-FirewallStatefulFtp

Enable-FirewallStatefulFtp

Install-Service

Remove-SslCertificateBinding

Set-SslCertificateBinding

Uninstall-Service

Obsolete Functions and Parameters

The following functions are now obsolete. Please don’t use them and stop using them if you are. They will be removed from a future major version of Carbon. You’ll get warnings if you use them.

Complete-Job : It’s total crap. Use PowerShell’s Wait-Job cmdlet instead.

: It’s total crap. Use PowerShell’s cmdlet instead. Invoke-AppCmd : Switch to Carbon’s IIS functions, or use Get-IisConfigurationSection to get ConfigurationElement objects from the Microsoft.Web.Administration API that you can modify.

: Switch to Carbon’s IIS functions, or use to get objects from the API that you can modify. Resolve-NetPath : Switch to something else. Carbon doesn’t use net.exe anymore.

The following functions now have obsolete parameters, which will be removed from a future major version of Carbon. You’ll get warnings if you use them.

Install-IisAppPool's UserName and Password parameters. Use the new Credential parameter instead.

and parameters. Use the new parameter instead. Install-Msi's Quiet switch. Install-Msi always installs in quiet mode. Please remove usages.

switch. always installs in quiet mode. Please remove usages. Install-Service's Password parameter. Use the new Credential parameter instead.

parameter. Use the new parameter instead. Install-User's UserName and Password parameters. Use the new Credential parameter instead.

and parameters. Use the new parameter instead. Set-RegistryKeyValue ’s Quiet parameter. Please remove usages.

Renamed Functions

The following functions were renamed, but with backwards-compatible aliases in place, so you shouldn’t have to change any code.

Invoke-WindowsInstaller -> Install-Msi

-> Install-SmbShare -> Install-FileShare

Switch to System.DirectoryServices.AccountManagement API for User/Group Management

The following functions were re-written to use the System.DirectoryServices.AccountManagement API, introduced in .NET 3.5.

Add-MemberToGroup

Install-Group

Install-User

Test-User

Uninstall-User

Miscellaneous Changes

Get-IisAppPool Now return all application pools installed on the local computer when called with no parameters. Added a default table format for Microsoft.Web.Administration.ApplicationPool objects.

Get-ProgramInstallInfo Return object’s Version property changed from an int to a Version object. Return object’s now have ProductCode and User properties. If a program doesn’t have a product code, it is set to [Guid]::Empty . The User property is only set for per-user software installs.

Get-ServiceConfiguration now supports services from remote computers.

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

now only grants permissions on an object if those permissions aren’t present. To preserve previous behavior, add the switch to all usages. Install-Certificate's Exportable switch is now only allowed when installing a certificate from a file. Previously, you could supply the switch when installing from an X509Certificate2 object but it was ignored.

switch is now only allowed when installing a certificate from a file. Previously, you could supply the switch when installing from an X509Certificate2 object but it was ignored. Install-Group's Members parameter renamed to Member (with backwards-compatible alias).

parameter renamed to (with backwards-compatible alias). Added Credential parameter to Install-IisAppPool for increased security and to follow PowerShell guidelines.

parameter to for increased security and to follow PowerShell guidelines. Install-IisVirtualDirectory no longer deletes and re-creates existing virtual directories, but modifies existing virtual directories in place.

no longer deletes and re-creates existing virtual directories, but modifies existing virtual directories in place. Install-IisWebsite Added SiteID parameter tfor setting a website’s IIS ID. No longer deletes and re-creates websites, but modifies existing websites in place. This may or may not be a breaking change in your environment.

Install-Msi Path parameter now supports wildcards. Now only installs an MSI if it isn’t already installed. To preserve the previous behavior and always install, add the -Force switch to all Invoke-WindowsInstaller `Install-Msi` usages.

Install-Service Now supports service startup parameters/arguments via the ArgumentList parameter. Improved error handling and messages. It now uses net helpmsg to get helpful error messages based on sc.exe exit codes. Added Credential parameter for increased security and to follow PowerShell guidelines. Added Description parameter for setting a service’s description. Added DisplayName parameter for setting a service’s display name.

Install-FileShare (fka Install-SmbShare ): Re-written to use WMI isntead of net.exe , so it no longer returns any console output. Modifies existing shares in place, instead of deleting and re-creating, unless the share’s path changes. Changing a share’s path requires the old share to be deleted and a new one created.

(fka ): Install-User Added PasswordExpires switch for creating accounts with passwords that expire. Added UserCannotChangePassword to prevent user from changing his password.

Remove-SslCertificateBinding has better error handling.

has better error handling. Added SID parameter to Resolve-IdentityName to resolve a SID into its identity name.

parameter to to resolve a SID into its identity name. Set-HostsEntry's IPAddress parameter is now a System.Net.IPAddress object. It used to be a string validated with a regular expression.

parameter is now a object. It used to be a string validated with a regular expression. Set-RegistryKeyValue : Added UDWord and UQWord parameters for setting registry key values to unsigned integers (i.e. integer values greater than [int]::MaxValue and [long]::MaxValue ). Fixes issue #165: Set-RegistryKeyValue rejects unsigned integers larger than [int]::MaxValue. Deprecated Quiet switch. Only sets the value if the value doesn’t exist or the current value is different than the desired value. Use the Force parameter to preserve previous 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 SID. Update scripts to use the FullName property to get the old return value, e.g. Test-Identity -Name $userName -PassThru | Select-Object -Expand 'FullName' .

now returns a object if the identity exists and you use the switch. It used to return the identity’s SID. Update scripts to use the property to get the old return value, e.g. . Test-OSIs32Bit now uses the Environment class’s new Is64BitOperatingSystem property.

now uses the Environment class’s new Is64BitOperatingSystem property. Test-OSIs64Bit now uses the Environment class’s new Is64BitOperatingSystem property.

now uses the Environment class’s new Is64BitOperatingSystem property. Test-PowerShellIs32Bit now uses the Environment class’s new Is64BitProcess property.

now uses the class’s new Is64BitProcess property. Test-PowerShellIs64Bit now uses the Environment class’s new Is64BitProcess property.

now uses the class’s new Is64BitProcess property. Uninstall-ScheduledTask now retries when un-installing a task fails with “The function attempted to use a name that is reserved for use by another transaction.” error.

now retries when un-installing a task fails with “The function attempted to use a name that is reserved for use by another transaction.” error. Unprotect-String Added AsSecureString switch, which will return a secure string instead of a normal string. The Password parameter now accepts SecureString values.

Initialize-Lcm Added support for PowerShell 5: RefreshIntervalMinutes default value changed to from 15 to 30; RefreshIntervalMinutes minimum value is now 30; ConfigurationFrequency ’s minimum value is now 1 (from 2).



Changes Since alpha.26

Enhancements

Includes all changes made in version 1.9.0.

PowerShell 4 is now required. Carbon won’t even import under PowerShell 3.

Removed Carbon_Script resource. It only existed so I could pass values to my script blocks. Turns out, the built-in Script resource supports this with the $using: scope. Remember, your most important features is documentation!

resource. It only existed so I could pass values to my script blocks. Turns out, the built-in resource supports this with the scope. Remember, your most important features is documentation! Created a new Carbon_ScheduledTask DSC resource for managing scheduled tasks.

DSC resource for managing scheduled tasks. The Version property on the objects returned by Get-ProgramInstallInfo is now a proper .NET Version object instead of an integer.

Bug Fixes

Carbon_Permission DSC resource fails when assigning multiple permissions

DSC resource fails when assigning multiple permissions Grant-Permission fails when clearing multiple existing, non-inherited permission on an item.

Changes Since alpha.31

Bug Fixes

Set-HostsEntry fails to preserve whitespace if existing lines end with a comment/description. Thanks to Konstantin Ushenin for the fix.

fails to preserve whitespace if existing lines end with a comment/description. Thanks to Konstantin Ushenin for the fix. Carbon’s System.ServiceProcess.ServiceController extended type data causes errors when PowerShell formats System.ServiceProcess.ServiceController objects that represent services on remote computers.

extended type data causes errors when PowerShell formats objects that represent services on remote computers. Install-Msi didn’t properly detect when installation failed.

didn’t properly detect when installation failed. Set-EnvironmentVariable fails to set process-level environment variable.

fails to set process-level environment variable. Compress-Item doesn’t remove handled errors from global error array.

doesn’t remove handled errors from global error array. Grant-Permission fails with an unhelpful error message if it is unable to get the ACL on a private key.

Enhancements