Skip to content

Commit

Permalink
Fixes MicrosoftDocs#4189 - Rewrite all provider cmdlets for Filter/Cr…
Browse files Browse the repository at this point in the history 
…edential clarity
  • Loading branch information
@bobbytreed
bobbytreed committed May 14, 2019
1 parent 14f7fa2 commit c0c0725
Show file tree
Hide file tree
Showing 25 changed files with 1,419 additions and 1,023 deletions.
197 changes: 116 additions & 81 deletions reference/6/Microsoft.PowerShell.Management/Add-Content.md
View file
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
---
ms.date: 1/28/2019
ms.date: 5/14/2019
schema: 2.0.0
locale: en-us
keywords: powershell,cmdlet
Expand Down Expand Up @@ -46,66 +46,70 @@ If you need to create files or directories for the following examples, see [New-
This example appends a value to text files in the current directory but excludes files based on
their file name.

The **Path** parameter to specifies all `.txt` files in the current directory, but the **Exclude**
parameter ignores file names that match the specified pattern.

The **Value** parameter specifies the text string that is written to the files.

```powershell
Add-Content -Path .\*.txt -Exclude help* -Value 'End of file'
```

The `Add-Content` cmdlet uses the **Path** parameter to specify all .txt files in the current
directory. The **Exclude** parameter ignores file names that match the specified pattern. The
**Value** parameter specifies the text string that is written to the files.

Use [Get-Content](Get-Content.md) to display the contents of these files.

### Example 2: Add a date to the end of the specified files

This example appends the date to files in the current directory and displays the date in the
PowerShell console.

The `Add-Content` creates two new files in the current directory. The **Value** parameter contains
the output of the `Get-Date`

The **PassThru** parameter outputs the added contents to the pipeline. Because there is no other
cmdlets to receive the output, it is displayed in the PowerShell console.

The `Get-Content` cmdlet displays the updated file, `DateTimeFile1.log`.

```powershell
Add-Content -Path .\DateTimeFile1.log, .\DateTimeFile2.log -Value (Get-Date) -PassThru
Get-Content -Path .\DateTimeFile1.log
```

The `Add-Content` cmdlet uses the **Path** and **Value** parameters to create two new files in the
current directory. The **Value** parameter specifies the `Get-Date` cmdlet to get the date and
passes the date to `Add-Content`. The `Add-Content` cmdlet writes the date to each file. The
**PassThru** parameter passes an object that represents the date object. Because there is no other
cmdlet to receive the passed object, it is displayed in the PowerShell console. The `Get-Content`
cmdlet displays the updated file, DateTimeFile1.log.
```Output
Tuesday, May 14, 2019 8:24:27 AM
Tuesday, May 14, 2019 8:24:27 AM
5/14/2019 8:24:27 AM
```

### Example 3: Add the contents of a specified file to another file

This example gets the content from a file and appends that content into another file.
This example gets the content from a file and stores the content in a variable. The variable is
used to append the content into another file.

```powershell
Add-Content -Path .\CopyToFile.txt -Value (Get-Content -Path .\CopyFromFile.txt)
$From = Get-Content -Path .\CopyFromFile.txt
Add-Content -Path .\CopyToFile.txt -Value $From
Get-Content -Path .\CopyToFile.txt
```

The `Add-Content` cmdlet uses the **Path** parameter to specify the new file in the current
directory, CopyToFile.txt. The **Value** parameter uses the `Get-Content` cmdlet to get the
contents of the file, CopyFromFile.txt. The parentheses around the `Get-Content` cmdlet ensure that
the command finishes before the `Add-Content` command begins. The **Value** parameter is passed to
`Add-Content`. The `Add-Content` cmdlet appends the data to the CopyToFile.txt file. The
`Get-Content` cmdlet displays the updated file, CopyToFile.txt.
- The `Get-Content` cmdlet gets the contents of `CopyFromFile.txt` and stores the contents in the
`$From` variable.
- The `Add-Content` cmdlet updates the `CopyToFile.txt` file using the contents of the `$From`
variable.
- The `Get-Content` cmdlet displays CopyToFile.txt.

### Example 4: Use a variable to add the contents of a specified file to another file
### Example 4: Add the contents of a specified file to another file using the pipeline

This example gets the content from a file and stores the content in a variable. The variable is
used to append the content into another file.
This example gets the content from a file and pipes it to the `Add-Content` cmdlet.

The `Get-Content` cmdlet gets the contents of `CopyFromFile.txt`. The results are piped to the
`Add-Content` cmdlet, which updates the `CopyToFile.txt`.

The last `Get-Content` cmdlet displays `CopyToFile.txt`.

```powershell
$From = Get-Content -Path .\CopyFromFile.txt
Add-Content -Path .\CopyToFile.txt -Value $From
Get-Content -Path .\CopyFromFile.txt | Add-Content -Path .\CopyToFile.txt
Get-Content -Path .\CopyToFile.txt
```

The `Get-Content` cmdlet gets the contents of CopyFromFile.txt and stores the contents in the
`$From` variable. The `Add-Content` cmdlet uses the **Path** parameter to specify the
CopyToFile.txt file in the current directory. The **Value** parameter uses the `$From` variable and
passes the content to `Add-Content`. The `Add-Content` cmdlet updates the CopyToFile.txt file. The
`Get-Content` cmdlet displays CopyToFile.txt.

### Example 5: Create a new file and copy content

This example creates a new file and copies an existing file's content into the new file.
Expand All @@ -115,16 +119,17 @@ Add-Content -Path .\NewFile.txt -Value (Get-Content -Path .\CopyFromFile.txt)
Get-Content -Path .\NewFile.txt
```

The `Add-Content` cmdlet uses the **Path** and **Value** parameters to create a new file in the
current directory. The **Value** parameter uses the `Get-Content` cmdlet to get the contents of an
existing file, CopyFromFile.txt. The parentheses around the `Get-Content` cmdlet ensure that the
command finishes before the `Add-Content` command begins. The **Value** parameter passes the
content to `Add-Content` which updates the NewFile.txt file. The `Get-Content` cmdlet displays the
contents of the new file, NewFile.txt.
- The `Add-Content` cmdlet uses the **Path** and **Value** parameters to create a new file in the
current directory.
- The `Get-Content` cmdlet gets the contents of an existing file, `CopyFromFile.txt`
and passes it to the **Value** parameter.
- The parentheses around the `Get-Content` cmdlet ensure that the command finishes before the
`Add-Content` command begins.
- The `Get-Content` cmdlet displays the contents of the new file, `NewFile.txt`.

### Example 6: Add content to a read-only file

This command adds the value to the file even if the **IsReadOnly** file attribute is set to True.
This command adds a value to the file even if the **IsReadOnly** file attribute is set to **True**.
The steps to create a read-only file are included in the example.

```powershell
Expand All @@ -141,17 +146,32 @@ Mode LastWriteTime Length Name
-ar-- 1/28/2019 13:35 0 IsReadOnlyTextFile.txt
```

The `New-Item` cmdlet uses the **Path** and **ItemType** parameters to create the file
IsReadOnlyTextFile.txt in the current directory. The `Set-ItemProperty` cmdlet uses the **Name**
and **Value** parameters to change the file's **IsReadOnly** property to True. The `Get-ChildItem`
cmdlet shows the file is empty (0) and has the read-only attribute (`r`). The `Add-Content` cmdlet
uses the **Path** parameter to specify the file. The **Value** parameter includes the text string
to append to the file. The **Force** parameter writes the text to the read-only file. The
`Get-Content` cmdlet uses the **Path** parameter to display the file's contents.
- The `New-Item` cmdlet uses the **Path** and **ItemType** parameters to create the file
`IsReadOnlyTextFile.txt` in the current directory.
- The `Set-ItemProperty` cmdlet uses the **Name** and **Value** parameters to change the file's
**IsReadOnly** property to True.
- The `Get-ChildItem` cmdlet shows the file is empty (0) and has the read-only attribute (`r`).
- The `Add-Content` cmdlet uses the **Path** parameter to specify the file. The **Value** parameter
includes the text string to append to the file. The **Force** parameter writes the text to the
read-only file.
- The `Get-Content` cmdlet uses the **Path** parameter to display the file's contents.

To remove the read-only attribute, use the `Set-ItemProperty` command with the **Value** parameter
set to `False`.

### Example 7: Use Filters with Add-Content

You can specify a filter to the `Add-Content` cmdlet. When using filters to qualify the **Path**
parameter, you need to include a trailing asterisk (`*`) to indicate the contents of the
path.

The following command adds the word "Done" the content of all `*.txt` files in the `C:\Temp`
directory.

```powershell
Add-Content -Path C:\Temp\* -Filter *.txt -Value "Done"
```

## PARAMETERS

### -AsByteStream
Expand All @@ -176,15 +196,10 @@ Accept wildcard characters: False
### -Credential
Specifies a user account that has permission to perform this action. The default is the current
user.
Type a user name, such as **User01** or **Domain01\User01**, or enter a **PSCredential** object,
such as one generated by the `Get-Credential` cmdlet. If you type a user name, you will be prompted
for a password.

> [!WARNING]
> This parameter is not supported by any providers installed with PowerShell.
> [!NOTE]
> This parameter is not supported by any providers installed with Windows PowerShell.
> To impersonate another user, or elevate your credentials when running this cmdlet,
> use [Invoke-Command](../Microsoft.PowerShell.Core/Invoke-Command.md)
```yaml
Type: PSCredential
Expand Down Expand Up @@ -237,8 +252,15 @@ Accept wildcard characters: False

### -Exclude

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.
Specifies, as a string array, an item or items that this cmdlet excludes in the operation.
The value of this parameter qualifies the **Path** parameter.

Enter a path element or pattern, such as `*.txt`.
Wildcard characters are permitted.

The **Exclude** parameter is effective only when the command includes the contents of an item,
such as `C:\Windows\*`, where the wildcard character specifies the contents of the `C:\Windows`
directory.

```yaml
Type: String[]
Expand All @@ -254,11 +276,17 @@ Accept wildcard characters: False

### -Filter

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 filters
when objects are retrieved. Otherwise, PowerShell processes filters after the objects are
retrieved.
Specifies a filter to qualify the **Path** parameter. When you specify a filter, the **Path**
parameter requires a trailing asterisk (`*`) to indicate the contents of the path.

The [FileSystem](../Microsoft.PowerShell.Core/About/about_FileSystem_Provider.md) provider is the
only installed PowerShell provider that supports the use of filters.

You can find the syntax for the **FileSystem** filter language in
[about_Wildcards](../Microsoft.PowerShell.Core/About/about_Wildcards.md).

Filters are more efficient than other parameters, because the provider applies them when the cmdlet
gets the objects rather than having PowerShell filter the objects after they are retrieved.

```yaml
Type: String
Expand Down Expand Up @@ -292,8 +320,15 @@ Accept wildcard characters: False

### -Include

Adds 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.
Specifies, as a string array, an item or items that this cmdlet includes in the operation.
The value of this parameter qualifies the **Path** parameter.
Enter a path element or pattern, such as `"*.txt"`.

Wildcard characters are permitted.

The **Include** parameter is effective only when the command includes the contents of an item, such
as `C:\Windows\*`, where the wildcard character specifies the contents of the `C:\Windows`
directory.

```yaml
Type: String[]
Expand All @@ -309,10 +344,12 @@ Accept wildcard characters: False

### -LiteralPath

Specifies the path to the items that receive the additional 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
PowerShell not to interpret any characters as escape sequences.
Specifies a path to one or more locations. 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 PowerShell not to interpret any characters
as escape sequences.

For more information, see [about_Quoting_Rules](../Microsoft.Powershell.Core/About/about_Quoting_Rules.md).

```yaml
Type: String[]
Expand Down Expand Up @@ -464,7 +501,7 @@ Accept wildcard characters: False
This cmdlet supports the common parameters: `-Debug`, `-ErrorAction`, `-ErrorVariable`,
`-InformationAction`, `-InformationVariable`, `-OutVariable`, `-OutBuffer`, `-PipelineVariable`,
`-Verbose`, `-WarningAction`, and `-WarningVariable`. For more information, see
[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216).
[about_CommonParameters](../Microsoft.PowerShell.Core/About/about_CommonParameters.md).

## INPUTS

Expand All @@ -481,17 +518,15 @@ represents the content. Otherwise, this cmdlet does not generate any output.

## NOTES

When you pipe an object to `Add-Content`, the object is converted to a string before it is added to
the item. The object type determines the string format, but the format might be different than the
default display of the object. To control the string format, use the formatting parameters of the
sending cmdlet.

You can also refer to `Add-Content` by its built-in alias, `ac`. For more information, see
[about_Aliases](../Microsoft.PowerShell.Core/About/about_Aliases.md).

The `Add-Content` cmdlet is designed to work with the data exposed by any provider. To list the
providers available in your session, type `Get-PSProvider`. For more information, see
[about_Providers](../Microsoft.PowerShell.Core/About/about_Providers.md).
- When you pipe an object to `Add-Content`, the object is converted to a string before it is added to
the item. The object type determines the string format, but the format might be different than the
default display of the object. To control the string format, use the formatting parameters of the
sending cmdlet.
- You can also refer to `Add-Content` by its built-in alias, `ac`. For more information, see
[about_Aliases](../Microsoft.PowerShell.Core/About/about_Aliases.md).
- The `Add-Content` cmdlet is designed to work with the data exposed by any provider. To list the
providers available in your session, type `Get-PSProvider`. For more information, see
[about_Providers](../Microsoft.PowerShell.Core/About/about_Providers.md).

## RELATED LINKS

Expand All @@ -507,4 +542,4 @@ providers available in your session, type `Get-PSProvider`. For more information

[New-Item](New-Item.md)

[Set-Content](Set-Content.md)
[Set-Content](Set-Content.md)
Loading

0 comments on commit c0c0725

Please sign in to comment.