New-PSDrive

Cria unidades temporárias e persistentes associadas a um local em um armazenamento de dados de item.

Sintaxe

New-PSDrive
   [-Name] <String>
   [-PSProvider] <String>
   [-Root] <String>
   [-Description <String>]
   [-Scope <String>]
   [-Persist]
   [-Credential <PSCredential>]
   [-WhatIf]
   [-Confirm]
   [-UseTransaction]
   [<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.

Nota

A menos que você use o parâmetro Scope , PSDrives são criados no escopo no qual o New-PSDrive comando é executado.

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

Nota

Lembre-se, se você usar o trecho acima em um script, defina o valor do parâmetro Scope como "Global" para garantir que a unidade persista fora do escopo atual.

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

Solicita a sua confirmação antes de executar o cmdlet.

Tipo:SwitchParameter
Aliases:cf
Position:Named
Default value:False
Necessário:False
Aceitar entrada de pipeline:False
Aceitar carateres universais:False

-Credential

Especifica uma conta de usuário que tem permissão para executar essa ação. A predefinição é o utilizador atual.

Desde o PowerShell 3.0, quando o valor do parâmetro Root é um caminho UNC, você pode usar credenciais para criar unidades do sistema de arquivos.

Digite um nome de usuário, como User01 ou Domain01\User01, ou insira um objeto PSCredential gerado pelo Get-Credential cmdlet. Se escrever um nome de utilizador, ser-lhe-á pedido que introduza a palavra-passe.

As credenciais são armazenadas em um objeto PSCredential e a senha é armazenada como um SecureString.

Nota

Para obter mais informações sobre a proteção de dados do SecureString , consulte Quão seguro é o SecureString?.

Tipo:PSCredential
Position:Named
Default value:Current user
Necessário:False
Aceitar entrada de pipeline:True
Aceitar carateres universais:False

-Description

Especifica uma breve descrição em texto da unidade. Digite qualquer cadeia de caracteres.

Para ver as descrições de todas as unidades da sessão, Get-PSDrive | Format-Table Name, Description.

Para ver a descrição de uma unidade específica, digite (Get-PSDrive <DriveName>).Description.

Tipo:String
Position:Named
Default value:None
Necessário:False
Aceitar entrada de pipeline:True
Aceitar carateres universais:False

-Name

Especifica um nome para a nova unidade. Para unidades de rede mapeadas persistentes, use uma letra de unidade. Para unidades temporárias do PowerShell, você não está limitado a letras de unidade, use qualquer cadeia de caracteres válida.

Tipo:String
Position:0
Default value:None
Necessário:True
Aceitar entrada de pipeline:True
Aceitar carateres universais:False

-Persist

Indica que esse cmdlet cria uma unidade de rede mapeada do Windows. O parâmetro Persist só está disponível no Windows.

As unidades de rede mapeadas são salvas no Windows no computador local. Eles são persistentes, não específicos da sessão, e podem ser visualizados e gerenciados no Explorador de Arquivos e em outras ferramentas.

Quando você define o escopo do comando localmente, sem dot-sourcing, o parâmetro Persist não persiste a criação de um PSDrive além do escopo no qual você executa o comando. Se você executar New-PSDrive dentro de um script e quiser que a nova unidade persista indefinidamente, você deve dot-source o script. Para obter melhores resultados, para forçar uma nova unidade a persistir, especifique Global como o valor do parâmetro Scope e inclua Persist no comando.

O nome da unidade deve ser uma letra, como D ou E. O valor do parâmetro Root deve ser um caminho UNC de um computador diferente. O valor do parâmetro PSProvider deve ser FileSystem.

Para desconectar uma unidade de rede mapeada do Windows, use o Remove-PSDrive cmdlet. Quando você desconecta uma unidade de rede mapeada do Windows, o mapeamento é excluído permanentemente do computador, não apenas excluído da sessão atual.

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.

Tipo:SwitchParameter
Position:Named
Default value:False
Necessário:False
Aceitar entrada de pipeline:True
Aceitar carateres universais:False

-PSProvider

Especifica o provedor do PowerShell que dá suporte a unidades desse tipo.

Por exemplo, se a unidade estiver associada a um compartilhamento de rede ou diretório do sistema de arquivos, o provedor do PowerShell será FileSystem. Se a unidade estiver associada a uma chave do Registro, o provedor será Registry.

As unidades temporárias do PowerShell podem ser associadas a qualquer provedor do PowerShell. As unidades de rede mapeadas podem ser associadas apenas ao FileSystem provedor.

Para ver uma lista dos provedores em sua sessão do PowerShell, use o Get-PSProvider cmdlet.

Tipo:String
Position:1
Default value:None
Necessário:True
Aceitar entrada de pipeline:True
Aceitar carateres universais:False

-Root

Especifica o local do armazenamento de dados para o qual uma unidade do PowerShell é mapeada.

Por exemplo, especifique um compartilhamento de rede, como \\Server01\Public, um diretório local, como C:\Program Files, ou uma chave do Registro, como HKLM:\Software\Microsoft.

As unidades temporárias do PowerShell podem ser associadas a um local local ou remoto em qualquer unidade de provedor suportada. As unidades de rede mapeadas podem ser associadas apenas a um local do sistema de arquivos em um computador remoto.

Tipo:String
Position:2
Default value:None
Necessário:True
Aceitar entrada de pipeline:True
Aceitar carateres universais:False

-Scope

Especifica um escopo para a unidade. Os valores aceitáveis para esse parâmetro são: Global, Local e Script, ou um número relativo ao escopo atual. Escopos número 0 até o número de escopos. O número de escopo atual é 0 e seu pai é 1. Para obter mais informações, consulte about_Scopes.

Tipo:String
Position:Named
Default value:Local
Necessário:False
Aceitar entrada de pipeline:True
Aceitar carateres universais:False

-UseTransaction

Inclui o comando na transação ativa. Este parâmetro é válido somente quando uma transação está em andamento. Para obter mais informações, consulte about_Transactions.

Tipo:SwitchParameter
Aliases:usetx
Position:Named
Default value:False
Necessário:False
Aceitar entrada de pipeline:False
Aceitar carateres universais:False

-WhatIf

Apresenta o que aconteceria mediante a execução do cmdlet. O cmdlet não é executado.

Tipo:SwitchParameter
Aliases:wi
Position:Named
Default value:False
Necessário:False
Aceitar entrada de pipeline:False
Aceitar carateres universais:False

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 Windows PowerShell inclui os seguintes aliases para New-PSDrive:

  • mount
  • ndr

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.