externalLibs/Carbon/Carbon/about_Carbon.help.txt
|
NAME
Carbon SYNOPSIS Carbon is a PowerShell module for automating the configuration of computers running Windows 2008, 2008 RS and 7. DESCRIPTION Carbon can configure and manage: * Local users and groups * IIS websites, virtual directories, and applications * Certificates * .NET connection strings and app settings * Junctions * File system permissions * Hosts file * INI files * Performance counters * Services * Shares * Windows features/components * And much more! All functions are designed to be idempotent: you should be able to run the same function with the same arguments and get the same result, without any failures. You'll notice Carbon uses the Install and Set PowerShell verb a lot, instead of New/Update. It wants to be clear that it handles cases where something new needs to be created and that same thing may already exist and needs to get updates. Carbon uses semantic versioning for its version numbering (see http://semver.org/). Carbon version numbers take the form X.Y.Z: X is the major version, Y is the minor version, and Z is the patch version. The patch version is incremented when backwards-compatible bug fixes are made. You should feel comforable rolling out a new patch version quickly, with limited testing. The minor version is incremented when new, backwards-compatible changes are introduced, or existing functions are deprecated. You'll probably want to review the changelog and test those bits that changed since the last release. The major version is incremented when backwards-incompatible changes are made. In this case, you'll need to do thorough testing, and upgrade your scripts to use new functionality. Only PowerShell approvated verbs are used in function names. Our canonical source for verbs and their meaning comes from Appendix J: Standard PowerShell Verbs from "PowerShell Cookbook, Second Edition" by Lee Holmes. Additionally, these verbs have the following meaning in Carbon: * Assert: Test a condition, writing an error or failing if it isn't met (e.g Assert-AdminPrivileges). * Format: Escape (e.g. Format-ADSearchFilterValue). * Install: Create if it doesn't exist. If it does exist, reset it to a given state. (E.g. Install-User, Install-IisWebsite, etc.) * Invoke: Run an external command-line application (e.g. Invoke-AppCmd, Invoke-WindowsInstaller). * Split: Parse (e.g. Split-Ini) * Test: Check a condition or for existence (e.g. Test-IisWebsite, Test-SslCertificateBinding, Test-PathIsJunction). As much as possible, Carbon uses existing Windows command line utilties that ship by default with Windows 2008, 2008 R2 and 7. No additional features/components are necessare to use Carbon. When command line tools aren't available, Carbon uses .NET. If .NET doesn't expose needed APIs, it uses P/Invoke to talk to the Win32 APIs. SYSTEM REQUIREMENTS PowerShell v2.0 and .NET Framework v3.5 or PowerShell v3.0 and .NET Framework v4.5 Windows 2008 (x64), Windows 2008 R2 (x64) and Windows 7 (x64). INSTALLATION Download the latest release from https://bitbucket.org/splatteredbits/carbon/downloads. Unblock the zip file (right-click the .zip file, choose Properties, click "Unblock", then click "OK".) Unzip the Carbon module anywhere on your file system. Import the module by running: > Path\To\Carbon\Directory\Import-Carbon.ps1 Replace "Path\To\Carbon\Directory" with the actual path where you unzipped Carbon. If you don't want to worry about remembering/finding the path to Carbon, and just want to run: > Import-Module Carbon Unzip Carbon into one of the following directories: * $PSHOME\Modules\Carbon * %USERPROFILE%\Documents\WindowsPowerShell\Modules\Carbon USAGE If you've installed Carbon into a standard PowerShell module directory (see above), importing it is easy: > Import-Module Carbon If you've got it installed somewhere else, maybe your application's version control repository, you'll need to know the path to where it is. We recommend always using relative paths to create the full path to Carbon. You can get the directory in which the current script is executing, and use that to get the path to Carbon, like this: $PSScriptRoot = Split-Path -Parent -Path $MyInvocation.MyCommand.Definition & (Join-Path $PSScriptRoot ..\Tools\Carbon\Import-Carbon.ps1 -Resolve) FUNCTIONS To get a list of functions, import Carbon, then run `Get-Command`: .\Tools\Carbon\Import-Carbon.ps1 Get-Command -Module Carbon TYPES Carbon augments the following .NET objects with some helpful properties: * Diagnostics.Process: ParentProcessID, the process ID of a process's parent (i.e. the process which started a process) * ServiceProcess.ServiceController: StartMode, the ServiceProcess.ServiceStartModel value for a service. * ServiceProcess.ServiceController: UserName, the name of the account a service runs as. * IO.DirectoryInfo: IsJunction, a boolean indicating if the directory is a junction/reparse point. * IO.DirectoryInfo: TargetPath, if the directory is a junction/reparse point, the path of the junction's target (i.e. where it points to). Otherwise, null. * Security.Cryptography.X509Certificates.X509Certificate2: IssuedTo and IssuedBy, to expose properties which match what you see in the Certificates MMC. * Security.Cryptography.X509Certificates.X509Store: DisplayName, to expose a property which matches the Certificate MMC store names. DEVELOPMENT/CONTRIBUTING We welcome your feedback and contributions! Carbon covers a lot of areas. Functions that work with common things are grouped into .ps1 files in the module's root directory, e.g. ActiveDirectory, IIS, Security, etc. All functions in a file should be ordered alphabetically. We belive in Test-Driven Development (TDD)! If you don't, you won't be happy contributing. Anything you want to submit back to the project must have good tests. If not, it will take longer to accept your contribution, because we'll have to take time to write tests. TDD enables us to release new versions of Carbon as soon changes are committed, pushed, and the tests pass. If the code is ready and works, we want to release it. No waiting! Pest is our testing framework. It uses NUnit-inspired assertions, e.g. Assert-True, Assert-Equal, etc. See http://bitbucket.org/splatteredbits/pest for more information. Tests should always clean-up after themselves and strive to leave an operating system in the exact state it was in before the test fixture ran. Unfortunately, we only have the resources to run our tests on a 64-bit Windows 2008 and 7 computer. Any donations to the project would be used to purchase licenses and hosting for running our tests on 32-bit and 64-bit versions of Windows 7, Windows 2008, and Windows 2008 R2 (and maybe even Windows 8 and Windows "8" Server someday). STYLE GUIDE We use spaces for indenting. Each level of indent (i.e. "tab") should be four spaces. Use camel-casing for all function names, including abbreviations three letters or longer, e.g. Install-Msmq, Install-IisWebsite. Capitalize all letters in one or two letter abbreviations, e.g. Test-PSIs32Bit. All function parameter and module variables names must be capitalized, e.g. $Path, $Name, etc. All variable names internal to functions should be lowercased, e.g. $result, $csprojXml. Variables that contain a path should end in `Path`, e.g. $csprojPath, $websitePath. Use the following parameter names whenever possible: * $ComputerName: for a server/computer host name * $Name: for the name of something. * $Path: for one or more paths Use a prefix for all functions that manage a common area of Windows, e.g. Iis for all IIS-related functions, Msmq for MSMQ-related functions, etc. All functions must have synopsis, description, and example documentation. RELATED LINKS: Carbon's website: https://bitbucket.org/splatteredbits/carbon Developer's Website: http://pshdo.com Pest: https://bitbucket.org/splatteredbits/pest |