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:
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:
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'.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:
[Carbon.AdvApi32] class to [Carbon.Service.ServiceSecurity].[Carbon.Lsa] class to [Carbon.Security.Privilege].[Carbon.Win32] class to [Carbon.FileSystem.Path].[Carbon.HandleInfo] class to [Carbon.Win32.HandleInfo].[Carbon.Lsa]::LookupPrivilegeValue class method. It was
incorrectly exposed as a public method.[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.
The following functions' internal behavior has changed. This may or may not impact you.
-Force
switch to all Grant-Permission usages.-Force switch to all Invoke-WindowsInstaller[Install-Msi](Install-Msi.html) usages.Microsoft.Web.Administration API
instead of appcmd.exe.-Force
switch.Force switch.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.
System.Net.IPAddress object. Previously it was a string validated with a
regular expression, so you should be OK.System.ServiceProcess.ServiceController extended type data causes
errors when PowerShell formats System.ServiceProcess.ServiceController objects
that represent services on remote computers.Start-Service would write an error even if somone called Install-Service
with an Ignore or SilentlyContinue error action preference.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.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.Get-Item Carbon.dll |
Select-Object -ExpandProperty 'VersionInfo' | Select-Object -ExpandProperty
'ProductVersion'.Microsoft.Web.Administration API
instead of appcmd.exe. As a side effect, they no longer return appcmd.exe
console output.Write-Host. Instead, they use
Write-Verbose:
System.DirectoryServices.AccountManagement.UserPrincipal,
System.DirectoryServices.AccountManagement.GroupPrincipal,
Microsoft.Web.Administration.ApplicationPool,
Microsoft.Web.Administration.Site, and
Microsoft.Web.Administration.Application objects.ConvertTo-SecurityIdentifer converts a binary, string, or
System.Security.Principal.SecurityIdentifier object into a
System.Security.Principal.SecurityIdentifier object.Win32_Share objects for the file shares
installed on the local computer.$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.SecurityIdentifer, string SDDL, or byte array) into its canonical
representation and includes extended identity information: domain, type, and SID.Test-TargetResource functions.ErrorLogRecord objects as errors.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 a PassThru switch to the following functions, which will return objects of
the given type:
Carbon.Security.ComAccessRule, representing the granted
permission.System.Security.AccessControl.AccessRule, representing the
granted permission.System.DirectoryServices.AccountManagement.GroupPrincipal,
representing the group. Microsoft.Web.Administration.Application,
representing the application.Microsoft.Web.Administration.Site, representing the
website.System.IO.DirectoryInfo, representing new target
directories and any new/updated junctions.System.ServiceProcess.ServiceController, representing the
service.System.DirectoryServices.AccountManagement.UserPrincipal,
representing the user.Carbon.Certificates.SslCertificateBinding,
representing the configured binding.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).
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.
Wait-Job cmdlet instead.ConfigurationElement objects from the
Microsoft.Web.Administration API that you can modify.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.The following functions were renamed, but with backwards-compatible aliases in place, so you shouldn't have to change any code.
The following functions were re-written to use the
System.DirectoryServices.AccountManagement API, introduced in .NET 3.5.
Microsoft.Web.Administration.ApplicationPool objects.Version property changed from an int to a
Version object.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.-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).Credential parameter to Install-IisAppPool for increased security and
to follow PowerShell guidelines.SiteID parameter tfor setting a website's IIS ID.Path parameter now supports wildcards.-Force switch to all
Invoke-WindowsInstaller[Install-Msi](Install-Msi.html) usages.ArgumentList
parameter.net helpmsg to get
helpful error messages based on sc.exe exit codes.Credential parameter for increased security and to follow PowerShell
guidelines.Description parameter for setting a service's description.DisplayName parameter for setting a service's display name.net.exe, so it no longer returns any
console output.PasswordExpires switch for creating accounts with passwords that
expire.UserCannotChangePassword to prevent user from changing his password.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.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'.Environment class's new
Is64BitProcess property.Environment class's new
Is64BitProcess property.AsSecureString switch, which will return a secure string instead of a
normal string.Password parameter now accepts SecureString values.RefreshIntervalMinutes default value
changed to from 15 to 30; RefreshIntervalMinutes minimum value is now 30;
ConfigurationFrequency's minimum value is now 1 (from 2).