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]
[<CommonParameters>]Description
O New-PSDrive cmdlet cria unidades temporárias e persistentes que são 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 que são 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-Locationo , 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 useo .
Os seguintes recursos foram adicionados no New-PSDrive PowerShell 3.0:
- Unidades de rede mapeadas. Você pode usar o parâmetro Persistir de para criar unidades de rede mapeadas do
New-PSDriveWindows. Ao contrário das unidades temporárias do PowerShell, as unidades de rede mapeadas do 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. Unidades de rede mapeadas devem ter um nome de letra da unidade e estar conectadas a um local de sistema de arquivos remoto. Quando o comando tem escopo local, 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 executandoNew-PSDrivedentro de um script e quiser que a unidade persista indefinidamente, deverá fornecer o script por pontos. 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. 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 de Nomenclatura Universal).
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.
Observação
A menos que você use o parâmetro Scope , os 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\PublicNew-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\DocumentsO 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 espalhados 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 HKLM:\Software\MyCompany chave do Registro.
New-PSDrive -Name "MyCompany" -PSProvider "Registry" -Root "HKLM:\Software\MyCompany"
Name Provider Root
---- -------- ----
MyCompany Registry HKLM:\Software\MyCompanyNew-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 NetworkObservação
Lembre-se de que, se você usar o snippet 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 uma SecureString.
New-PSDrive Cria a unidade de rede mapeada usando vários parâmetros. Nome especifica a letra da S unidade que o Windows aceita. e Root define \\Server01\Scripts como o local em um computador remoto. Persistir 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 exibida 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 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 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 ele deve ser persistente e se a unidade deve ser 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 UnavailableExemplo 6: Criar unidade persistente em um script
Os PSDrives são criados no escopo em que o New-PSDrive comando é executado. Quando o comando é executado em 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 GlobalPara 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 sua confirmação antes de executar o cmdlet.
| Tipo: | SwitchParameter |
| Aliases: | cf |
| Cargo: | Named |
| Valor padrão: | False |
| Obrigatório: | False |
| Aceitar a entrada de pipeline: | False |
| Aceitar caracteres curinga: | False |
-Credential
Especifica uma conta de usuário que tem permissão para executar essa ação. O padrão é o usuário 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 você digitar um nome de usuário, será solicitado que você insira a senha.
As credenciais são armazenadas em um objeto PSCredential e a senha é armazenada como um SecureString.
Observação
Para obter mais informações sobre a proteção de dados do SecureString , consulte Quão seguro é o SecureString?.
| Tipo: | PSCredential |
| Cargo: | Named |
| Valor padrão: | Current user |
| Obrigatório: | False |
| Aceitar a entrada de pipeline: | True |
| Aceitar caracteres curinga: | 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 |
| Cargo: | Named |
| Valor padrão: | None |
| Obrigatório: | False |
| Aceitar a entrada de pipeline: | True |
| Aceitar caracteres curinga: | 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 |
| Cargo: | 0 |
| Valor padrão: | None |
| Obrigatório: | True |
| Aceitar a entrada de pipeline: | True |
| Aceitar caracteres curinga: | False |
-Persist
Indica que esse cmdlet cria uma unidade de rede mapeada do Windows. O parâmetro Persist só está disponível no Windows.
Unidades de rede mapeadas são salvos no Windows no computador local. Eles são persistentes, não específicos da sessão e podem ser exibidos 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, deverá dot-source do script. Para obter melhores resultados, para forçar a persistência de uma nova unidade, especifique Global como o valor do parâmetro Scope e inclua Persist em seu 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 da sessão atual.
Unidades de rede mapeadas são específicas para 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 |
| Cargo: | Named |
| Valor padrão: | False |
| Obrigatório: | False |
| Aceitar a entrada de pipeline: | True |
| Aceitar caracteres curinga: | 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 |
| Cargo: | 1 |
| Valor padrão: | None |
| Obrigatório: | True |
| Aceitar a entrada de pipeline: | True |
| Aceitar caracteres curinga: | 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 com suporte. Unidades de rede mapeadas podem ser associadas somente a um local de sistema de arquivos em um computador remoto.
| Tipo: | String |
| Cargo: | 2 |
| Valor padrão: | None |
| Obrigatório: | True |
| Aceitar a entrada de pipeline: | True |
| Aceitar caracteres curinga: | 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. Os escopos são de 0 a 0 até o número de escopos. O número do escopo atual é 0 e seu pai é 1. Para obter mais informações, consulte about_Scopes.
| Tipo: | String |
| Cargo: | Named |
| Valor padrão: | Local |
| Obrigatório: | False |
| Aceitar a entrada de pipeline: | True |
| Aceitar caracteres curinga: | False |
-WhatIf
Mostra o que aconteceria se o cmdlet fosse executado. O cmdlet não é executado.
| Tipo: | SwitchParameter |
| Aliases: | wi |
| Cargo: | Named |
| Valor padrão: | False |
| Obrigatório: | False |
| Aceitar a entrada de pipeline: | False |
| Aceitar caracteres curinga: | False |
Entradas
None
Você não pode canalizar objetos para esse cmdlet
Saídas
Esse cmdlet retorna um objeto PSDriveInfo que representa a unidade criada.
Observações
O PowerShell inclui os seguintes aliases para Get-PSDrive:
- Todas as plataformas:
ndr
- Windows:
mount
New-PSDrive foi projetado para funcionar com os dados expostos por qualquer provedor. Para listar os provedores disponíveis em sua sessão, use Get-PSProvidero . Para obter mais informações sobre provedores, consulte about_Providers.
Unidades de rede mapeadas são específicas para 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.
