Carbon/en-US/about_Carbon_2.0.help.txt
|
TOPIC
about_Carbon_2.0 SHORT DESCRIPTION Describes changes included in Carbon 2.0. LONG DESCRIPTION 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. UPGRADE INSTRUCTIONS Make sure you're running PowerShell 4. `Install-CCertificate`'s parameters have changed: * Remove the `Exportable` switch from any usages of `Install-CCertificate` 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-CIdentity` 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-CIdentity -Name $userName -PassThru | Select-Object -Expand 'Sid'`. * Update usages of `Carbon.Computer.ProgramInstallInfo`'s `Version` property (returned by `Get-CProgramInstallInfo`). It was an `int` and is now a [Version](http://msdn.microsoft.com/en-us/library/y0hf9t2e.aspx) 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-CFirewallStatefulFtp` * `Enable-CFirewallStatefulFtp` * `Install-CService` * `Install-SmbShare` * `Remove-CSslCertificateBinding` * `Set-CSslCertificateBinding` The following functions' internal behavior has changed. This may or may not impact you. * `Grant-CPermission` now only grants permissions on an object if those permissions aren't present. To preserve previous behavior, add the `-Force` switch to all `Grant-CPermission` usages. * `Grant-CPermission` now writes an error if you don't have access to a private key. Previously, it would skip the key without any messages. * `Install-CMsi` (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-CMsi` usages. * All IIS functions were re-written to use the `Microsoft.Web.Administration` API instead of `appcmd.exe`. * `Install-CIisWebsite` 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-CIisVirtualDirectory` 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-CFileShare` (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-CSslCertificateBinding` are valid (40 character hex strings), since it now validates thumbprints. * Check that all IP addresses passed to `Set-CHostsEntry` are valid IP v4 or v6 addresses. `Set-CHostsEntry`'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. 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-CItem` doesn't remove handled errors from global error array. * `Grant-CPermission` fails with an unhelpful error message if it is unable to get the ACL on a private key. * `Install-CMsi` didn't properly detect when installation failed. * `Install-CScheduledTask` fails under PowerShell 5 to create a scheduled task to run on Sunday. * `Install-CService`: * 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-CService-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-CService` with an `Ignore` or `SilentlyContinue` error action preference. * `Set-CEnvironmentVariable` fails to set process-level environment variable. * `Set-CHostsEntry` fails to preserve whitespace if existing lines end with a comment/description. Thanks to [Konstantin Ushenin](https://vk.com/kostanew) for the fix. GENERAL EHANCEMENTS * 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 '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-CNtfsCompression` * `Enable-CNtfsCompression` * `Grant-CComPermission` * `Grant-CPermission` * `Install-CService` * `Remove-CSslCertificateBinding` * `Revoke-CComPermission` * 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. NEW FUNCTIONS * `Clear-CDscLocalResourceCache` clears the local LCM's DSC resource. This makes developing resources easier. * `Clear-CMofAuthoringMetadata` removes authoring metadata from .mof files. * `Copy-CDscResource` 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-CDscError` gets any DSC errors that were written to a computer's DSC event log. * `Get-CDscWinEvent` gets DSC events that were written to a computer's DSC event log. * `Get-CFileSharePermission` gets the sharing permissions on a file/SMB share (*not* the NTFS file system permissions). * `Get-CFileShare` uses WMI to get `Win32_Share` objects for the file shares installed on the local computer. * `Get-CGroup` gets a local group or all local groups. * `Get-CMsi` reads installer information and properties from an MSI file. * `Get-CPowerShellModuleInstallPath` 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-CUser` gets a local user or all local users. * `Initialize-CLcm` configures the DSC Local Configuration Manager on computers, including installing the private key needed for decrypting credentials. * `Remove-CGroupMember` removes a user/group from a local group. Thanks to [Philip Kluss](https://bitbucket.org/philkloose) for the contribution. * `Resolve-CIdentity` 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-CDscPullConfiguration` starts a configuration check on a computer that is configured to use the PULL refresh mode. * `Test-CDscTargetResource` compares target resource with desired resource. Helpful when writing `Test-TargetResource` functions. * `Test-CGroup` checks if a *local* group exists. * `Test-CFileShare` uses WMI to check if a file/SMB share exists on the local computer. * `Test-CTypeDataMember` tests if a type has an extended type member defined. * `Uninstall-CFileShare` uninstalls/removes a file share, if it exists. * `Write-CDscError` 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-CComPermission`: `Carbon.Security.ComAccessRule`, representing the granted permission. * `Grant-CPermission`: `System.Security.AccessControl.AccessRule`, representing the granted permission. * `Install-CGroup`: `System.DirectoryServices.AccountManagement.GroupPrincipal`, representing the group. * `Install-CIisApplication`: `Microsoft.Web.Administration.Application`, representing the application. * `Install-CIisWebsite`: `Microsoft.Web.Administration.Site`, representing the website. * `Install-CJunction`: `System.IO.DirectoryInfo`, representing new target directories and any new/updated junctions. * `Install-CService`: `System.ServiceProcess.ServiceController`, representing the service. * `Install-CUser`: `System.DirectoryServices.AccountManagement.UserPrincipal`, representing the user. * `Set-CSslCertificateBinding`: `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-CFirewallStatefulFtp` * `Enable-CFirewallStatefulFtp` * `Install-CService` * `Remove-CSslCertificateBinding` * `Set-CSslCertificateBinding` 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-CJob`: It's total crap. Use PowerShell's `Wait-Job` cmdlet instead. * `Invoke-CAppCmd`: Switch to Carbon's IIS functions, or use `Get-CIisConfigurationSection` to get `ConfigurationElement` objects from the `Microsoft.Web.Administration` API that you can modify. * `Resolve-CNetPath`: 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-CIisAppPool's` `UserName` and `Password` parameters. Use the new `Credential` parameter instead. * `Install-CMsi's` `Quiet` switch. `Install-CMsi` always installs in quiet mode. Please remove usages. * `Install-CService's` `Password` parameter. Use the new `Credential` parameter instead. * `Install-CUser'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-CMsi` * `Install-SmbShare` -> `Install-CFileShare` 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-CGroupMember` * `Install-CGroup` * `Install-CUser` * `Test-CUser` * `Uninstall-CUser` MISCELLANEOUS CHANGES * `Get-CIisAppPool` * 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-CProgramInstallInfo` * 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-CServiceConfiguration` now supports services from remote computers. * `Grant-CPermission` now only grants permissions on an object if those permissions aren't present. To preserve previous behavior, add the `-Force` switch to all `Grant-CPermission` usages. * `Install-CCertificate'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-CGroup's` `Members` parameter renamed to `Member` (with backwards-compatible alias). * Added `Credential` parameter to `Install-CIisAppPool` for increased security and to follow PowerShell guidelines. * `Install-CIisVirtualDirectory` no longer deletes and re-creates existing virtual directories, but modifies existing virtual directories in place. * `Install-CIisWebsite` * 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-CMsi` * `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-CMsi` usages. * `Install-CService` * 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-CFileShare` (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-CUser` * Added `PasswordExpires` switch for creating accounts with passwords that expire. * Added `UserCannotChangePassword` to prevent user from changing his password. * `Remove-CSslCertificateBinding` has better error handling. * Added `SID` parameter to `Resolve-CIdentityName` to resolve a SID into its identity name. * `Set-CHostsEntry's` `IPAddress` parameter is now a `System.Net.IPAddress` object. It used to be a string validated with a regular expression. * `Test-CIdentity` 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-CIdentity -Name $userName -PassThru | Select-Object -Expand 'FullName'`. * `Test-COSIs32Bit` now uses the Environment class's new [Is64BitOperatingSystem](http://msdn.microsoft.com/en-us/library/system.environment.is64bitoperatingsystem.aspx) property. * `Test-COSIs64Bit` now uses the Environment class's new [Is64BitOperatingSystem](http://msdn.microsoft.com/en-us/library/system.environment.is64bitoperatingsystem.aspx) property. * `Test-CPowerShellIs32Bit` now uses the `Environment` class's new [Is64BitProcess](http://msdn.microsoft.com/en-us/library/system.environment.is64bitprocess.aspx) property. * `Test-CPowerShellIs64Bit` now uses the `Environment` class's new [Is64BitProcess](http://msdn.microsoft.com/en-us/library/system.environment.is64bitprocess.aspx) property. * `Uninstall-CScheduledTask` 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-CString` * Added `AsSecureString` switch, which will return a secure string instead of a normal string. * The `Password` parameter now accepts `SecureString` values. * `Initialize-CLcm` * 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). |