New-PSDrive

New-PSDrive
    [-Name] <String>
    [-PSProvider] <String>
    [-Root] <String>
    [-Description <String>]
    [-Scope <String>]
    [-Persist]
    [-Credential <PSCredential>]
    [-WhatIf]
    [-Confirm]
    [<CommonParameters>]

O cmdlet New-PSDrive cria unidades temporárias e persistentes mapeadas ou associadas a um local em um armazenamento de dados, como uma unidade de rede, um diretório no computador local ou uma chave de registro e unidades de rede mapeadas persistentes do Windows associadas a um local do sistema de arquivos em um computador remoto.

As unidades temporárias existem apenas na sessão atual do PowerShell e nas sessões criadas na sessão atual. Eles podem ter qualquer nome válido no PowerShell e podem ser mapeados para qualquer recurso local ou remoto. Você pode usar unidades temporárias do PowerShell para acessar dados no armazenamento de dados associado, assim como faria com qualquer unidade de rede mapeada. Você pode alterar os locais na unidade usando Set-Locatione acessar o conteúdo da unidade usando Get-Item ou Get-ChildItem.

Como as unidades temporárias são conhecidas apenas pelo PowerShell, você não pode acessá-las usando o Explorador de Arquivos, a WMI (Instrumentação de Gerenciamento do Windows), o COM (Component Object Model), o Microsoft .NET Framework ou com ferramentas como net use.

Os seguintes recursos foram adicionados ao New-PSDrive no PowerShell 3.0:

• Unidades de rede mapeadas. Você pode usar o parâmetro Persist de New-PSDrive para criar unidades de rede mapeadas do Windows. Ao contrário das unidades temporárias do PowerShell, as unidades de rede mapeadas pelo Windows não são específicas da sessão. Eles são salvos no Windows e podem ser gerenciados usando ferramentas padrão do Windows, como o Explorador de Arquivos e uso de rede. As unidades de rede mapeadas devem ter um nome de letra de unidade e estar conectadas a um local remoto do sistema de arquivos. Quando o comando tem escopo local, sem fornecimento de ponto, o parâmetro Persist não persiste a criação de um PSDrive além do escopo no qual o comando está em execução. Se você estiver executando New-PSDrive dentro de um script e quiser que a unidade persista indefinidamente, você deverá criar o script por ponto. Para obter melhores resultados, para forçar uma nova unidade a persistir indefinidamente, adicione o parâmetro Scope ao seu comando e defina seu valor como Global. Para obter mais informações sobre dot-sourcing, consulte about_Scripts.
• Unidades externas. Quando uma unidade externa é conectada ao computador, o PowerShell adiciona automaticamente um PSDrive ao sistema de arquivos que representa a nova unidade. Você não precisa reiniciar o PowerShell. Da mesma forma, quando uma unidade externa é desconectada do computador, o PowerShell exclui automaticamente o PSDrive que representa a unidade removida.
• Credenciais para caminhos UNC (Convenção Universal de Nomenclatura).

Quando o valor do parâmetro Raiz é um caminho UNC, como \\Server\Share, a credencial especificada no valor do parâmetro de Credenciais é usada para criar o PSDrive. Caso contrário, de credencial não será eficaz quando você estiver criando novas unidades do sistema de arquivos.

Alguns exemplos de código usam splatting para reduzir o comprimento da linha e melhorar a legibilidade. Para obter mais informações, consulte about_Splatting.

Este exemplo cria uma unidade temporária do PowerShell mapeada para um compartilhamento de rede.

New-PSDrive -Name "Public" -PSProvider "FileSystem" -Root "\\Server01\Public"

Name       Provider      Root
----       --------      ----
Public     FileSystem    \\Server01\Public

New-PSDrive usa o parâmetro Name para especificar a unidade do PowerShell chamada Public e o parâmetro PSProvider para especificar o provedor de FileSystem do PowerShell. O parâmetro Raiz especifica o caminho UNC do compartilhamento de rede.

Para exibir o conteúdo de uma sessão do PowerShell: Get-ChildItem -Path Public:

Este exemplo cria uma unidade temporária do PowerShell que fornece acesso a um diretório no computador local.

$parameters = @{
    Name = "MyDocs"
    PSProvider = "FileSystem"
    Root = "C:\Users\User01\Documents"
    Description = "Maps to my My Documents folder."
}
New-PSDrive @parameters

Name        Provider      Root
----        --------      ----
MyDocs      FileSystem    C:\Users\User01\Documents

A splatting cria as chaves de parâmetro e os valores. O parâmetro Name especifica o nome da unidade, myDocs. O parâmetro PSProvider especifica o provedor de FileSystem do PowerShell. raiz especifica o diretório do computador local. O parâmetro de Descrição do descreve a finalidade da unidade. New-PSDrive usa os parâmetros splatted para criar a unidade de MyDocs.

Para exibir o conteúdo de uma sessão do PowerShell: Get-ChildItem -Path MyDocs:

Este exemplo cria uma unidade temporária do PowerShell que fornece acesso a uma chave do Registro. Ele cria uma unidade chamada MyCompany mapeada para a chave do registro HKLM:\Software\MyCompany.

New-PSDrive -Name "MyCompany" -PSProvider "Registry" -Root "HKLM:\Software\MyCompany"

Name           Provider      Root
----           --------      ----
MyCompany      Registry      HKLM:\Software\MyCompany

New-PSDrive usa o parâmetro Name para especificar a unidade do PowerShell chamada MyCompany e o parâmetro PSProvider para especificar o provedor de Registry do PowerShell. O parâmetro Root especifica o local do registro.

Para exibir o conteúdo de uma sessão do PowerShell: Get-ChildItem -Path MyCompany:

Este exemplo mapeia uma unidade de rede autenticada com as credenciais de uma conta de serviço de domínio. Para obter mais informações sobre o objeto PSCredential que armazena credenciais e como as senhas são armazenadas como um SecureString, consulte a descrição do parâmetro Credential.

$cred = Get-Credential -Credential Contoso\ServiceAccount
New-PSDrive -Name "S" -Root "\\Server01\Scripts" -Persist -PSProvider "FileSystem" -Credential $cred
Net Use

Status       Local     Remote                    Network
---------------------------------------------------------
OK           S:        \\Server01\Scripts        Microsoft Windows Network

A variável $cred armazena um objeto PSCredential que contém as credenciais da conta de serviço. Get-Credential solicita que você insira a senha armazenada em um SecureString.

New-PSDrive cria a unidade de rede mapeada usando vários parâmetros. Name especifica a letra da unidade S aceita pelo Windows. e Raiz define \\Server01\Scripts como o local em um computador remoto. Persist cria uma unidade de rede mapeada do Windows salva no computador local. PSProvider especifica o provedor de FileSystem. de Credenciais usa a variável $cred para obter as credenciais da conta de serviço para autenticação.

A unidade mapeada pode ser exibida no computador local em sessões do PowerShell, Explorador de Arquivos e com ferramentas como uso de rede. Para exibir o conteúdo de uma sessão do PowerShell: Get-ChildItem -Path S:

Este exemplo mostra a diferença entre uma unidade de rede mapeada persistente e uma unidade temporária do PowerShell mapeada para o mesmo compartilhamento de rede.

Se você fechar a sessão do PowerShell e abrir uma nova sessão, o PSDrive: temporário não estará disponível, mas a unidade de X: persistente estará disponível. Ao decidir qual método usar para mapear unidades de rede, considere como você usará a unidade. Por exemplo, se ela precisa ser persistente e se a unidade precisa estar visível para outros recursos do Windows.

# Create a temporary PowerShell drive called PSDrive:
# that's mapped to the \\Server01\Public network share.
New-PSDrive -Name "PSDrive" -PSProvider "FileSystem" -Root "\\Server01\Public"

# Use the Persist parameter of New-PSDrive to create the X: mapped network drive,
# which is also mapped to the \\Server01\Public network share.
New-PSDrive -Persist -Name "X" -PSProvider "FileSystem" -Root "\\Server01\Public"

# Now, you can use the Get-PSDrive drive cmdlet to examine the two drives.
# The drives appear to be the same, although the network share name appears only
# in the root of the PSDrive: drive.
Get-PSDrive -Name "PSDrive", "X"

Name       Provider      Root
----       --------      ----

PSDrive    FileSystem    \\Server01\public
X          FileSystem    X:\

# Get-Member cmdlet shows that the drives have the same object type,
# System.Management.Automation.PSDriveInfo.
Get-PSDrive "PSDrive", "x" | Get-Member

TypeName: System.Management.Automation.PSDriveInfo

Name                MemberType   Definition
----                ----------   ----------
CompareTo           Method       System.Int32 CompareTo(PSDriveInfo drive),
Equals              Method       System.Boolean Equals(Object obj),
GetHashCode         Method       System.Int32 GetHashCode()
...

# Net Use and Get-CimInstance for the Win32_LogicalDisk class,
# and Win32_NetworkConnection class find only the persistent X: drive.
# PowerShell temporary drives are known only to PowerShell.
Net Use
Get-CimInstance Win32_LogicalDisk | Format-Table -Property DeviceID
Get-CimInstance Win32_NetworkConnection

Status       Local     Remote                    Network
--------------------------------------------------------
OK           X:        \\contoso-pc\data         Microsoft Windows Network

deviceid
--------
C:
D:
X:

LocalName    RemoteName              ConnectionState          Status
---------    ----------              ---------------          ------
X:           \\products\public       Disconnected             Unavailable

PSDrives são criados no escopo no qual o comando New-PSDrive é executado. Quando o comando é executado dentro de um script, o mapeamento de unidade é local para o script. Quando o script é encerrado, a unidade não está mais disponível.

New-PSDrive -Persist -Name "X" -PSProvider "FileSystem" -Root "\\Server01\Public" -Scope Global

Para garantir que a unidade esteja disponível fora do script, você deve usar o parâmetro Escopo para criar a unidade no escopo Global.

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.

Você não pode redirecionar objetos para este cmdlet

Esse cmdlet retorna um objeto PSDriveInfo que representa a unidade criada.

O PowerShell inclui os seguintes aliases para Get-PSDrive:

• Todas as plataformas:
  • ndr
• Windows:
  • mount

New-PSDrive foi projetado para trabalhar com os dados expostos por qualquer provedor. Para listar os provedores disponíveis em sua sessão, use Get-PSProvider. Para obter mais informações sobre provedores, consulte about_Providers.

As unidades de rede mapeadas são específicas para uma conta de usuário. As unidades mapeadas criadas em sessões ou sessões com privilégios elevados usando a credencial de outro usuário não são visíveis em sessões iniciadas usando credenciais diferentes.