Usando o Cmdlet Copy-Item do PowerShell para Copiar Arquivos

O que é o Cmdlet PowerShell Copy-Item?

O cmdlet Copy-Item no Powershell é usado principalmente para copiar arquivos da fonte para o destino. Em termos de quantidade de arquivos, podem ser individuais ou múltiplos, juntamente com o seu conteúdo. Ele também pode funcionar em diferentes sistemas de arquivos, como locais, compartilhamentos de rede etc,

Sintaxe Básica e Parâmetros

A sintaxe básica para o cmdlet Copy-Item do PowerShell é a seguinte:

      Copy-Item -Path <source> -Destination <destination> [<parameters>]
      

Se você digitar apenas o cmdlet, o PowerShell solicitará a origem, conforme mostrado abaixo:

O primeiro parâmetro obrigatório é o caminho de origem. Este parâmetro de caminho do item especifica o caminho para o item ou itens a serem copiados. A origem pode ser um caminho de arquivo ou pasta. Vários caminhos podem ser especificados usando uma lista separada por vírgulas, e o caminho pode conter curingas. Uma boa prática seria fornecer uma string de caminho de destino para especificar o caminho para o qual os itens devem ser copiados. Se estiver copiando um único item, o caminho pode incluir um novo nome para o item copiado, se desejado.

Abaixo está uma lista de outros parâmetros para o cmdlet Copy-Item do PowerShell:

• -Recurse: Copia subdiretórios e seu conteúdo de forma recursiva, o que significa que o cmdlet Copy-Item é aplicado à pasta de nível superior e a todos os níveis de subpastas abaixo dela.
• -Force parameter: Sobrescreve arquivos somente leitura existentes e cria diretórios de destino se eles não existirem.
• -Container: Preserva objetos de contêiner durante operações de cópia, o que é útil ao copiar estruturas de diretórios.
• -Filter: Especifica uma string de filtro para qualificar o parâmetro de caminho, como especificar uma determinada extensão de arquivo
• -Include: Especifica itens para copiar e suporta curingas. Apenas itens que correspondem aos parâmetros Path e Include são copiados
• -Exclude: Especifica itens a serem omitidos da cópia, suporta curingas
• -Credential: Especifica as credenciais da conta de usuário a serem usadas para a operação
• -WhatIf: Mostra o que aconteceria se o comando fosse executado sem realmente executá-lo
• -Confirm: Solicita confirmação antes de executar o comando
• -FromSession: Especifica o objeto PSSession do qual obter um arquivo remoto.
• -ToSession: Especifica o objeto PSSession para o qual enviar um arquivo remoto
  

Casos de Uso Comuns

Na maioria dos exemplos, copiaremos arquivos para múltiplos locais no computador local. Existem, no entanto, uma variedade de casos de uso comuns para o cmdlet Copy-Item, incluindo:

• Criando backups de arquivos e pastas importantes
• Distribuindo arquivos ou aplicações simples por várias máquinas
• Migrando grandes quantidades de arquivos entre servidores ou locais de armazenamento
• Os desenvolvedores podem criar instantâneos de pastas de projeto em diferentes estágios do desenvolvimento.
• Distribua arquivos de configuração por vários servidores

Agora vamos comparar o cmdlet Copy-Item com outros cmdlets de gerenciamento de arquivos:

Copy-Item vs. Move-Item:

• Copy-Item cria uma cópia, mantendo o original intacto
• Move-Item move o arquivo/pasta, removendo-o do local original

Copy-Item vs. Get-ChildItem

• Copy-Item executa a ação de copiar
• Get-ChildItem lista arquivos e pastas e é frequentemente usado em conjunto com o Copy-Item

Observe que o cmdlet Copy-Item é recomendado para cópias básicas de arquivos. Aqueles que procuram recursos mais avançados para transferências de arquivos grandes ou espelhamento podem considerar o Microsoft Robocopy.

Copiando arquivos com o Cmdlet Copy-Item do PowerShell

Exemplo Básico de Cópia de Arquivo

Neste exemplo, queremos copiar uma planilha de uma pasta para outra usando o comando copy item do PowerShell.

      Copy-Item -Path "C:\Destination One\SpreadsheetOne.xlsx" -Destination "c:\Destination Two"

      

Aqui está como parece no PowerShell:

Copiando Múltiplos Arquivos

Agora, vamos copiar mais de um arquivo por vez. Observe que os caminhos dos arquivos usam unidades diferentes. Lembre-se de que se o diretório de destino não existir, o PowerShell irá criá-lo.

      Copy-Item -Path "C:\source\file1.txt","C:\Source\file2.txt" -Destination "D:\Destination Two"
      

Copiando arquivos com renomeação

Você pode copiar um arquivo para uma nova pasta e renomeá-lo no processo usando o comando abaixo:

      Copy-Item -Path "C:\Source\file1.txt" -Destination "C:\Destination Two\NewName1.txt"
      

Aqui está como parece no PowerShell:

Copiando pastas com PowerShell

A capacidade de cópia do PowerShell não se limita apenas a arquivos – você também pode copiar uma pasta usando o cmdlet Copy-Item para novos locais. Abaixo, mostramos como usar o comando do PowerShell para copiar pasta e conteúdos.

Exemplo Básico de Cópia de Pasta

Utilize o comando do PowerShell para copiar pastas abaixo para copiar uma pasta para um local diferente. Este comando de cópia do PowerShell copiará todos os arquivos na pasta “source” e os colocará na pasta de destino.

      Copy-Item -Path "C:\source\folder" -Destination "D:\destination"
      

Copiando pastas com subpastas

E se a pasta de origem tivesse múltiplos subdiretórios dentro dela? Usando o comando básico acima, qualquer coisa dentro das subpastas teria sido ignorada. Se você quiser copiar tudo na pasta de origem, incluindo o conteúdo dos subdiretórios, você precisa executar um comando de cópia de pasta e subpastas no PowerShell usando o parâmetro Recurse.

      Copy-Item -Path "C:\source\folder" -Destination "D:\destination" -Recurse
      

Copiando e mesclando múltiplas pastas

Vamos supor que você queira copiar os arquivos de duas pastas de origem e mesclá-los em uma única pasta de destino. Isso é facilmente realizado usando o comando do PowerShell para copiar o conteúdo de uma pasta para outra. Aqui, dois caminhos de origem são separados por uma vírgula. Eles são copiados e depois mesclados na pasta de destino.

      Copy-Item -Path "C:\source1\*","C:\source2\*" -Destination "D:\destination"
      

Técnicas Avançadas de Cópia de Arquivos e Pastas

Usando Curingas em Caminhos de Arquivos

Os curingas permitem que você copie vários arquivos ou pastas que correspondam a um padrão específico sem precisar listar cada item individualmente. Eles são ideais para lidar com um grande número de arquivos ou pastas, pois o uso de curingas pode reduzir significativamente a quantidade de código necessária. No exemplo abaixo, o curinga é usado para qualquer arquivo .txt:

      Copy-Item -Path "C:\source\*.txt" -Destination "C:\Destination Two"
      

Eis como parece no PowerShell:

Filtrando arquivos com parâmetros de Inclusão e Exclusão

Haverá momentos em que você desejará excluir arquivos específicos dentro de uma pasta para cópia. Pode ser que queira excluir ou apenas incluir certos tipos de arquivos ou versões de arquivos, ou não incluir arquivos específicos que contenham informações sensíveis. Assim, provavelmente vai querer excluir arquivos temporários ou desnecessários durante um processo de backup ou migração.

No exemplo abaixo, estamos copiando e especificando que todos os arquivos de log devem ser considerados para cópia; no entanto, qualquer arquivo de log que também tenha uma extensão .tmp será excluído.

      Copy-Item -Path "C:\source\*" -Destination "D:\destination" -Include "*.log" -Exclude "*.tmp"
      

Usando o parâmetro Force para sobrescrever arquivos

Por padrão, o Copy-Item sobrescreverá arquivos existentes no destino sem solicitar confirmação. Às vezes, você pode encontrar uma situação onde a pasta de destino contém um arquivo somente leitura com o mesmo nome do arquivo que você está tentando copiar. Por padrão, o Copy-Item não sobrescreverá este arquivo somente leitura. No entanto, você pode anular esse comportamento e forçar a sobrescrita usando o parâmetro -Force. Aqui está um exemplo de como usá-lo:

      Copy-Item -Path "C:\source\file.txt" -Destination "D:\destination" -Force
      

Copiando arquivos e pastas para computadores remotos via Copy-Item

Embora existam situações em que você pode precisar copiar arquivos e pastas para diferentes locais de unidade em um computador local, a verdadeira força do cmdlet Copy-Item reside na sua capacidade de facilitar a transferência de arquivos e pastas entre computadores remotos.

Configurando uma Sessão Remota com New-PSSession

Digamos que você queira copiar alguns arquivos para um computador remoto usando o PowerShell. Embora você possa ter direitos de administrador local, sua conta atual pode não ter os direitos adequados no computador de destino. Você também precisará saber o nome do computador remoto. Neste caso, você deve estabelecer uma sessão remota com o novo computador usando uma credencial alternativa. Você pode realizar a cópia de arquivos para uma pasta no PowerShell usando o comando $session abaixo.

      $session = New-PSSession -ComputerName "RemotePC" -Credential "User"
      

Copiando arquivos para um computador remoto

Agora você pode copiar arquivos para o computador remoto usando a sessão estabelecida.

      Copy-Item -Path "C:\source\file.txt" -Destination "C:\remote\destination" -ToSession $session
      

Copiando arquivos de um computador remoto

Claro, você pode querer copiar arquivos de um computador remoto para o seu computador local. Para fazer isso, use o seguinte comando.

      Copy-Item -Path "C:\remote\source\file.txt" -Destination "C:\local\destination" -FromSession $session
      

Copiando Recursivamente Pastas Remotas

Nos exemplos anteriores envolvendo computadores remotos, subpastas e seus conteúdos não foram incluídos na operação de cópia. Para incluir todo o conteúdo do caminho do item de origem, incluindo todas as subpastas e arquivos, adicione o parâmetro -Recurse ao comando Copy-Item, assim como fizemos com operações de cópia locais.

      Copy-Item -Path "C:\remote\source\folder" -Destination "C:\local\destination" -FromSession $session -Recurse
      

Tratamento de Erros e Verificação

Usando os parâmetros WhatIf e Confirm

O parâmetro WhatIf permite que você verifique o resultado de um comando sem fazer nenhuma alteração. Por exemplo, como mostrado abaixo, você pode querer confirmar que os caminhos de origem e destino estão corretos antes de executar a operação de cópia.

Você também pode verificar o comportamento de sobrescrita, que mostra quais arquivos serão sobrescritos no destino, ajudando a evitar perda de dados não intencional. WhatIf ajuda você a entender exatamente quais itens serão copiados. O parâmetro do comando é mostrado abaixo.

      Copy-Item -Path "C:\Source\File1.txt" -Destination "C:\Destination Two" -WhatIf
      

Por padrão, a maioria dos cmdlets do PowerShell faz alterações no sistema sem confirmação do usuário. Pode haver situações em que você deseja que o usuário confirme uma ação antes de executá-la. O melhor exemplo seria se você usasse o PowerShell para remover um arquivo. No exemplo abaixo, você usa o comando confirm para solicitar a confirmação do usuário.

      Remove-Item -Path C:\file.txt -Confirm
      

O comando será executado no PowerShell, conforme mostrado abaixo:

Você pode adicionar o parâmetro -Confirm a qualquer comando Copy-Item.

Verificando o Processo de Cópia

Ao usar o PowerShell para fazer backup de arquivos críticos, você pode querer verificar se o processo de cópia ocorreu. Você pode criar um script simples de PowerShell, como o abaixo, para confirmar a cópia de arquivos comparando contagens de arquivos, tamanhos e carimbos de data/hora.

      # Define source and destination paths
$source = "C:\SourceFolder"
$destination = "C:\DestinationFolder"
# Copy the files from source to destination
Copy-Item -Path $source\* -Destination $destination -Recurse
# Confirm the files were copied by checking if they exist in the destination folder
$sourceFiles = Get-ChildItem -Path $source
$allCopied = $true
foreach ($file in $sourceFiles) {
    $destinationFile = Join-Path $destination $file.Name
    if (Test-Path $destinationFile) {
        Write-Host "File '$($file.Name)' was copied successfully."
    } else {
        Write-Host "File '$($file.Name)' failed to copy."
        $allCopied = $false
    }
}
if ($allCopied) {
    Write-Host "All files copied successfully."
} else {
    Write-Host "Some files failed to copy."
}
      

Tratamento de Erros e Tentativas de Recuperação

Você pode querer utilizar o tratamento de erros para a cópia de arquivos grandes para garantir que seus scripts funcionem corretamente e possam se recuperar de falhas inesperadas. No PowerShell, a principal maneira de lidar com erros é através de blocos try-catch. O script abaixo utiliza o try-catch para tratar erros ao copiar arquivos

      # Define source and destination paths
$source = "C:\SourceFolder"
$destination = "C:\DestinationFolder"
# Function to copy files with error handling
function Copy-Files {
    try {
        # Copy files and set error action to stop failure
        Copy-Item -Path $source\* -Destination $destination -Recurse -ErrorAction Stop
        Write-Host "Files copied successfully."
    }
    catch {
        # Log the error message
        Write-Error "An error occurred while copying files: $($_.Exception.Message)"
        # Perform additional actions, like retrying or logging
    }
    finally {
        Write-Host "Copy operation complete."
    }
}
# Execute the function
Copy-Files

      

Exemplos Práticos e Casos de Uso do Cmdlet Copy-Item

Exemplos Detalhados de Tarefas Comuns

• Copiando arquivos de um disco rígido com falhas: Um disco rígido apresenta sinais de falha e arquivos críticos precisam ser copiados para um local seguro antes que o disco falhe.
• Automação de Backup para Alterações Diárias de Arquivos: Para recuperação de desastres, uma empresa pode precisar fazer backup de todos os arquivos em um diretório crítico para um servidor de backup.
• Migração de um Servidor On-Prem para Armazenamento na Nuvem: Uma empresa pode querer migrar os documentos do seu servidor local de discos locais para um provedor de armazenamento na nuvem, como Azure ou AWS.
• Implantando Arquivos de Configuração em Múltiplos Servidores: Um administrador de sistema deseja implantar arquivos de configuração atualizados a partir de C:\ConfigUpdates para uma lista de servidores remotos.

Cenários e Soluções do Mundo Real

Uma estrutura de arquivos complexa pode apresentar alguns desafios ao usar o cmdlet Copy-Item. Por exemplo, caminhos de arquivo longos podem ser um problema para versões mais antigas do Windows que não suportam caminhos de arquivo com mais de 260 caracteres. Nessas instâncias, você pode querer usar caminhos UNC em vez de caminhos de arquivo locais.

Pode haver situações em que você precise usar o parâmetro -LiteralPath no cmdlet Copy-Item. Isso pode ser necessário quando o caminho contém caracteres especiais (como [, ], ou *) que o PowerShell pode interpretar como caracteres curinga ou sequências de escape.

Problemas de permissão também são um problema comum. Você pode usar o parâmetro -Force para substituir algumas restrições ou executar o PowerShell como administrador.

Scripts de Exemplo para Automação

É do seu interesse automatizar o máximo possível de tarefas manuais para otimizá-las e evitar erros humanos. Abaixo está um exemplo de um script PowerShell que é usado para fazer backup de uma pasta para um diretório de backup.

      # Define source and destination directories
$sourcePath = "C:\SourceDirectory"
$backupPath = "D:\BackupDirectory"
# Get current timestamp to append to the backup folder
$timestamp = Get-Date -Format "yyyyMMdd_HHmmss"
# Create a new folder for the current backup with timestamp
$backupDestination = "$backupPath\Backup_$timestamp"
New-Item -ItemType Directory -Path $backupDestination
# Copy all files and directories from the source to the backup folder
try {
    Copy-Item -Path $sourcePath -Destination $backupDestination -Recurse -Force
    Write-Output "Backup completed successfully on $(Get-Date)"
} catch {
    Write-Output "An error occurred during the backup: $_"
}
# Optional: Clean up old backups (e.g., delete backups older than 30 days)
$daysToKeep = 30
$oldBackups = Get-ChildItem -Path $backupPath -Directory | Where-Object { $_.CreationTime -lt (Get-Date).AddDays(-$daysToKeep) }
foreach ($backup in $oldBackups) {
    try {
        Remove-Item -Path $backup.FullName -Recurse -Force
        Write-Output "Old backup removed: $($backup.FullName)"
    } catch {
        Write-Output "An error occurred while deleting old backups: $_"
    }
}
      

Dicas e Melhores Práticas

Melhores Práticas para Usar Copy-Item

Embora o cmdlet Copy-Item seja direto, aqui estão algumas das melhores práticas que podem ajudá-lo em circunstâncias mais complexas.

• Execute o PowerShell como Administrador
• Utilize o parâmetro -Recurse para copiar estruturas de diretórios inteiros.
• Utilize o parâmetro -Force com prudência para evitar sobrescritas não intencionais
• Ao copiar diretórios grandes, considere alternativas como Robocopy ou outras ferramentas mais adequadas para trabalhos de grande porte.
• Considere usar -WhatIf para testar seus comandos e ver o que pode acontecer sem fazer alterações reais.

Erros Comuns e Como Evitá-los

Além das melhores práticas, você também deve estar atento a estas armadilhas comuns ao usar scripts PowerShell:

• Evite usar caminhos incorretos ou relativos que não se resolvem como esperado, utilizando caminhos completos
• É fácil esquecer-se dos subdiretórios subjacentes, portanto, use o parâmetro -Recurse para garantir que todos os arquivos contidos no diretório pai sejam copiados.
• Permissões insuficientes impedirão que você complete operações de cópia, especialmente quando máquinas remotas estiverem envolvidas. Garanta as permissões adequadas e use privilégios elevados quando necessário.
• Quando operações de cópia complexas não são concluídas corretamente, utilize blocos try-catch e implemente um registro de erros adequado.

Considerações de Desempenho e Otimizações

Copiar grandes conjuntos de dados pode consumir muita capacidade de processamento no seu computador. O processamento paralelo é uma técnica de computação que envolve dividir uma tarefa em partes menores e executá-las simultaneamente em vários processadores ou núcleos. O processamento paralelo pode melhorar significativamente o desempenho quando aplicado a operações de arquivo como as realizadas pelo cmdlet Copy-Item. Em vez de copiar arquivos um de cada vez sequencialmente, o processamento paralelo permite que vários arquivos sejam copiados simultaneamente, utilizando a capacidade total dos processadores multi-core modernos. Esta abordagem pode reduzir drasticamente o tempo necessário para grandes operações de cópia, pois aproveita os recursos do sistema disponíveis de forma mais eficiente. Embora o cmdlet Copy-Item não suporte nativamente o processamento paralelo, o PowerShell fornece mecanismos como ForEach-Object -Parallel que podem ser usados com Copy-Item para alcançar a cópia de arquivos em paralelo. Isso pode potencialmente proporcionar ganhos substanciais de desempenho em cenários que envolvem numerosos arquivos ou hierarquias de diretórios complexas. Um exemplo básico é mostrado abaixo:

      <$sourcePath = "C:\SourceFolder"
$destPath = "D:\DestinationFolder"
Get-ChildItem $sourcePath | ForEach-Object -Parallel {
    Copy-Item $_.FullName -Destination $using:destPath -Force
} -ThrottleLimit 8
      

Conclusão

O comando cmdlet Copy-Item é uma ferramenta versátil no PowerShell para gerenciar operações de arquivos e diretórios. Possui uma variedade de parâmetros para cobrir múltiplas situações, como a capacidade de especificar um caminho de item de cópia e implementar tratamento de erros. Seja usando script PowerShell para copiar arquivos de origem para destino ou para copiar arquivos localmente ou entre sistemas remotos, o cmdlet Copy-Item pode realizar funções essenciais de cópia de forma eficiente. Considere implementar processamento paralelo para melhorar o desempenho em conjuntos de dados grandes e complexos ou explorar ferramentas especializadas projetadas para lidar com transferências extensivas de dados. Dominar o cmdlet Copy-Item garante transferências de arquivos precisas, tornando-o um componente essencial do kit de ferramentas de qualquer usuário do PowerShell, enquanto entender suas limitações permite tomar decisões informadas sobre quando empregar métodos alternativos.