About Help

Choose a topic from the list on the left or search for a specific topic. Choose a topic from the list or search for a specific topic.
Cmdlets  Providers  Aliases  Modules
 

about_Carbon_2.0

Carbon_2.0

Carbon
 

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-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](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-FirewallStatefulFtp` 
     * `Enable-FirewallStatefulFtp` 
     * `Install-Service` 
     * `Install-SmbShare` 
     * `Remove-SslCertificateBinding` 
     * `Set-SslCertificateBinding` 
     
    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. 
     
    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. 
     
     

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](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  
       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-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. 
      

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](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  
       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` 
      

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. 
     

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](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  
       `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. 
     * `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  
       [Is64BitOperatingSystem](http://msdn.microsoft.com/en-us/library/system.environment.is64bitoperatingsystem.aspx) property. 
     * `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  
       [Is64BitProcess](http://msdn.microsoft.com/en-us/library/system.environment.is64bitprocess.aspx) 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).