en-US/about_Carbon_2.0.help.txt

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
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-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-GroupMember`
    * `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).