New-PSDrive
Cria unidades temporárias e persistentes associadas a um local em um armazenamento de dados de item.
Syntax
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-PSDriveWindows. 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 executandoNew-PSDrivedentro 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\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 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\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 NetworkNota
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 UnavailableExemplo 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 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 a sua confirmação antes de executar o cmdlet.
| Type: | SwitchParameter |
| Aliases: | cf |
| Position: | Named |
| Default value: | False |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | 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?.
| Type: | PSCredential |
| Position: | Named |
| Default value: | Current user |
| Required: | False |
| Accept pipeline input: | True |
| Accept wildcard characters: | 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.
| Type: | String |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | True |
| Accept wildcard characters: | 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.
| Type: | String |
| Position: | 0 |
| Default value: | None |
| Required: | True |
| Accept pipeline input: | True |
| Accept wildcard characters: | 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.
| Type: | SwitchParameter |
| Position: | Named |
| Default value: | False |
| Required: | False |
| Accept pipeline input: | True |
| Accept wildcard characters: | 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.
| Type: | String |
| Position: | 1 |
| Default value: | None |
| Required: | True |
| Accept pipeline input: | True |
| Accept wildcard characters: | 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.
| Type: | String |
| Position: | 2 |
| Default value: | None |
| Required: | True |
| Accept pipeline input: | True |
| Accept wildcard characters: | 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.
| Type: | String |
| Position: | Named |
| Default value: | Local |
| Required: | False |
| Accept pipeline input: | True |
| Accept wildcard characters: | False |
-WhatIf
Apresenta o que aconteceria mediante a execução do cmdlet. O cmdlet não é executado.
| Type: | SwitchParameter |
| Aliases: | wi |
| Position: | Named |
| Default value: | False |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
Entradas
None
Não é possível canalizar objetos para este cmdlet
Saídas
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
Comentários
Brevemente: Ao longo de 2024, vamos descontinuar progressivamente o GitHub Issues como mecanismo de feedback para conteúdos e substituí-lo por um novo sistema de feedback. Para obter mais informações, veja: https://aka.ms/ContentUserFeedback.
Submeter e ver comentários