Carbon_IniFile

DSC resource for managing settings in INI files.

Syntax

Carbon_IniFile [String] #ResourceName
{
    Name = [string]
    Path = [string]
    [CaseSensitive = [bool]]
    [DependsOn = [string[]]]
    [Ensure = [string]{ Absent | Present }]
    [Force = [bool]]
    [PsDscRunAsCredential = [PSCredential]]
    [Section = [string]]
    [Value = [string]]
}

Description

The Carbon_IniFile resource sets or removes settings from INI files.

Carbon_IniFile is new in Carbon 2.0.

Related Commands

Parameters

Name	Type	Description	Required?	Pipeline Input	Default Value
Path	String	The path to the file to update.	true	false
Section	String	The section of the INI file where the setting can be found.	false	false
Name	String	The name of the INI setting.	true	false
Value	String	The value of the INI setting.	false	false
CaseSensitive	SwitchParameter	The INI file being modified is case-sensitive.	false	false	False
Force	SwitchParameter	If `$true`, creates the INI file if it doesn't exist.	false	false	False
Ensure	String	Create or delete the INI setting?	false	false	Present

EXAMPLE 1

Demonstrates how to create/set a setting in sectionless INI file.

Carbon_IniFile SetNpmPrefix
{
    Path = 'C:\Program Files\nodejs\node_modules\npm\npmrc'
    Name = 'prefix';
    Value = 'C:\node-global-modules';
    CaseSensitive = $true;
}

In this case, we're setting the prefix NPM setting to C:\node-global-modules in the C:\Program Files\nodejs\node_modules\npm\npmrc file. It is expected this file exists and you'll get an error if it doesn't. NPM configuration files are case-sensitive, so the CaseSensitive property is set to $true.

This line will be added to the INI file:

prefix = C:\node-global-modules

EXAMPLE 2

Demonstrates how to create/set a setting in an INI file with sections.

Carbon_IniFile SetBuildUserMercurialUsername
{
    Path = 'C:\Users\BuildUser\mercurial.ini'
    Section = 'ui';
    Name = 'username';
    Force = $true;
    Value = 'Build User <builduser@example.com>';
}

In this case, we're setting the 'username' setting in the 'ui' section of the C:\Users\BuildUser\mercurial.ini file to Build User <builduser@example.com>. Since the $Force property is $true, if the file doesn't exist, it will be created. These lines will be added to the ini file:

[ui]
username = Build User <builduser@example.com>

EXAMPLE 3

Demonstrates how to remove a setting from a case-sensitive INI file.

Carbon_IniFile RemoveNpmPrefix
{
    Path = 'C:\Program Files\nodejs\node_modules\npm\npmrc'
    Name = 'prefix';
    CaseSensitive = $true;
    Ensure = 'Absent';
}

EXAMPLE 4

Demonstrates how to remove a setting from an INI file that organizes settings into sections.

Carbon_IniFile RemoveBuildUserMercurialUsername
{
    Path = 'C:\Users\BuildUser\mercurial.ini'
    Section = 'ui';
    Name = 'username';
    Ensure = 'Absent';
}