Set-Content
|
Additional Resources for Set-Content |
|
Saving Data to a Text File http://www.microsoft.com/technet/scriptcenter/topics/msh/cmdlets/set-content.mspx
|
SYNOPSIS
Writes or replaces the content in an item with new content.
SYNTAX
Set-Content [-path] <string[]> [-value] <Object[]> [-include <string[]>] [-exclude <string[]>] [-filter <string>] [-passThru] [-force] [-credential <PSCredential>] [-whatIf] [-confirm] [<CommonParameters>]
Set-Content [-literalPath] <string[]> [-value] <Object[]> [-include <string[]>] [-exclude <string[]>] [-filter <string>] [-passThru] [-force] [-credential <PSCredential>] [-whatIf] [-confirm] [<CommonParameters>]
DETAILED DESCRIPTION
The Set-Content cmdlet is a string-processing cmdlet that writes or replaces the content in the specified item, such as a file. Whereas the Add-Content cmdlet appends content to a file, Set-Content replaces the existing content. You can type the content in the command or send content through the pipeline to Set-Content.
PARAMETERS
-path <string[]>
Specifies the path to the item that will receive the content. Wildcards are permitted.
|
Required? |
true |
|
Position? |
1 |
|
Default value |
N/A - The path must be specified |
|
Accept pipeline input? |
true (ByPropertyName) |
|
Accept wildcard characters? |
true |
-include <string[]>
Changes only the specified items. The value of this parameter qualifies the Path parameter. Enter a path element or pattern, such as "*.txt". Wildcards are permitted.
|
Required? |
false |
|
Position? |
named |
|
Default value |
|
|
Accept pipeline input? |
false |
|
Accept wildcard characters? |
true |
-exclude <string[]>
Omits the specified items. The value of this parameter qualifies the Path parameter. Enter a path element or pattern, such as "*.txt". Wildcards are permitted.
|
Required? |
false |
|
Position? |
named |
|
Default value |
|
|
Accept pipeline input? |
false |
|
Accept wildcard characters? |
true |
-filter <string>
Specifies a filter in the provider's format or language. The value of this parameter qualifies the Path parameter. The syntax of the filter, including the use of wildcards, depends on the provider. Filters are more efficient than other parameters, because the provider applies them when retrieving the objects, rather than having Windows PowerShell filter the objects after they are retrieved.
|
Required? |
false |
|
Position? |
named |
|
Default value |
|
|
Accept pipeline input? |
false |
|
Accept wildcard characters? |
false |
-passThru <SwitchParameter>
Passes the object created by this cmdlet through the pipeline. By default, this cmdlet does not pass any objects through the pipeline.
|
Required? |
false |
|
Position? |
named |
|
Default value |
False |
|
Accept pipeline input? |
false |
|
Accept wildcard characters? |
false |
-value <Object[]>
Specifies the new content for the item.
|
Required? |
true |
|
Position? |
2 |
|
Default value |
|
|
Accept pipeline input? |
true (ByValue, ByPropertyName) |
|
Accept wildcard characters? |
true |
-force <SwitchParameter>
Overrides restrictions that prevent the command from succeeding, just so the changes do not compromise security. For example, Force will override the read-only attribute or create directories to complete a file path, but it will not attempt to change file permissions.
|
Required? |
false |
|
Position? |
named |
|
Default value |
False |
|
Accept pipeline input? |
false |
|
Accept wildcard characters? |
false |
-credential <PSCredential>
Uses a credential to validate access to the file. <Credential> represents a user-name, such as "User01" or "Domain01\User01", or a PSCredential object, such as the one retrieved by using the Get-Credential cmdlet. If you type a user name, you will be prompted for a password. This parameter appears, but it is not supported in any Windows PowerShell core cmdlets or providers.
|
Required? |
false |
|
Position? |
named |
|
Default value |
|
|
Accept pipeline input? |
true (ByPropertyName) |
|
Accept wildcard characters? |
false |
-literalPath <string[]>
Specifies the path to the item that will receive the content. Unlike Path, the value of LiteralPath is used exactly as it is typed. No characters are interpreted as wildcards. If the path includes escape characters, enclose it in single quotation marks. Single quotation marks tell Windows PowerShell not to interpret any characters as escape sequences.
|
Required? |
true |
|
Position? |
1 |
|
Default value |
|
|
Accept pipeline input? |
true (ByPropertyName) |
|
Accept wildcard characters? |
false |
-whatIf
Describes what would happen if you executed the command without actually executing the command.
|
Required? |
false |
|
Position? |
named |
|
Default value |
|
|
Accept pipeline input? |
false |
|
Accept wildcard characters? |
false |
-confirm
Prompts you for confirmation before executing the command.
|
Required? |
false |
|
Position? |
named |
|
Default value |
|
|
Accept pipeline input? |
false |
|
Accept wildcard characters? |
false |
<CommonParameters>
This cmdlet supports the common parameters: -Verbose, -Debug, -ErrorAction, -ErrorVariable, and -OutVariable. For more information, type, "get-help about_commonparameters".
INPUT TYPE
String
NOTES
For more information, type "Get-Help Set-Content -detailed". For technical information, type "Get-Help Set-Content -full".
Set-Content is designed for string processing. If you pipe non-string objects to Set-Content, it convert the object to a string before writing it. To write object to files, use Out-File.
When specifying multiple values for a parameter, use commas to separate the values. For example, "<parameter-name> <value1>, <value2>".
You can also refer to Set-Content by its built-in alias, "sc". For more information, see About_Alias.
EXAMPLE 1
set-content -path C:\Test1\test*.txt -value "Hello, World"
This command replaces the contents of all files in the Test1 directory that have names beginning with "test" with "Hello, World." This examples shows how to specify content by typing it in the command.
EXAMPLE 2
get-date | set-content C:\Test1\date.csv
This command creates a comma-separated variable-length (csv) file that contains only the current date and time. It uses the Get-Datecmdlet to get the current system date and time. The pipeline operator passes the result to Set-Content, which creates the file and writes the content.
If the Test1 directory does not exist, the command fails, but if the file does not exist, the command will create it.
EXAMPLE 3
(get-content Notice.txt) | foreach-object {$_ -replace "Warning", "Caution"} | set-content Notice.txt
This command replaces all instances of "Warning" with "Caution" in the Notice.txt file.
It uses the Get-Contentcmdlet to get the content of Notice.txt. The pipeline operator sends the results to the ForEach-Objectcmdlet, which applies the expression to each line of content in Get-Content. The expression uses the "$_" symbol to refer to the current item and the Replace parameter to specify the text to be replaced.
Another pipeline operator sends the changed content to Set-Content which replaces the text in Notice.txt with the new content.
The parentheses around the Get-Content command assure that the Get operation is complete, before the Set operation begins. Otherwise, command will fail because the two functions will be trying to access the same file.
RELATED LINKS