DOCSEARCHbyAlgolia
Submit Docs

Carbon PowerShell Module

repository·main·Indexed 43 days ago

https://github.com/webmd-health-services/carbon

A PowerShell module for automating the configuration and setup of Windows workstations and servers. It provides a framework for managing system states, administrative tasks, and includes Desired State Configuration (DSC) resources for environment variables, firewall rules, services, and permissions. Version 2.0 requires PowerShell 4 and introduces updated function naming conventions with a 'C' prefix.

Tokens
7.3K
Snippets
21
Records
47
Agent score
50%

What's inside Carbon

  1. Overview of Carbon capabilities

    main

    Carbon is a PowerShell module designed to automate the configuration and management of Windows computers (Windows 7, 8, 2008, and 2012). It provides idempotent functions to manage various system resources, including:

    • Users & Groups: Local users and groups.
    • IIS: Websites, virtual directories, and applications.
    • Permissions: File system, registry, and certificate permissions.
    • System Resources: Services, Privileges, Certificates, Encryption, Junctions, Hosts file, INI files, Performance counters, and Shares.
    • Application Config: .NET connection strings and app settings.

    Note on IIS: To use IIS-related functions, IIS must be installed/enabled, including the Web-Scripting-Tools feature.

  2. Overview of Carbon PowerShell module

    main
    Carbon is a PowerShell module designed for automating the configuration and setup of Windows workstations and servers. It provides a framework for managing system states and automating repetitive administrative tasks on Windows environments.

  3. What is Silk and how does it work?

    main

    Silk is a PowerShell module designed to publish a PowerShell module's help topics as a website.

    It automates the conversion of help documentation into a navigable HTML site by:

    1. Creating an individual HTML page for every function in the target module.
    2. Using the module's main 'about' topic (e.g., about_Silk) as the site's index page.
    3. Converting additional 'about' topics into navigation elements for the website.

    Advanced control over the publishing process is managed through a JSON manifest file.

  4. Handle errors and assertion failures in Blade

    main

    Understanding how Blade determines test success:

    • Test Failure: Occurs if an assertion fails (throws a Blade.AssertionException) or if the test encounters a terminating error.
    • Test Success: Occurs in all other cases.
    • Write-Error Behavior: If your code or the test uses Write-Error, the test will still pass.
    • Enforcing No Errors: To ensure a test fails if any error is written to the error stream, use the Assert-NoError assertion. Blade automatically clears the $Error variable before each test starts.

  5. Understand Carbon's idempotent command verbs

    main

    Carbon uses standard PowerShell approved verbs but assigns specific semantic meanings to them to ensure idempotency (the ability to run the same command multiple times without changing the result or causing errors once the desired state is reached):

    • Install-*: Creates a resource if it doesn't exist. If the resource already exists, it updates its configuration to match your desired state (e.g., Install-CUser, Install-CIisWebsite).
    • Uninstall-*: Removes a resource if it exists. If the resource does not exist, the command does nothing and does not error.
    • Split-*: Used for parsing (e.g., Split-CIni).
    • Format-*: Used for escaping (e.g., Format-CADSearchFilterValue).

  6. Carbon versioning and upgrade guidance

    main

    Carbon follows semantic versioning (Major.Minor.Patch). Use the following guide when upgrading:

    Change TypeExampleCompatibilityAction Required
    Patch1.5.0 $\rightarrow$ 1.5.1100% Backwards-compatible (bug fixes)Upgrade with no or limited testing.
    Minor1.8.0 $\rightarrow$ 1.9.0100% Backwards-compatible (new features/fixes)Upgrade with light to limited testing. Always upgrade to the highest patch number of a minor version.
    Major1.9.0 $\rightarrow$ 2.0.0Breaking changesCarefully review release notes, update your code, and perform thorough testing.

  7. Use setup and teardown functions in Blade

    main

    Blade provides lifecycle hooks to manage state for your tests. You can implement these at two levels:

    Per-Test Setup/Teardown

    To run code before and after each individual test, define:

    • Start-Test: Runs before each test.
    • Stop-Test: Runs after each test.

    Per-Fixture Setup/Teardown

    To run code once before any tests run and once after all tests have finished, define:

    • Start-TestFixture: Runs once at the very beginning.
    • Stop-TestFixture: Runs once at the very end.
    $tempDir = $null

function Start-TestFixture {
    # Global setup, e.g., importing a module
    & (Join-Path -Path $PSScriptRoot -ChildPath '..\Module\Import-Module.ps1' -Resolve)
}

function Start-Test {
    # Per-test setup
    $tempDir = New-TempDir
}

function Stop-Test {
    # Per-test teardown
    Remove-Item -Path $tempDir -Recurse
}

function Stop-TestFixture {
    # Global teardown
    Remove-Module 'MyModule'
}

function Test-ShouldCreateTempDir {
    Assert-DirectoryExists $tempDir
}

  9. Install Carbon from the PowerShell Gallery

    main

    To install Carbon via the PowerShell Gallery, you must be running PowerShell 5 or PowerShell 4 with the Package Management PowerShell Modules Preview installed.

    Run the following command to install. Note that the -AllowClobber switch is required because Windows 10/2016 includes modules with function names that conflict with Carbon's functions.

    Install-Module -Name 'Carbon' -AllowClobber

    After installation, import the module using:

    Import-Module 'Carbon'

  11. Install Carbon from a ZIP archive

    main

    To install Carbon manually using a ZIP archive:

    1. Download the ZIP file from the GitHub releases page.
    2. Unblock the ZIP file (Right-click the .zip file, select Properties, check Unblock, and click OK).
    3. Unzip the Carbon module to a location on your file system.

    To use Carbon immediately after unzipping, run the provided import script:

    .\Carbon\Import-Carbon.ps1

    To make Carbon available for standard Import-Module Carbon commands, copy the Carbon directory into one of your PowerShell module paths. You can find your module paths by running:

    $env:PSModulePath -split ';'

  12. Preserve legacy behavior with -Force switch

    main

    Several functions have changed their internal logic to be more idempotent or efficient. To maintain previous behavior (e.g., always overwriting or re-installing), add the -Force switch:

    • Grant-CPermission: Now only grants permissions if they aren't already present. Use -Force to ensure permissions are applied.
    • Install-CMsi: Now only installs the MSI if it isn't already installed. Use -Force to always install.
    • Install-CIisWebsite: Now updates existing websites instead of deleting/re-creating them. Use -Force to delete and re-create.
    • Install-CIisVirtualDirectory: Now updates existing virtual directories in place. Use -Force to delete and re-create.
    • Install-CFileShare: Now modifies existing shares in place. Use -Force to delete and re-create.