Carbon

Author(s)

• Aaron Jensen

Tags

.net acl active-directory certificates com compression computer credential cryptography directory dsc dsc-resources encryption environment file-system firewall groups hosts-file http identity iis ini installers internet-explorer ip junctions msi msmq netsh networking ntfs operating-system os path performance-counters powershell principal privileges programs registry rsa scheduled-tasks security service shares sid smb ssl text trusted-host users wcf windows windows-features xml zip DscResources setup automation admin

Functions

Add-CGroupMember Add-CIisDefaultDocument Add-CTrustedHost Assert-CAdminPrivilege Assert-CFirewallConfigurable Assert-CService Clear-CDscLocalResourceCache Clear-CMofAuthoringMetadata Clear-CTrustedHost Complete-CJob Compress-CItem ConvertFrom-CBase64 Convert-CSecureStringToString ConvertTo-CBase64 ConvertTo-CContainerInheritanceFlags ConvertTo-CInheritanceFlag ConvertTo-CPropagationFlag ConvertTo-CSecurityIdentifier Convert-CXmlFile Copy-CDscResource Disable-CAclInheritance Disable-CFirewallStatefulFtp Disable-CIEEnhancedSecurityConfiguration Disable-CIisSecurityAuthentication Disable-CNtfsCompression Enable-CAclInheritance Enable-CFirewallStatefulFtp Enable-CIEActivationPermission Enable-CIisDirectoryBrowsing Enable-CIisSecurityAuthentication Enable-CIisSsl Enable-CNtfsCompression Expand-CItem Find-CADUser Format-CADSearchFilterValue Get-CADDomainController Get-CCertificate Get-CCertificateStore Get-CComPermission Get-CComSecurityDescriptor Get-CDscError Get-CDscWinEvent Get-CFileShare Get-CFileSharePermission Get-CFirewallRule Get-CGroup Get-CHttpUrlAcl Get-CIisApplication Get-CIisAppPool Get-CIisConfigurationSection Get-CIisHttpHeader Get-CIisHttpRedirect Get-CIisMimeMap Get-CIisSecurityAuthentication Get-CIisVersion Get-CIisWebsite Get-CIPAddress Get-CMsi Get-CMsmqMessageQueue Get-CMsmqMessageQueuePath Get-CPathProvider Get-CPathToHostsFile Get-CPerformanceCounter Get-CPermission Get-CPowerShellModuleInstallPath Get-CPowershellPath Get-CPrivilege Get-CProgramInstallInfo Get-CRegistryKeyValue Get-CScheduledTask Get-CServiceAcl Get-CServiceConfiguration Get-CServicePermission Get-CServiceSecurityDescriptor Get-CSslCertificateBinding Get-CTrustedHost Get-CUser Get-CWindowsFeature Get-CWmiLocalUserAccount Grant-CComPermission Grant-CHttpUrlPermission Grant-CMsmqMessageQueuePermission Grant-CPermission Grant-CPrivilege Grant-CServiceControlPermission Grant-CServicePermission Initialize-CLcm Install-CCertificate Install-CDirectory Install-CFileShare Install-CGroup Install-CIisApplication Install-CIisAppPool Install-CIisVirtualDirectory Install-CIisWebsite Install-CJunction Install-CMsi Install-CMsmq Install-CMsmqMessageQueue Install-CPerformanceCounter Install-CRegistryKey Install-CScheduledTask Install-CService Install-CUser Install-CWindowsFeature Invoke-CAppCmd Invoke-CPowerShell Join-CIisVirtualPath Lock-CIisConfigurationSection New-CCredential New-CJunction New-CRsaKeyPair New-CTempDirectory Protect-CString Read-CFile Remove-CDotNetAppSetting Remove-CEnvironmentVariable Remove-CGroupMember Remove-CHostsEntry Remove-CIisMimeMap Remove-CIniEntry Remove-CJunction Remove-CRegistryKeyValue Remove-CSslCertificateBinding Reset-CHostsFile Reset-CMsmqQueueManagerID Resolve-CFullPath Resolve-CIdentity Resolve-CIdentityName Resolve-CNetPath Resolve-CPathCase Resolve-CRelativePath Restart-CRemoteService Revoke-CComPermission Revoke-CHttpUrlPermission Revoke-CPermission Revoke-CPrivilege Revoke-CServicePermission Set-CDotNetAppSetting Set-CDotNetConnectionString Set-CEnvironmentVariable Set-CHostsEntry Set-CIisHttpHeader Set-CIisHttpRedirect Set-CIisMimeMap Set-CIisWebsiteID Set-CIisWebsiteSslCertificate Set-CIisWindowsAuthentication Set-CIniEntry Set-CRegistryKeyValue Set-CServiceAcl Set-CSslCertificateBinding Set-CTrustedHost Split-CIni Start-CDscPullConfiguration Test-CAdminPrivilege Test-CDotNet Test-CDscTargetResource Test-CFileShare Test-CFirewallStatefulFtp Test-CGroup Test-CGroupMember Test-CIdentity Test-CIisAppPool Test-CIisConfigurationSection Test-CIisSecurityAuthentication Test-CIisWebsite Test-CIPAddress Test-CMsmqMessageQueue Test-CNtfsCompression Test-COSIs32Bit Test-COSIs64Bit Test-CPathIsJunction Test-CPerformanceCounter Test-CPerformanceCounterCategory Test-CPermission Test-CPowerShellIs32Bit Test-CPowerShellIs64Bit Test-CPrivilege Test-CRegistryKeyValue Test-CScheduledTask Test-CService Test-CSslCertificateBinding Test-CTypeDataMember Test-CUncPath Test-CUser Test-CWindowsFeature Test-CZipFile Uninstall-CCertificate Uninstall-CDirectory Uninstall-CFileShare Uninstall-CGroup Uninstall-CIisAppPool Uninstall-CIisWebsite Uninstall-CJunction Uninstall-CMsmqMessageQueue Uninstall-CPerformanceCounterCategory Uninstall-CScheduledTask Uninstall-CService Uninstall-CUser Uninstall-CWindowsFeature Unlock-CIisConfigurationSection Unprotect-CString Write-CDscError Write-CFile *

DSCResources

Carbon_EnvironmentVariable Carbon_FirewallRule Carbon_Group Carbon_IniFile Carbon_Permission Carbon_Privilege Carbon_ScheduledTask Carbon_Service

Dependencies

This module has no dependencies.

Release Notes

# Naming Collisions Solved (Again)

Fixed: In Carbon 2.7.0, we added a `C` prefix to all the Carbon functions, with aliases that used the old function
names to preserve backwards-compatability. We didn't realize at the time that aliases have the highest precedence of
commands, so Carbon's aliases hid any other commands on your system that may have been named the same. Bad idea. With
this release, Carbon no longer uses aliases for backwards-compatability. Instead, it dynamically creates shim functions
named after the old functions. These shim functions write a warning that the function with the old name is deprecated
then calls the function using its new name. Hopefully, this will finally fix the name collisions problems. The function
names with out the `C` prefix will be removed in Carbon 3, so update your code to make upgrading easier.

Because Carbon creates these backwards-compatible function shims dynamically, Carbon *won't* create a shim if a
function with the old name exists. If there is a name conflict between Carbon and another module, if you import that
module first, Carbon won't export its shim function.

# Carbon on PowerShell Core

We need parts of Carbon to work on PowerShell Core. The current size of Carbon makes that hard (over 200 functions and
automated tests that take a long time). So, we're breaking Carbon into smaller modules. The new modules will all require
PowerShell 5.1+. If you use Carbon 2 and the new modules together, you'll get naming conflicts during installation and
when importing.

The first two modules are already out: Carbon.Core and Carbon.Cryptography.

# Carbon.Core

Carbon.Core will contain all the functions that are foundational to all or most other future Carbon modules, or generic
functions we feel are core to Carbon and/or PowerShell. It has no dependencies. The following functions were migrated to
it:

* `ConvertTo-CBase64` (with some added functionality)
* `Get-CPowerShellPath`
* `Invoke-CPowerShell`
* `Test-COperatingSystem`: Replaces `Test-OSIs32Bit` and `Test-OSIs64Bit`. Tests operating system type, too, so you
can use this function instead of the `$IsWindows`, `$IsLinux`, or `$IsMacOS` variables. Works on versions of PowerShell
that don't define those variables.
* `Test-CPowerShell`: Replaces `Test-PowerShellIs32Bit` and `Test-PowerShellIs64Bit`. Tests edition, too. Use this
function instead of `$PSVersionTable.PSEdition`. Handles when $PSVersionTable doesn't have the PSEdition property.

# Carbon.Cryptography

Carbon.Crytography contains functions that are used when encrypting and decrypting strings. This is where certificate
management funtions live. These function were migrated from Carbon:

* `Convert-CSecureStringToString`
* `Get-CCertificate`: works on Linux and macOS when opening certificate files.
* `Install-CCertificate`
* `Uninstall-CCertificate`
* `Protect-CString`: works on Linux and macOS.
* `Unprotect-CString`: works on Linux and macOS.

# TL;DR Changes

* Fixed: Carbon's backward compatible aliases replaced with shim functions. Carbon no longer aggressively loads its
functions.
* New: Carbon now warns when you're using a function shim with a deprecated name. Update your code so that all Carbon
functions have a `C` prefix. Carbon has a `Use-CarbonPrefix.ps1` script in its bin directory that will update files to
use the new prefix.
* Migrated the following functions to new Carbon.Core and Carbon.Cryptography modules. These functions still exist in
Carbon 2, so if you use all these modules together, you'll probably run into naming collisions and errors depending on
how you install, import, and use Carbon. You'll get a warning if you use any of the functions that migrated.
   * `ConvertTo-CBase64`, `Get-CPowerShellPath`, and `Invoke-CPowerShell` are now in the Carbon.Core module.
   * The `Test-COSIs32Bit` and `Test-COSIs64Bit` functions merged into a `Test-COperatingSystem` function in the
   Carbon.Core module.
   * The `Test-CPowerShellIs32Bit` and `Test-CPowerShellIs64Bit` functions merged into a `Test-CPowerShell` function in
   the Carbon.Core module.
   * New: `Convert-CSecureStringToString`, `Get-CCertificate`, `Install-CCertificate`, `Uninstall-CCertificate`,
   `Protect-CString`, and `Unprotect-CString` migrated to the Carbon.Cryptography module.