New-PSDrive

Sintaxe

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

Description

O New-PSDrive cmdlet 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 do 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 que você cria 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-Location, e 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, o 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 PowerShell 3.0:

• Unidades de rede mapeadas. Você pode usar o parâmetro Persist de para criar unidades de rede mapeadas do New-PSDrive 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 o uso da 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 localmente, sem dot-sourcing, o parâmetro Persist não persiste a criação de um PSDrive além do escopo no qual o comando está sendo executado. Se você estiver executando New-PSDrive dentro de um script e quiser que a unidade persista indefinidamente, você deve dot-source o script. Para obter melhores resultados, para forçar uma nova unidade a persistir indefinidamente, adicione o parâmetro Scope ao 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. Não é necessário 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 Root é um caminho UNC, como \\Server\Share, a credencial especificada no valor do parâmetro Credential é usada para criar o PSDrive. Caso contrário, a 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.

Exemplos

Exemplo 1: Criar uma unidade temporária mapeada para um compartilhamento de rede

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-PSDriveusa o parâmetro Name para especificar a unidade do PowerShell nomeada Public e o parâmetro PSProvider para especificar o provedor do PowerShellFileSystem. O parâmetro Root especifica o caminho UNC do compartilhamento de rede.

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

Exemplo 2: Criar uma unidade temporária mapeada para um diretório local

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

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

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

Exemplo 3: Criar uma unidade temporária para uma chave do Registro

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

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

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

New-PSDriveusa o parâmetro Name para especificar a unidade do PowerShell nomeada MyCompany e o parâmetro PSProvider para especificar o provedor do PowerShellRegistry. O parâmetro Root especifica o local do Registro.

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

Exemplo 4: Criar uma unidade de rede mapeada persistente usando credenciais

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 $cred variável 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 que o S Windows aceita. e Root define \\Server01\Scripts como o local em um computador remoto. Persist cria uma unidade de rede mapeada do Windows que é salva no computador local. PSProvider especifica o FileSystem provedor. A credencial usa a $cred variável para obter as credenciais da conta de serviço para autenticação.

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

Exemplo 5: Criar unidades persistentes e temporárias

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

Se você fechar a sessão do PowerShell e, em seguida, abrir uma nova sessão, o temporário PSDrive: não estará disponível, mas a unidade persistente X: estará disponível. Ao decidir qual método usar para mapear unidades de rede, considere como você usará a unidade. Por exemplo, se tem de ser persistente e se a unidade tem de estar visível para outras funcionalidades 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

Exemplo 6: Criar unidade persistente em um script

PSDrives são criados no escopo em que o New-PSDrive comando é executado. Quando o comando é executado dentro de um script, o mapeamento da 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 Scope para criar a unidade no escopo Global .

Parâmetros

-Confirm

-Credential

-Description

-Name

-Persist

-PSProvider

-Root

-Scope

-WhatIf

Entradas

None

Não é possível canalizar objetos para este cmdlet

Saídas

PSDriveInfo

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

Notas

O PowerShell inclui os seguintes aliases para Get-PSDrive:

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

New-PSDrive é 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 de uma conta de usuário. As unidades mapeadas criadas em sessões elevadas ou sessões usando a credencial de outro usuário não são visíveis em sessões iniciadas usando credenciais diferentes.

Ligações Relacionadas

• about_Providers
• Get-Credential
• Get-PSDrive
• Remove-PSDrive