[PowerShell] 87. Copy-Item -ToSession/-FromSession — 원격 파일 전송

개요

Copy-Item의 -ToSession/-FromSession 동적 매개변수는 34장에서 배운 파일 복사 cmdlet을, 86장의 지속 세션을 통해 로컬과 원격 컴퓨터 사이의 파일 전송으로 확장한다. 이 두 매개변수는 FileSystem 프로바이더가 제공하는 동적 매개변수(38장에서 다룬 개념)라, Get-Help Copy-Item -Full의 기본 출력에는 안 보이다가 실제로 파일 시스템 경로에 대해 쓸 때만 나타난다.

정신 모델은 “-ToSession은 로컬 파일을 원격으로 밀어 넣는(push) 것이고, -FromSession은 원격 파일을 로컬로 끌어오는(pull) 것"이라는 것이다. 두 경우 모두 84–86장에서 만든 지속 세션이 실제 파일 데이터가 오가는 통로가 된다.

사용법

1
2

Copy-Item -Path <로컬경로> -Destination <원격경로> -ToSession <세션>
Copy-Item -Path <원격경로> -Destination <로컬경로> -FromSession <세션>

종류

예시

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

$Session = New-PSSession -ComputerName "Server01" -Credential "Contoso\User01"   # 86장에서 만든 세션

Copy-Item "D:\Folder001\test.log" -Destination "C:\Folder001_Copy\" -ToSession $Session   # 로컬 → 원격

Copy-Item "D:\Folder002\" -Destination "C:\Folder002_Copy\" -ToSession $Session -Recurse    # 디렉터리 전체

Copy-Item "C:\MyRemoteData\test.log" -Destination "D:\MyLocalData\" -FromSession $Session   # 원격 → 로컬

$copyParams = @{
    Path        = "D:\Folder004\scriptingexample.ps1"
    Destination = "C:\Folder004_Copy\scriptingexample_copy.ps1"    # 복사하며 이름도 함께 변경
    ToSession   = $Session
}
Copy-Item @copyParams

Copy-Item "C:\MyRemoteData\scripts" -Destination "D:\MyLocalData\" -FromSession $Session -Recurse   # 원격 폴더 통째로 회수

주의사항·함정

-ToSession/-FromSession은 Get-Help의 기본 출력에 보이지 않는 동적 매개변수다: 38장에서 배운 것처럼, 이 매개변수들은 FileSystem 프로바이더가 실제 파일 시스템 경로를 다룰 때만 나타난다. 문서에서 처음 찾으려 하면 안 보여서 당황할 수 있는데, Get-Help Copy-Item -Full을 실제 파일 시스템 경로와 함께 확인하거나 이 장의 예시처럼 그대로 쓰면 된다.

-Path와 -Destination이 각각 로컬인지 원격인지는 어느 매개변수를 쓰느냐에 따라 반대로 해석된다: -ToSession을 쓸 때는 -Path가 로컬, -Destination이 원격이지만, -FromSession을 쓰면 정반대로 -Path가 원격, -Destination이 로컬이 된다. 이 방향을 헷갈리면 엉뚱한 위치에서 파일을 찾거나 엉뚱한 곳에 파일을 만드는 실수로 이어지기 쉽다.

대용량 파일 전송은 WinRM의 기본 전송 제한에 걸릴 수 있다: WS-Management 프로토콜은 기본적으로 한 번에 전송할 수 있는 데이터 크기에 제한이 있어, 매우 큰 파일을 전송하면 실패하거나 매우 느릴 수 있다. 대용량 파일이라면 New-PSSessionOption -MaximumReceivedDataSizePerCommand 같은 세션 옵션을 조정하거나, 네트워크 공유 폴더처럼 WinRM을 거치지 않는 다른 전송 방법을 고려해야 한다.

-Recurse 없이 디렉터리를 복사하면 폴더만 만들어지고 내용은 비어 있다: 34장에서 배운 로컬 Copy-Item의 규칙이 세션 전송에도 그대로 적용된다 — 디렉터리 자체는 생성되지만 그 안의 파일·하위 폴더까지 함께 옮기려면 반드시 -Recurse를 명시해야 한다.

이식성: scp(Secure Copy Protocol)가 SSH 기반으로 원격 파일을 주고받는 것과 정확히 같은 목적을 수행한다 — 88장에서 SSH Remoting을 다루고 나면, Copy-Item -ToSession을 SSH 기반 세션에도 적용해 scp와 매우 비슷한 사용자 경험을 얻을 수 있다. CMD에는 표준화된 원격 파일 복사 명령이 없어 공유 폴더 매핑이나 robocopy 같은 별도 도구에 의존해야 한다.

Reference

• Copy-Item (Microsoft.PowerShell.Management) - PowerShell | Microsoft Learn