> pshdo

Carbon 2.0.0 Released

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'.
  • 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].
  • 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.

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.
  • 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.
  • 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.
  • All IIS functions were re-written to use the Microsoft.Web.Administration API instead of appcmd.exe.
  • 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.
  • 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.
  • 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.
  • 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.
  • 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.
  • Compress-Item 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.
  • Install-Msi didn’t properly detect when installation failed.
  • Install-ScheduledTask 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.
  • 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.
  • 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.
  • 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.
  • 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
  • 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.
  • 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.
  • Clear-MofAuthoringMetadata 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.
  • ConvertTo-SecurityIdentifer converts a binary, string, or System.Security.Principal.SecurityIdentifier object into a System.Security.Principal.SecurityIdentifier object.
  • Get-DscError 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.
  • Get-FileSharePermission 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.
  • Get-Group gets a local group or all local groups.
  • Get-Msi 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.
  • Get-User 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.
  • Remove-GroupMember 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.
  • Start-DscPullConfiguration 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.
  • Test-Group checks if a local group exists.
  • Test-FileShare 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.
  • Uninstall-FileShare 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.
  • Carbon_FirewallRule configures firewall rules.
  • Carbon_IniFile manages the contents of INI files.
  • Carbon_Permission configures file, directory, registry, and certificate permissions.
  • Carbon_Privilege configures an identity’s privileges.
  • Carbon_ScheduledTask configures scheduled tasks with schtasks.exe.
  • 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.
  • Grant-Permission: System.Security.AccessControl.AccessRule, representing the granted permission.
  • Install-Group: System.DirectoryServices.AccountManagement.GroupPrincipal, representing the group.
  • Install-IisApplication: Microsoft.Web.Administration.Application, representing the application.
  • Install-IisWebsite: Microsoft.Web.Administration.Site, representing the website.
  • Install-Junction: System.IO.DirectoryInfo, representing new target directories and any new/updated junctions.
  • Install-Service: System.ServiceProcess.ServiceController, representing the service.
  • Install-User: System.DirectoryServices.AccountManagement.UserPrincipal, 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.
  • 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.
  • 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.
  • Install-Msi's Quiet switch. Install-Msi always installs in quiet mode. Please remove usages.
  • Install-Service's Password parameter. Use the new Credential parameter instead.
  • Install-User's UserName and Password parameters. Use the new Credential 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.
  • 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.
  • 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.
  • Install-Group's Members parameter renamed to Member (with backwards-compatible alias).
  • Added Credential parameter to Install-IisAppPool 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.
  • 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.
  • 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.
  • Added SID parameter to Resolve-IdentityName 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.
  • 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'.
  • Test-OSIs32Bit now uses the Environment class’s new Is64BitOperatingSystem property.
  • Test-OSIs64Bit now uses the Environment class’s new Is64BitOperatingSystem property.
  • Test-PowerShellIs32Bit now uses the Environment class’s new Is64BitProcess property.
  • Test-PowerShellIs64Bit now uses the Environment 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.
  • 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!
  • Created a new Carbon_ScheduledTask 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
  • 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.
  • Carbon’s System.ServiceProcess.ServiceController extended type data causes errors when PowerShell formats System.ServiceProcess.ServiceController objects that represent services on remote computers.
  • Install-Msi didn’t properly detect when installation failed.
  • Set-EnvironmentVariable fails to set process-level environment variable.
  • Compress-Item 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

  • 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.
  • Created Uninstall-Junction for uninstalling a junction in an idempotent way (i.e. without errors). Thanks to Konstantin Ushenin for the contribution.
  • Improved error handling in Remove-Junction.
  • Install-Service:
    • Now supports service startup parameters/arguments.
    • No longer returns ServiceController objects by default. This should improve backwards-compatability. Added a PassThru switch you can use to get a ServiceController object returned to you.
    • Improved error handling. It now uses net helpmsg to get helpful error messages based on sc.exe exit codes.
    • Improved handling of arguments/services with spaces in them under PowerShell 5.
    • Added Credential parameter for increased security and to follow PowerShell guidelines.
    • Now supports setting a service’s description and display name.
    • 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.
  • New Test-TypeDataMember for testing if a type has an extended type member defined.
  • Install-IisAppPool no longer returns appcmd.exe output.
  • Added PassThru parameter to Install-IisAppPool to control when a Microsoft.Web.Administration.ApplicationPool for the installed app pool is returned.
  • Get-ServiceConfiguration and Carbon’s extended type data for System.ServiceProcess.ServiceController objects now supports services from remote computers.
  • 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.
  • 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.
  • Grant-Permission now only returns an access rule object when the new PassThru switch is used. In previous 2.0 alpha releases, it only returned something when permissions on an object were added or changed.
  • Install-User only returns a user object when the new PassThru switch is used. In previous 2.0 alpha releases, it only returned an object if a user was created or updated.
  • Grant-ComPermissions only returns an access rule object when the new PassThru switch is used. In previous 2.0 alpha releases, it only returned an object if permissions were changed.
  • Install-IisApplication only returns an IIS application object when the new PassThru switch is used. In previous 2.0 alpha releases, it only returned an object if the application was created or modified.
  • Created Get-Msi function for reading MSI information and properties from an MSI file.
  • Carbon.Computer.ProgramInstallInfo objects (returned from Get-ProgramInstallInfo) 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.
  • Invoke-WindowsInstaller renamed Install-Msi, with a backwards-compatibility-preserving alias.
  • Install-Msi now supports wildcards for MSI path to install.
  • Install-Msi 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.
  • Added SiteID parameter to Install-IisWebsite for setting a website’s IIS ID.
  • Put the Resolve-IdentityName function back. It was removed from previous alpha releases.
  • Install-IisWebsite no longer deletes and re-creates websites. This may or may not be a breaking change in your environment.
  • Install-SmbShare no longer returns net.exe output, instead writing it to the verbose stream. To see previous output, use the -Verbose switch.
  • Changed -PasswordNeverExpires switch to PasswordExpires on Install-User for improved backwards-compatability.
  • Set-SslCertificateBinding no longer returns binding objects by default. Use new PassThru switch to get the old behavior.
  • 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 using Chocolatey.
  • Added AsSecureString switch to Unprotect-String which causes Unprotect-String to return a secure string instead of a normal string.
  • Unprotect-String now accepts a SecureString as the value for the Password parameter, which is the password for the private key used to decrypt from password-protected RSA certificate file.
  • Added Credential parameter to Install-IisAppPool for increased security and to follow PowerShell guidelines.
  • Added Credential parameter to Install-User for increased security and to follow PowerShell guidelines.
  • Install-IisVirtualDirectory now modifies existing virtual directories in place, instead of deleting and re-creating.
  • Invoke-AppCmd is now obsolete and will be removed from a future version of Carbon. Switch to Carbon’s IIS functions, or use Get-IisConfigurationSection to get ConfigurationElement objects from the Microsoft.Web.Administration API that you can modify.
  • Added Description and DisplayName properties to Carbon_Service for setting a service’s description and display name.
  • 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.
  • Resolve-Identity now converts SIDs to a Carbon.Identity object. The SID may be a string (SID in SDDL form), byte array, or a SecurityIdentifier object.
  • Get-FileSharePermission gets the sharing permissions on a file/SMB share (not the NTFS file system permissions).
  • Created Get-FileShare function. It uses WMI to get Win32_Share objects for the file shares installed on the local computer.
  • Renamed Install-SmbShare to Install-FileShare, with a backwards-compatible alias in place.
  • Added SID parameter to Resolve-IdentityName to resolve a SID into its identity name.
  • Created ConvertTo-SecurityIdentifer function to convert a binary, string, or System.Security.Principal.SecurityIdentifier object into a System.Security.Principal.SecurityIdentifier object.
  • Install-FileShare (fka Install-SmbShare):
    • Re-written to use WMI isntead of net.exe.
    • 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.
  • Carbon_FirewallRule now fails with an error if it finds multiple firewall rules with the same name.
  • Set-RegistryKeyValue:
  • Uninstall-Service no longer returns sc.exe stdout.

Carbon 1.9.0 Released

Carbon 1.9 is out and is backwards compatible with 1.0 through 1.8. It supports PowerShell 2 and 3.

Download from Bitbucket.

This is the last minor release for version 1.0. Future 1.0-compatible releases will only contain bug fixes, no new features. It takes too much time to maintain two versions, and I’d rather spend my time getting 2.0 out the door. Carbon 2.0 will require PowerShell 4.0, so start planning.

Enhancements

Certificates

  • Added KeyStorageFlags parameter to Get-Certificate when loading a certificate from a file for better control when storing the certificate.

Hosts File

  • Set-HostsEntry now handles writing to an in-use/locked hosts file, retrying up to 10 times before writing an error, waiting a random amount of time (from 0 to 1000 milliseconds) between each retry attempt.

IIS

Scheduled Tasks

  • Created Get-ScheduledTask function for getting the scheduled tasks on the local computer using schtasks.exe.
  • Created Install-ScheduledTask function for installing a scheduled task using schtasks.exe.
  • Created Test-ScheduledTask function for testing if a scheduled tasks on the local computer exists using schtasks.exe.
  • Created Uninstall-ScheduledTask function for deleting a scheduled task using schtasks.exe.

Services

  • Install-Service now supports setting a command to run when a service fails.

Bug Fixes

General

  • Import-Carbon fails when -WhatIf switch is used.
  • Importing Carbon no longer writes an error if the PATH environment variable contains a path to a non-existent drive (issue #134).

INI

  • Set-IniEntry fails when adding the first section-less setting to a file.

Internet Explorer

Security

  • Fixed an error that occurs when setting permissions on a private key fails: the error message is created using an invalid format string (issue #133).
  • Fixed an exception that gets thrown when setting a private key’s permissions and the only certificate key is AT_SIGNATURE (issue #132).

Services

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

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

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.

Carbon 1.8 Released

Carbon 1.8 is out and is backwards compatible with 1.0 through 1.7. It supports PowerShell 2 and 3. Highlights include:

Get the bits at BitBucket.

Enhancements

General

Certificates

  • Improving error handling when Get-Certificate fails to load a certificate from a file.
  • Install-Certificate now supports installing with an X509Certificate2 object instead of just a path to a certificate.
  • Remove-SslCertificateBinding: improved error handling.
  • Set-SslCertificateBinding: improved error handling.
  • Improved documentation for Get-Certificate.
  • Added extended script property StoreName to X509Store objects to return the store’s System.Security.Cryptography.X509Certificates.StoreName value.
  • Added a table view/format for X509Store objects. PowerShell’s default view is a list, so you’ll have to explicitly format the objects as a table, e.g. dir cert:\LocalMachine | Format-Table.
  • Get-Certificate’s Path parameter now supports wildcards and certificate provider paths, e.g. cert:\.
  • Get-Certificate now writes an error if a certificate isn’t found when getting a certificate by its path.

Computer

Cryptography

  • Protect-String can now encrypt strings as a specific user. Use the Credential parameter.
  • Created New-RsaKeyPair for creating public/private RSA key pair using makecert.exe and pkv2pfx.exe. Requires that you’ve installed a Windows SDK.
  • Protect-String can now encrypt strings using an RSA public key.
  • Unprotect-String can now decrypt strings using an RSA private key.

File System

  • Disable-NtfsCompression: improved error handling.
  • Enable-NtfsCompression: improved error handling.
  • Created Compress-Item function for compressing files/directories into a ZIP file.
  • Created Test-ZipFile function for testing if a file is a ZIP file.
  • Created Expand-Item function for decompressing a ZIP file.
  • New-TempDirectory now supports adding a prefix to the temporary directory’s name, so you can more easily track down those scripts/processes that don’t clean up after themselves.

Firewall

  • Disable-FirewallStatefulFtp: improved error handling.
  • Added Name and LiteralName parameters to Get-FirewallRule to return specific rules instead of all of them.
  • Get-FirewallRule, now returns Carbon.Firewall.Rule objects, instead of anonymous hashes.
  • Added default table format for Get-FirewallRule output.
  • Get-FirewallRule now returns additional rule information: interface type, security, source, description, program, and service. Who knew netsh advfirewall firewall rule show had a verbose switch? RTFM.

INI

MSI

Security

  • Creating Revoke-Permission function for revoking a user’s permission to a file, directory, registry key, or certificate’s private key/key container.
  • Creating ConvertTo-ContainerInheritanceFlags function for converting System.Security.AccessControl.InheritanceFlags and System.Security.AccessControl.PropagationFlag values into a Carbon.Security.ContainerInheritanceFlags value.
  • Get-Permission now supports returning the permissions on private keys/key containers.
  • Grant-Permission now supports granting permissions on private keys//key containers.
  • Test-Permission now supports testing permissions on certificate private keys/key containers.

Services

  • Created Get-ServiceConfiguration function for loading a service’s configuration: description, account name/username, failure actions, etc.
  • Added the following extended type data to System.ServiceController.Service:
    • Description
    • ErrorControl
    • FailureProgram
    • FirstFailure
    • LoadOrderGroup
    • Path
    • RebootDelay
    • RebootDelayMinutes
    • RebootMessage
    • ResetPeriod
    • ResetPeriodDays
    • RestartDelay
    • RestartDelayMinutes
    • SecondFailure
    • StartMode
    • StartType
    • TagID
    • ThirdFailure
    • UserName

Bug Fixes

General

  • Importing Carbon gives an error if PATH environment variable contains an empty path.
  • Improved the error handling in the following functions so they properly catch exceptions and write friendlier errors:

Certificates

  • Get-Certificate couldn’t open CA/CertificateAuthority store (fixes issue #130).
  • Extended script property DisplayName on X509Store objects returning wrong store name for custom stores, now returns an empty string.

File System

Path

Users and Groups

  • The Carbon.Identity.FindByName method and the Resolve-IdentityName and Test-Identity functions now handle identity names with . for the domain/machine name, e.g. .\Administrator.
  • The Carbon.Identity.FullName property returns the wrong value when domain is empty/null, e.g. Resolve-IdentityName -Name 'Everyone' returns \Everyone, when it should return Everyone.
  • The Carbon.Identity.FindByName method and the Resolve-IdentityName and Test-Identity functions unable to resolve LocalSystem account (which is actually NT AUTHORITY\SYSTEM).