Describes changes included in Carbon 2.0.
Carbon version 2.0 is a *huge* release, with lots of new enhancements. 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.
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
* 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
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` The following functions' internal behavior has changed. This may or may not impact
* `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. 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.
* 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](https://bitbucket.org/splatteredbits/carbon/issues/158/install-service-extraneous-warning-about)). * 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.
* `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](https://vk.com/kostanew) for
* 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](http://semver.org). To get this version, run `Get-Item Carbon.dll |
Select-Object -ExpandProperty 'VersionInfo' | Select-Object -ExpandProperty
* The Carbon NuGet package now supports installing and uninstalling under
* 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`
* The following functions no longer use `Write-Host`. Instead, they use
* Created default, table-based display formats for
* `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
* `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](https://bitbucket.org/philkloose) 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 PARAMETERS
Added a `PassThru` switch to the following functions, which will return objects of
the given type:
* `Grant-ComPermission`: `Carbon.Security.ComAccessRule`, representing the granted
* `Grant-Permission`: `System.Security.AccessControl.AccessRule`, representing the
* `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
* `Install-Junction`: `System.IO.DirectoryInfo`, representing new target
directories and any new/updated junctions.
* `Install-Service`: `System.ServiceProcess.ServiceController`, representing the
* `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).
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
* `Install-User's` `UserName` and `Password` parameters. Use the new `Credential` parameter instead. 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.
* Now return all application pools installed on the local computer when called
with no parameters.
* Added a default table format for
* Return object's `Version` property changed from an `int` to a [Version](http://msdn.microsoft.com/en-us/library/y0hf9t2e.aspx) 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
* `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
* 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.
* 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
* Now supports service startup parameters/arguments via the `ArgumentList`
* 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
* 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
* 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.
* Added `PasswordExpires` switch for creating accounts with passwords that
* 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
* `Set-HostsEntry's` `IPAddress` parameter is now a `System.Net.IPAddress` object. It used to be a string validated with a regular expression. * `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](http://msdn.microsoft.com/en-us/library/system.environment.is64bitoperatingsystem.aspx) property. * `Test-OSIs64Bit` now uses the Environment class's new
* `Test-PowerShellIs32Bit` now uses the `Environment` class's new [Is64BitProcess](http://msdn.microsoft.com/en-us/library/system.environment.is64bitprocess.aspx) property. * `Test-PowerShellIs64Bit` now uses the `Environment` class's new
* `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."
* Added `AsSecureString` switch, which will return a secure string instead of a
* The `Password` parameter now accepts `SecureString` values.
* 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).