Copy-Item

Copy-Item
    [-Path] <String[]>
    [[-Destination] <String>]
    [-Container]
    [-Force]
    [-Filter <String>]
    [-Include <String[]>]
    [-Exclude <String[]>]
    [-Recurse]
    [-PassThru]
    [-Credential <PSCredential>]
    [-WhatIf]
    [-Confirm]
    [-FromSession <PSSession>]
    [-ToSession <PSSession>]
    [<CommonParameters>]

Copy-Item
    [[-Destination] <String>]
    -LiteralPath <String[]>
    [-Container]
    [-Force]
    [-Filter <String>]
    [-Include <String[]>]
    [-Exclude <String[]>]
    [-Recurse]
    [-PassThru]
    [-Credential <PSCredential>]
    [-WhatIf]
    [-Confirm]
    [-FromSession <PSSession>]
    [-ToSession <PSSession>]
    [<CommonParameters>]

Copy-Item
    [-Path] <string[]>
    [[-Destination] <string>]
    [-Container]
    [-Force]
    [-Filter <string>]
    [-Include <string[]>]
    [-Exclude <string[]>]
    [-Recurse]
    [-PassThru]
    [-Credential <pscredential>]
    [-WhatIf]
    [-Confirm]
    [<CommonParameters>]

Copy-Item
    [[-Destination] <string>]
    -LiteralPath <string[]>
    [-Container]
    [-Force]
    [-Filter <string>]
    [-Include <string[]>]
    [-Exclude <string[]>]
    [-Recurse]
    [-PassThru]
    [-Credential <pscredential>]
    [-WhatIf]
    [-Confirm]
    [<CommonParameters>]

O cmdlet Copy-Item copia um item de um local para outro local no mesmo namespace. Por exemplo, ele pode copiar um arquivo para uma pasta, mas não pode copiar um arquivo para uma unidade de certificado.

Esse cmdlet não corta nem exclui os itens que estão sendo copiados. Os itens específicos que o cmdlet pode copiar dependem do provedor do PowerShell que expõe o item. Por exemplo, ele pode copiar arquivos e diretórios em uma unidade do sistema de arquivos e chaves e entradas do Registro na unidade do Registro.

Esse cmdlet pode copiar e renomear itens no mesmo comando. Para renomear um item, insira o novo nome no valor do parâmetro Destination. Para renomear um item e não copiá-lo, use o cmdlet Rename-Item.

Este exemplo copia o arquivo mar1604.log.txt para o diretório C:\Presentation. O arquivo original não é excluído.

Copy-Item "C:\Wabash\Logfiles\mar1604.log.txt" -Destination "C:\Presentation"

Este exemplo copia o conteúdo do diretório C:\Logfiles no diretório C:\Drawings existente. O diretório Logfiles não é copiado.

Se o diretório Logfiles tiver arquivos em subdiretórios, esses subdiretórios serão copiados com suas árvores de arquivos intactas. Por padrão, o parâmetro Container é definido como True, que preserva a estrutura do diretório.

Copy-Item -Path "C:\Logfiles\*" -Destination "C:\Drawings" -Recurse

Este exemplo copia o conteúdo do diretório de origem C:\Logfiles e cria um novo diretório de destino. O novo diretório de destino, \Logs, é criado em C:\Drawings.

Para incluir o nome do diretório de origem, copie para um diretório de destino existente, conforme mostrado em Exemplo 2. Ou nomeie o novo diretório de destino com o mesmo diretório de origem.

Copy-Item -Path "C:\Logfiles" -Destination "C:\Drawings\Logs" -Recurse

Este exemplo usa o cmdlet Copy-Item para copiar o script Get-Widget.ps1 do diretório \\Server01\Share para o diretório \\Server12\ScriptArchive. Como parte da operação de cópia, o comando altera o nome do item de Get-Widget.ps1 para Get-Widget.ps1.txt, para que ele possa ser anexado com segurança a mensagens de email.

$copyParams = @{
    Path        = "\\Server01\Share\Get-Widget.ps1"
    Destination = "\\Server12\ScriptArchive\Get-Widget.ps1.txt"
}
Copy-Item @copyParams

Uma sessão é criada para o computador remoto chamado Server01 com a credencial de Contoso\User01 e armazena os resultados na variável chamada $Session.

O cmdlet Copy-Item copia test.log da pasta D:\Folder001 para a pasta C:\Folder001_Copy no computador remoto usando as informações de sessão armazenadas na variável $Session. O arquivo original não é excluído.

$Session = New-PSSession -ComputerName "Server01" -Credential "Contoso\User01"
Copy-Item "D:\Folder001\test.log" -Destination "C:\Folder001_Copy\" -ToSession $Session

Uma sessão é criada para o computador remoto chamado Server01 com a credencial de Contoso\User01 e armazena os resultados na variável chamada $Session.

O cmdlet Copy-Item copia a pasta D:\Folder002 para o diretório C:\Folder002_Copy no computador remoto usando as informações de sessão armazenadas na variável $Session. Quaisquer subpastas ou arquivos não são copiados sem usar a opção Recurse. A operação criará a pasta Folder002_Copy se ela ainda não existir.

$Session = New-PSSession -ComputerName "Server02" -Credential "Contoso\User01"
Copy-Item "D:\Folder002\" -Destination "C:\Folder002_Copy\" -ToSession $Session

Uma sessão é criada para o computador remoto chamado Server01 com a credencial de Contoso\User01 e armazena os resultados na variável chamada $Session.

O cmdlet Copy-Item copia todo o conteúdo da pasta D:\Folder003 para o diretório C:\Folder003_Copy no computador remoto usando as informações de sessão armazenadas na variável $Session. As subpastas são copiadas com suas árvores de arquivos intactas. A operação criará a pasta Folder003_Copy se ela ainda não existir.

$Session = New-PSSession -ComputerName "Server04" -Credential "Contoso\User01"
Copy-Item "D:\Folder003\" -Destination "C:\Folder003_Copy\" -ToSession $Session -Recurse

Uma sessão é criada para o computador remoto chamado Server01 com a credencial de Contoso\User01 e armazena os resultados na variável chamada $Session.

O cmdlet Copy-Item copia scriptingexample.ps1 da pasta D:\Folder004 para a pasta C:\Folder004_Copy no computador remoto usando as informações de sessão armazenadas na variável $Session. O arquivo original não é excluído.

$Session = New-PSSession -ComputerName "Server04" -Credential "Contoso\User01"
$copyParams = @{
    Path        = "D:\Folder004\scriptingexample.ps1"
    Destination = "C:\Folder004_Copy\scriptingexample_copy.ps1"
    ToSession   = $Session
}
Copy-Item @copyParams

Uma sessão é criada para o computador remoto chamado Server01 com a credencial de Contoso\User01 e armazena os resultados na variável chamada $Session.

O cmdlet Copy-Item copia test.log do C:\MyRemoteData\ remoto para a pasta de D:\MyLocalData local usando as informações de sessão armazenadas na variável $Session. O arquivo original não é excluído.

$Session = New-PSSession -ComputerName "Server01" -Credential "Contoso\User01"
Copy-Item "C:\MyRemoteData\test.log" -Destination "D:\MyLocalData\" -FromSession $Session

Uma sessão é criada para o computador remoto chamado Server01 com a credencial de Contoso\User01 e armazena os resultados na variável chamada $Session.

O cmdlet Copy-Item copia todo o conteúdo da pasta C:\MyRemoteData\scripts remota para a pasta de D:\MyLocalData local usando as informações de sessão armazenadas na variável $Session. Se a pasta scripts tiver arquivos em subpastas, essas subpastas serão copiadas com suas árvores de arquivos intactas.

$Session = New-PSSession -ComputerName "Server01" -Credential "Contoso\User01"
Copy-Item "C:\MyRemoteData\scripts" -Destination "D:\MyLocalData\" -FromSession $Session

Uma sessão é criada para o computador remoto chamado Server01 com a credencial de Contoso\User01 e armazena os resultados na variável chamada $Session.

O cmdlet Copy-Item copia todo o conteúdo da pasta C:\MyRemoteData\scripts remota para a pasta de D:\MyLocalData\scripts local usando as informações de sessão armazenadas na variável $Session. Como o parâmetro Recurse é usado, a operação cria a pasta scripts se ainda não existir. Se a pasta scripts tiver arquivos em subpastas, essas subpastas serão copiadas com suas árvores de arquivos intactas.

$Session = New-PSSession -ComputerName "Server01" -Credential "Contoso\User01"
$copyParams = @{
    Path        = "C:\MyRemoteData\scripts"
    Destination = "D:\MyLocalData\scripts"
    FromSession = $Session
    Recurse     = $true
}
Copy-Item @copyParams

Este exemplo mostra como copiar arquivos de uma estrutura de pastas de vários níveis em uma única pasta simples. Os três primeiros comandos mostram a estrutura de pastas existente e o conteúdo de dois arquivos, ambos os nomes file3.txt.

PS C:\temp\test> (Get-ChildItem C:\temp\tree -Recurse).FullName
C:\temp\tree\subfolder
C:\temp\tree\file1.txt
C:\temp\tree\file2.txt
C:\temp\tree\file3.txt
C:\temp\tree\subfolder\file3.txt
C:\temp\tree\subfolder\file4.txt
C:\temp\tree\subfolder\file5.txt

PS C:\temp\test> Get-Content C:\temp\tree\file3.txt
This is file3.txt in the root folder

PS C:\temp\test> Get-Content C:\temp\tree\subfolder\file3.txt
This is file3.txt in the subfolder

PS C:\temp\test> Copy-Item -Path C:\temp\tree -Filter *.txt -Recurse -Container:$false
PS C:\temp\test> (Get-ChildItem . -Recurse).FullName
C:\temp\test\subfolder
C:\temp\test\file1.txt
C:\temp\test\file2.txt
C:\temp\test\file3.txt
C:\temp\test\file4.txt
C:\temp\test\file5.txt

PS C:\temp\test> Get-Content .\file3.txt
This is file3.txt in the subfolder

O cmdlet Copy-Item tem o parâmetro Container definido como $false. Isso faz com que o conteúdo da pasta de origem seja copiado, mas não preserva a estrutura da pasta. Observe que os arquivos com o mesmo nome são substituídos na pasta de destino.

Este exemplo mostra os resultados usando o parâmetro Include para selecionar os itens a serem copiados.

Este exemplo usa a seguinte estrutura de pastas que contém os arquivos a serem copiados:

• D:\temp\tree\example.ps1
• D:\temp\tree\example.txt
• D:\temp\tree\examples\
• D:\temp\tree\examples\example_1.txt
• D:\temp\tree\examples\example_2.txt
• D:\temp\tree\examples\subfolder\
• D:\temp\tree\examples\subfolder\test.txt

Neste exemplo, Copy-Item é chamado com um curinga para os parâmetros de Caminho e Incluir. Especificar um curinga para o parâmetro caminho garante que ele processe todos os arquivos e pastas que correspondem a D:\temp\tree\*. O parâmetro Include filtra a lista de itens a serem processados, limitando a operação apenas aos caminhos que começam com ex.

PS D:\temp\test\out> Copy-Item -Path D:\temp\tree\* -Include ex*
PS D:\temp\test\out> (Get-ChildItem -Recurse).FullName
D:\temp\out\examples
D:\temp\out\example.ps1
D:\temp\out\example.txt

O parâmetro Include é aplicado ao conteúdo da pasta D:\temp\tree para copiar todos os itens que correspondem a ex*. Observe que, sem recursão, a pasta D:\temp\out\examples é copiada, mas nenhum de seus conteúdos é copiado.

Este exemplo mostra os resultados usando o parâmetro Include para selecionar os itens a serem copiados.

Este exemplo usa a seguinte estrutura de pastas que contém os arquivos a serem copiados:

• D:\temp\tree\example.ps1
• D:\temp\tree\example.txt
• D:\temp\tree\examples\
• D:\temp\tree\examples\example_1.txt
• D:\temp\tree\examples\example_2.txt
• D:\temp\tree\examples\subfolder\
• D:\temp\tree\examples\subfolder\test.txt

Neste exemplo, Copy-Item é chamado com um curinga para os parâmetros de Caminho e Incluir. Especificar um curinga para o parâmetro Path garante que ele processe todos os arquivos e pastas que correspondem a D:\temp\tree\*. O parâmetro Include filtra a lista de itens a serem processados, limitando a operação apenas aos caminhos que começam com ex.

D:\temp\out> Copy-Item -Path D:\temp\tree\* -Include ex* -Recurse
D:\temp\out> (Get-ChildItem -Recurse).FullName
D:\temp\out\examples
D:\temp\out\example.ps1
D:\temp\out\example.txt
D:\temp\out\examples\subfolder
D:\temp\out\examples\example_1.txt
D:\temp\out\examples\example_2.txt
D:\temp\out\examples\subfolder\test.txt

O parâmetro Include é aplicado ao conteúdo da pasta D:\temp\tree para copiar todos os itens que correspondem a ex*. Observe que, com a recursão, a pasta D:\temp\out\examples é copiada juntamente com todos os arquivos e subpastas. A cópia inclui arquivos que não corresponder ao filtro de inclusão. Ao usar Copy-Item, os filtros só se aplicam ao nível superior especificado pelo parâmetro caminho. Em seguida, a recursão é aplicada a esses itens correspondentes.

Este exemplo mostra como limitar os arquivos copiados recursivamente de um caminho de correspondência curinga em outra pasta. O exemplo 13 mostra que, como o parâmetro Include filtra apenas os caminhos resolvidos para um de Caminho deque especifica curinga, o parâmetro Incluir não pode ser usado para limitar os arquivos copiados recursivamente de uma pasta. Em vez disso, você pode usar Get-ChildItem para localizar os itens que deseja copiar e passar esses itens para Copy-Item.

Este exemplo usa a seguinte estrutura de pastas que contém os arquivos a serem copiados:

• D:\temp\tree\example.ps1
• D:\temp\tree\example.txt
• D:\temp\tree\examples\
• D:\temp\tree\examples\example_1.txt
• D:\temp\tree\examples\example_2.txt
• D:\temp\tree\examples\subfolder\
• D:\temp\tree\examples\subfolder\test.txt

Para copiar todos os itens que começam com ex*, use Get-ChildItem com os parâmetros Recurse e Filter e direcione os resultados para Copy-Item.

D:\temp\out> Get-ChildItem -Path D:\temp\tree -Recurse -Filter ex* | Copy-Item
D:\temp\out> (Get-ChildItem -Recurse).FullName
D:\temp\out\examples
D:\temp\out\example_1.txt
D:\temp\out\example_2.txt
D:\temp\out\example.ps1
D:\temp\out\example.txt

Ao contrário do Copy-Item, o parâmetro filtro de para Get-ChildItem se aplica aos itens descobertos durante a recursão. Isso permite que você localize, filtre e copie os itens recursivamente.

Este cmdlet suporta os parâmetros comuns: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction e -WarningVariable. Para obter mais informações, consulte about_CommonParameters.

É possível direcionar uma cadeia de caracteres que contém um caminho para este cmdlet.

Por padrão, esse cmdlet não retorna nenhuma saída.

Quando você usa o parâmetro PassThru, esse cmdlet retorna um objeto que representa o item copiado.

O PowerShell inclui os seguintes aliases para Copy-Item:

• Todas as plataformas:
  • copy
  • cpi
• Windows:
  • cp

Esse cmdlet foi projetado para funcionar com os dados expostos por qualquer provedor. Para listar os provedores disponíveis na sessão, digite Get-PSProvider. Para obter mais informações, consulte about_Providers.