FileContents.adoc

DSC Resource 'FileContents'

FileContents contains DSC resources for managing file content as features by the underlying DSC resource.

Source	https://github.com/dsccommunity/CommonTasks/tree/main/source/DSCResources/FileContents
DSC Resource	FileContentDsc
Documentation	IniSettingsFile KeyValuePairFile ReplaceText

Table 1. Attributes of category 'FileContents'

Parameter	DataType	Description
IniSettingsFiles	hashtable[]	This parameter is used to add, set or clear entries in Windows INI settings files (see IniSettingsFile)
KeyValuePairFile	hashtable[]	The parameter is used to add, remove or set key/value pairs in a text file containing key/value pair entries (see KeyValuePairFile)
ReplaceText	hashtable[]	This parameter is used to replace strings matching a regular expression in a text file (see ReplaceText)

Table 2. Attributes of category 'FileContents/IniSettingsFiles'

Parameter	Attribute	DataType	Description	Allowed Values
Path	Key	String	The path to the INI settings file to set the entry in.
Key	Key	String	The section to add or set the entry in.
Section	Key	String	The section to add or set the entry in.
Type		String	Specifies the value type that contains the value to set the entry to. Defaults to 'Text'.	Text Secret
Text		String	The text to set the entry value to. Only used when Type is set to 'Text'.
Secret		PSCredential	The secret text to set the entry value to. Only used when Type is set to 'Secret'.

Table 3. Attributes of category 'FileContents/KeyValuePairFile'

Parameter	Attribute	DataType	Description	Allowed Values
Path	Key	String	The path to the key value pair text file.
Ensure		String	Specifies the if the key value pair with the specified key should exist in the file.	Present (default) Absent
Type		String	Specifies the value type to use as the replacement string. Defaults to 'Text'.	Text Secret
Text		String	The text to replace the value with in the identified key. Only used when Type is set to 'Text'.
Secret		PSCredential	The secret text to replace the value with in the identified key. Only used when Type is set to 'Secret'.
IgnoreNameCase		Boolean	Ignore the case of the name of the key. Defaults to $False.
IgnoreValueCase		Boolean	Ignore the case of any text or secret when determining if it they need to be updated. Defaults to $False.
Encoding		String	Specifies the file encoding. Defaults to ASCII.	ASCII BigEndianUnicode BigEndianUTF32 UTF8 UTF32

Table 4. Attributes of category 'FileContents/ReplaceText'

Parameter	Attribute	DataType	Description	Allowed Values
Path	Key	String	The path to the text file to replace the string in.
Search	Key	String	The RegEx string to use to search the text file.
Type		String	Specifies the value type to use as the replacement string. Defaults to 'Text'.	Text Secret
Text		String	The text to replace the text identified by the RegEx. Only used when Type is set to 'Text'.
Secret		PSCredential	The secret text to replace the text identified by the RegEx. Only used when Type is set to 'Secret'.
AllowAppend		Boolean	Specifies to append text to the file being modified. Adds the ability to add a configuration entry.
Encoding		String	Specifies the file encoding. Defaults to ASCII.	ASCII BigEndianUnicode BigEndianUTF32 UTF8 UTF32

Example

FileContents:
  IniSettingsFiles:
  - Path: C:\MyApp\MyApp.ini
    Section: Logging
    Key: Level
    Text: Information
  - Path: C:\MyApp\MyApp2.ini
    Section: Database
    Key: ConnectionString
    Type: Secret
    Secret: "[ENC=PE9ianMgVmVyc2lvbj0iMS4xLjAuMSIgeG1sbnM9...=]"

KeyValuePairFiles:
  - Path: C:\MyApp\MyApp.conf
    Name: Core.Logging1
    Ensure: Absent
  - Path: C:\MyApp\MyApp.conf
    Name: Core.Logging2
    Ensure: Present
    Text: Information
  - Path: C:\MyApp\MyApp.conf
    Name: Core.Password
    Ensure: Present
    Type: Secret
    Secret: "[ENC=PE9ianMgVmVyc2lvbj0iMS4xLjAuMSIgeG1sbnM9...=]"

ReplaceTexts:
  - Path: c:\inetpub\wwwroot\default.htm
    Search: "%secret%"
    Type: Secret
    Secret: "[ENC=PE9ianMgVmVyc2lvbj0iMS4xLjAuMSIgeG1sbnM9...=]"
  - Path: c:\inetpub\wwwroot\default.htm
    Search: "%appname%"
    Type: Text
    Text: Awesome App
  - Path: c:\inetpub\wwwroot\default.htm
    Search: <img src=['`\"][a-zA-Z0-9.]*['`\"]>
    Type: Text
    Text: <img src="imgs/placeholder.jpg">

Recommended Lookup Options in Datum.yml (Excerpt)

lookup_options:

  FileContents:
    merge_hash: deep
  FileContents\IniSettingsFiles:
    merge_hash_array: UniqueKeyValTuples
    merge_options:
      tuple_keys:
        - Path
        - Section
        - Key
  FileContents\KeyValuePairFiles:
    merge_hash_array: UniqueKeyValTuples
    merge_options:
      tuple_keys:
        - Path
        - Name
  FileContents\ReplaceTexts:
    merge_hash_array: UniqueKeyValTuples
    merge_options:
      tuple_keys:
        - Path
        - Search