New-Item

Módulo:

Microsoft.PowerShell.Management Module

Cria um novo item.

Sintaxe

pathSet (Default) - All providers

New-Item
    [-Path] <string[]>
    [-ItemType <string>]
    [-Value <Object>]
    [-Force]
    [-Credential <pscredential>]
    [-WhatIf]
    [-Confirm]
    [-UseTransaction]
    [<CommonParameters>]

nameSet - All providers

New-Item
    [[-Path] <string[]>]
    -Name <string>
    [-ItemType <string>]
    [-Value <Object>]
    [-Force]
    [-Credential <pscredential>]
    [-WhatIf]
    [-Confirm]
    [-UseTransaction]
    [<CommonParameters>]

pathSet (Default) - WSMan provider

New-Item
    [-Path] <string[]>
    -ConnectionURI <uri>
    [-ItemType <string>]
    [-Value <Object>]
    [-Force]
    [-Credential <pscredential>]
    [-WhatIf]
    [-Confirm]
    [-UseTransaction]
    [-OptionSet <hashtable>]
    [-Authentication <AuthenticationMechanism>]
    [-CertificateThumbprint <string>]
    [-SessionOption <SessionOption>]
    [-Port <int>]
    [<CommonParameters>]

nameSet - WSMan provider

New-Item
    [[-Path] <string[]>]
    -Name <string>
    [-ItemType <string>]
    [-Value <Object>]
    [-Force]
    [-Credential <pscredential>]
    [-WhatIf]
    [-Confirm]
    [-UseTransaction]
    [-OptionSet <hashtable>]
    [-Authentication <AuthenticationMechanism>]
    [-CertificateThumbprint <string>]
    [-SessionOption <SessionOption>]
    [-ApplicationName <string>]
    [-Port <int>]
    [-UseSSL]
    [<CommonParameters>]

pathSet (Predefinição)

New-Item
    [-Path] <string[]>
    [-ItemType <string>]
    [-Value <Object>]
    [-Force]
    [-Credential <pscredential>]
    [-WhatIf]
    [-Confirm]
    [-UseTransaction]
    [-Options <ScopedItemOptions>]
    [<CommonParameters>]

nameSet

New-Item
    [[-Path] <string[]>]
    -Name <string>
    [-ItemType <string>]
    [-Value <Object>]
    [-Force]
    [-Credential <pscredential>]
    [-WhatIf]
    [-Confirm]
    [-UseTransaction]
    [-Options <ScopedItemOptions>]
    [<CommonParameters>]

Description

O cmdlet New-Item cria um novo item e define seu valor. Os tipos de itens que podem ser criados dependem da localização do item. Por exemplo, no sistema de arquivos, New-Item cria arquivos e pastas. No Registro, New-Item cria chaves e entradas do Registro.

New-Item também pode definir o valor dos itens que cria. Por exemplo, quando ele cria um novo arquivo, New-Item pode adicionar conteúdo inicial ao arquivo.

Exemplos

Exemplo 1: Criar um arquivo no diretório atual

Este comando cria um arquivo de texto chamado "testfile1.txt" no diretório atual. O ponto ('.') no valor do parâmetro Path indica o diretório atual. O texto citado que segue o parâmetro Value é adicionado ao arquivo como conteúdo.

New-Item -Path . -Name "testfile1.txt" -ItemType "File" -Value "This is a text string."

Exemplo 2: Criar um diretório

Este comando cria um diretório chamado "Logfiles" na unidade C:. O parâmetro ItemType especifica que o novo item é um diretório, não um arquivo ou outro objeto do sistema de arquivos.

New-Item -Path "C:\" -Name "logfiles" -ItemType "Directory"

Exemplo 3: Criar um perfil

Este comando cria um perfil do PowerShell no caminho especificado pela variável $PROFILE.

Você pode usar perfis para personalizar o PowerShell. $PROFILE é uma variável automática (interna) que armazena o caminho e o nome do arquivo do perfil "CurrentUser/CurrentHost". Por padrão, o perfil não existe, mesmo que o PowerShell armazene um caminho e um nome de arquivo para ele.

Neste comando, a variável $PROFILE representa o caminho do arquivo. parâmetro ItemType especifica que o comando cria um arquivo. O parâmetro Force permite criar um arquivo no caminho do perfil, mesmo quando os diretórios no caminho não existem.

Depois de criar um perfil, você pode inserir aliases, funções e scripts no perfil para personalizar seu shell.

Para obter mais informações, consulte about_Automatic_Variables e about_Profiles.

New-Item -Path $PROFILE -ItemType "File" -Force

Observação

Quando você cria um arquivo usando esse método, o arquivo resultante é codificado como UTF-8 sem uma marca de ordem de bytes (BOM).

Exemplo 4: Criar um diretório em um diretório diferente

Este exemplo cria um novo diretório Scripts no diretório "C:\PS-Test".

O nome do novo item de diretório, "Scripts", é incluído no valor de parâmetro Path, em vez de ser especificado no valor de Name. Conforme indicado pela sintaxe, qualquer forma de comando é válida.

New-Item -ItemType "Directory" -Path "C:\ps-test\scripts"

Exemplo 5: Criar vários arquivos

Este exemplo cria arquivos em dois diretórios diferentes. Como Path usa várias cadeias de caracteres, você pode usá-lo para criar vários itens.

New-Item -ItemType "File" -Path "C:\ps-test\test.txt", "C:\ps-test\Logs\test.log"

Exemplo 6: Usar curingas para criar arquivos em vários diretórios

O cmdlet New-Item oferece suporte a curingas no parâmetro Path. O comando a seguir cria um arquivo de temp.txt em todos os diretórios especificados pelos curingas no parâmetro Path.

Get-ChildItem -Path C:\Temp\

    Directory:  C:\Temp

Mode                LastWriteTime     Length Name
----                -------------     ------ ----
d-----        5/15/2019   6:45 AM        1   One
d-----        5/15/2019   6:45 AM        1   Two
d-----        5/15/2019   6:45 AM        1   Three

New-Item -Path C:\Temp\* -Name temp.txt -ItemType File | Select-Object FullName

FullName
--------
C:\Temp\One\temp.txt
C:\Temp\Three\temp.txt
C:\Temp\Two\temp.txt

O cmdlet Get-ChildItem mostra três diretórios no diretório C:\Temp. Usando curingas, o cmdlet New-Item cria um arquivo temp.txt em todos os diretórios do diretório atual. O cmdlet New-Item gera a saída dos itens criados, que são canalizados para Select-Object para verificar os caminhos dos arquivos recém-criados.

Exemplo 7: Criar um link simbólico para um arquivo ou pasta

Este exemplo cria um link simbólico para o arquivo Notice.txt na pasta atual.

$link = New-Item -ItemType SymbolicLink -Path .\link -Target .\Notice.txt
$link | Select-Object LinkType, Target

LinkType     Target
--------     ------
SymbolicLink {.\Notice.txt}

Neste exemplo, Target é um alias para o parâmetro Value. O alvo da ligação simbólica deve ser um caminho plenamente qualificado.

Exemplo 8: Use o parâmetro -Force para tentar recriar pastas

Este exemplo cria uma pasta com um arquivo dentro. Em seguida, tenta criar a mesma pasta usando -Force. Ele não substituirá a pasta, mas simplesmente retornará o objeto de pasta existente com o arquivo criado intacto.

PS> New-Item -Path .\TestFolder -ItemType Directory
PS> New-Item -Path .\TestFolder\TestFile.txt -ItemType File

PS> New-Item -Path .\TestFolder -ItemType Directory -Force

    Directory: C:\
Mode                LastWriteTime         Length Name
----                -------------         ------ ----
d-----         5/1/2020   8:03 AM                TestFolder

PS> Get-ChildItem .\TestFolder\

    Directory: C:\TestFolder
Mode                LastWriteTime         Length Name
----                -------------         ------ ----
-a----         5/1/2020   8:03 AM              0 TestFile.txt

Exemplo 9: Use o parâmetro -Force para substituir arquivos existentes

Este exemplo cria um arquivo com um valor e, em seguida, recria o arquivo usando -Force. Isso substitui o arquivo existente, como você pode ver pela propriedade Length.

PS> New-Item ./TestFile.txt -ItemType File -Value 'This is just a test file'

    Directory: C:\Source\Test
Mode                LastWriteTime         Length Name
----                -------------         ------ ----
-a----         5/1/2020   8:32 AM             24 TestFile.txt

New-Item ./TestFile.txt -ItemType File -Force

    Directory: C:\Source\Test
Mode                LastWriteTime         Length Name
----                -------------         ------ ----
-a----         5/1/2020   8:32 AM              0 TestFile.txt

Observação

Ao usar New-Item com a opção -Force para criar chaves do Registro, o comando se comportará da mesma forma que ao substituir um arquivo. Se a chave do Registro já existir, a chave e todas as propriedades e valores serão substituídos por uma chave do Registro vazia.

Parâmetros

-ApplicationName

Este é um parâmetro dinâmico disponibilizado pelo provedor WSMan. O provedor de WSMan e esse parâmetro só estão disponíveis no Windows.

Especifica o nome do aplicativo na conexão. O valor padrão do parâmetro ApplicationName é WSMAN.

Para obter mais informações, consulte New-WSManInstance.

Propriedades dos parâmetros

Tipo:	String
Default value:	None
Suporta carateres universais:	False
NãoMostrar:	False

Conjuntos de parâmetros

nameSet

Position:	Named
Obrigatório:	False
Valor do pipeline:	False
Valor do pipeline por nome de propriedade:	False
Valor dos restantes argumentos:	False

-Authentication

Este é um parâmetro dinâmico disponibilizado pelo provedor WSMan. O provedor de WSMan e esse parâmetro só estão disponíveis no Windows.

Especifica o mecanismo de autenticação a ser usado no servidor.

Para obter mais informações, consulte New-WSManInstance.

Propriedades dos parâmetros

Tipo:	AuthenticationMechanism
Default value:	None
Suporta carateres universais:	False
NãoMostrar:	False

Conjuntos de parâmetros

(All)

Position:	Named
Obrigatório:	False
Valor do pipeline:	False
Valor do pipeline por nome de propriedade:	False
Valor dos restantes argumentos:	False

-CertificateThumbprint

Este é um parâmetro dinâmico disponibilizado pelo provedor WSMan. O provedor de WSMan e esse parâmetro só estão disponíveis no Windows.

Especifica o certificado de chave pública digital (X509) de uma conta de usuário que tem permissão para executar essa ação WSMan. Insira a impressão digital (thumbprint) do certificado.

Para obter mais informações, consulte New-WSManInstance.

Propriedades dos parâmetros

Tipo:	String
Default value:	None
Suporta carateres universais:	False
NãoMostrar:	False

Conjuntos de parâmetros

(All)

Position:	Named
Obrigatório:	False
Valor do pipeline:	False
Valor do pipeline por nome de propriedade:	False
Valor dos restantes argumentos:	False

-Confirm

Solicita confirmação antes de executar o cmdlet.

Propriedades dos parâmetros

Tipo:	SwitchParameter
Default value:	False
Suporta carateres universais:	False
NãoMostrar:	False
Aliases:	Cf.

Conjuntos de parâmetros

(All)

Position:	Named
Obrigatório:	False
Valor do pipeline:	False
Valor do pipeline por nome de propriedade:	False
Valor dos restantes argumentos:	False

-ConnectionURI

Este é um parâmetro dinâmico disponibilizado pelo provedor WSMan. O provedor de WSMan e esse parâmetro só estão disponíveis no Windows.

Especifica o ponto de extremidade de conexão para o WSMan.

Para obter mais informações, consulte New-WSManInstance.

Propriedades dos parâmetros

Tipo:	Uri
Default value:	None
Suporta carateres universais:	False
NãoMostrar:	False

Conjuntos de parâmetros

pathSet

Position:	Named
Obrigatório:	True
Valor do pipeline:	False
Valor do pipeline por nome de propriedade:	False
Valor dos restantes argumentos:	False

-Credential

Observação

Esse parâmetro não é suportado por nenhum provedor instalado com o PowerShell. Para representar outro usuário ou elevar suas credenciais ao executar este cmdlet, use Invoke-Command.

Propriedades dos parâmetros

Tipo:	PSCredential
Default value:	Current user
Suporta carateres universais:	False
NãoMostrar:	False

Conjuntos de parâmetros

(All)

Position:	Named
Obrigatório:	False
Valor do pipeline:	False
Valor do pipeline por nome de propriedade:	True
Valor dos restantes argumentos:	False

-Force

Força esse cmdlet a criar um item que grava sobre um item somente leitura existente. A implementação varia de fornecedor para fornecedor. Mesmo usando o parâmetro Force, o cmdlet não consegue ultrapassar restrições de segurança.

Não é possível usar Force para substituir uma junção existente. As tentativas de substituir uma junção existente falham com um erro "não pode ser removido porque não está vazio". Você deve remover a junção existente antes de criar uma nova.

Propriedades dos parâmetros

Tipo:	SwitchParameter
Default value:	None
Suporta carateres universais:	False
NãoMostrar:	False

Conjuntos de parâmetros

(All)

Position:	Named
Obrigatório:	False
Valor do pipeline:	False
Valor do pipeline por nome de propriedade:	False
Valor dos restantes argumentos:	False

-ItemType

Especifica o tipo especificado pelo provedor do novo item. Os valores disponíveis desse parâmetro dependem do provedor atual que você está usando.

Se a sua localização estiver numa unidade FileSystem, são permitidos os seguintes valores:

• File
• Directory
• SymbolicLink
• Junction
• HardLink

Quando você cria um arquivo usando esse método, o arquivo resultante é codificado como UTF-8 sem uma marca de ordem de bytes (BOM).

Em uma unidade Certificate, estes são os valores que você pode especificar:

• Certificate Provider
• Certificate
• Store
• StoreLocation

Para obter mais informações, consulte about_Providers.

Propriedades dos parâmetros

Tipo:	String
Default value:	None
Suporta carateres universais:	False
NãoMostrar:	False
Aliases:	Tipo

Conjuntos de parâmetros

(All)

Position:	Named
Obrigatório:	False
Valor do pipeline:	False
Valor do pipeline por nome de propriedade:	True
Valor dos restantes argumentos:	False

-Name

Especifica o nome do novo item. Você pode especificar o nome do novo item no Nome do ou valor do parâmetro Caminho e pode especificar o caminho do novo item em Nome ou valor Caminho. Os nomes de itens passados usando o parâmetro Name são criados em relação ao valor do parâmetro Path.

Propriedades dos parâmetros

Tipo:	String
Default value:	None
Suporta carateres universais:	False
NãoMostrar:	False

Conjuntos de parâmetros

nameSet

Position:	Named
Obrigatório:	True
Valor do pipeline:	False
Valor do pipeline por nome de propriedade:	True
Valor dos restantes argumentos:	False

-Options

Este é um parâmetro dinâmico disponibilizado pelo provedor Alias. Para obter mais informações, consulte New-Alias.

Especifica o valor da propriedade Opções de um alias.

Os valores válidos são:

• None: O alias não tem restrições (valor padrão)
• ReadOnly: O alias pode ser excluído, mas não pode ser alterado sem usar o parâmetro Force
• Constant: O alias não pode ser excluído ou alterado
• Private: O alias está disponível apenas no âmbito atual
• AllScope: O alias é copiado para quaisquer novos escopos que são criados
• Unspecified: A opção não está especificada

Propriedades dos parâmetros

Tipo:	ScopedItemOptions
Default value:	None
Suporta carateres universais:	False
NãoMostrar:	False

Conjuntos de parâmetros

(All)

Position:	Named
Obrigatório:	False
Valor do pipeline:	False
Valor do pipeline por nome de propriedade:	False
Valor dos restantes argumentos:	False

-OptionSet

Este é um parâmetro dinâmico disponibilizado pelo provedor WSMan. O provedor de WSMan e esse parâmetro só estão disponíveis no Windows.

Passa um conjunto de opções para um serviço para modificar ou refinar a natureza da solicitação.

Para obter mais informações, consulte New-WSManInstance.

Propriedades dos parâmetros

Tipo:	Hashtable
Default value:	None
Suporta carateres universais:	False
NãoMostrar:	False
Aliases:	Sistema Operativo

Conjuntos de parâmetros

(All)

Position:	Named
Obrigatório:	False
Valor do pipeline:	False
Valor do pipeline por nome de propriedade:	False
Valor dos restantes argumentos:	False

-Path

Especifica o caminho do local do novo item. O padrão é o local atual quando de caminho é omitido. Você pode especificar o nome do novo item em Nomeou incluí-lo em Caminho. Os nomes de itens passados usando o parâmetro Name são criados em relação ao valor do parâmetro Path.

Para este cmdlet, o parâmetro Path funciona como o parâmetro LiteralPath de outros cmdlets. Os caracteres curinga não são interpretados. Todos os caracteres são passados para o provedor do local. O provedor pode não suportar todos os caracteres. Por exemplo, não é possível criar um nome de arquivo que contenha um caractere de asterisco (*).

Propriedades dos parâmetros

Tipo:	String[]
Default value:	Current location
Suporta carateres universais:	False
NãoMostrar:	False

Conjuntos de parâmetros

pathSet

Position:	0
Obrigatório:	True
Valor do pipeline:	False
Valor do pipeline por nome de propriedade:	True
Valor dos restantes argumentos:	False

nameSet

Position:	0
Obrigatório:	False
Valor do pipeline:	False
Valor do pipeline por nome de propriedade:	True
Valor dos restantes argumentos:	False

-Port

Este é um parâmetro dinâmico disponibilizado pelo provedor WSMan. O provedor de WSMan e esse parâmetro só estão disponíveis no Windows.

Especifica a porta a ser usada quando o cliente se conecta ao serviço WinRM.

Para obter mais informações, consulte New-WSManInstance.

Propriedades dos parâmetros

Tipo:	Int32
Default value:	None
Suporta carateres universais:	False
NãoMostrar:	False

Conjuntos de parâmetros

(All)

Position:	Named
Obrigatório:	True
Valor do pipeline:	False
Valor do pipeline por nome de propriedade:	False
Valor dos restantes argumentos:	False

-SessionOption

Este é um parâmetro dinâmico disponibilizado pelo provedor WSMan. O provedor de WSMan e esse parâmetro só estão disponíveis no Windows.

Define um conjunto de opções estendidas para a sessão WS-Management.

Para obter mais informações, consulte New-WSManInstance.

Propriedades dos parâmetros

Tipo:	SessionOption
Default value:	None
Suporta carateres universais:	False
NãoMostrar:	False
Aliases:	ENTÃO

Conjuntos de parâmetros

(All)

Position:	Named
Obrigatório:	False
Valor do pipeline:	False
Valor do pipeline por nome de propriedade:	False
Valor dos restantes argumentos:	False

-UseSSL

Este é um parâmetro dinâmico disponibilizado pelo provedor WSMan. O provedor de WSMan e esse parâmetro só estão disponíveis no Windows.

Especifica que o protocolo SSL (Secure Sockets Layer) deve ser usado para estabelecer uma conexão com o computador remoto. Por padrão, o SSL não é usado.

Para obter mais informações, consulte New-WSManInstance.

Propriedades dos parâmetros

Tipo:	SwitchParameter
Default value:	None
Suporta carateres universais:	False
NãoMostrar:	False

Conjuntos de parâmetros

nameSet

Position:	Named
Obrigatório:	False
Valor do pipeline:	False
Valor do pipeline por nome de propriedade:	False
Valor dos restantes argumentos:	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.

Propriedades dos parâmetros

Tipo:	SwitchParameter
Default value:	False
Suporta carateres universais:	False
NãoMostrar:	False
Aliases:	Usetx

Conjuntos de parâmetros

(All)

Position:	Named
Obrigatório:	False
Valor do pipeline:	False
Valor do pipeline por nome de propriedade:	False
Valor dos restantes argumentos:	False

-Value

Especifica o valor do novo item. Você também pode canalizar um valor para New-Item.

Propriedades dos parâmetros

Tipo:	Object
Default value:	None
Suporta carateres universais:	False
NãoMostrar:	False
Aliases:	Objetivo

Conjuntos de parâmetros

(All)

Position:	Named
Obrigatório:	False
Valor do pipeline:	True
Valor do pipeline por nome de propriedade:	True
Valor dos restantes argumentos:	False

-WhatIf

Mostra o que aconteceria se o cmdlet fosse executado. O cmdlet não é executado.

Propriedades dos parâmetros

Tipo:	SwitchParameter
Default value:	False
Suporta carateres universais:	False
NãoMostrar:	False
Aliases:	Wi

Conjuntos de parâmetros

(All)

Position:	Named
Obrigatório:	False
Valor do pipeline:	False
Valor do pipeline por nome de propriedade:	False
Valor dos restantes argumentos:	False

CommonParameters

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.

Entradas

Object

Você pode canalizar um valor para o novo item para este cmdlet.

Saídas

DictionaryEntry

O cmdlet retorna um objeto DictionaryEntry ao criar uma nova variável de ambiente.

DirectoryInfo

O cmdlet retorna um objeto DirectoryInfo ao criar um novo diretório no sistema de arquivos.

FileInfo

O cmdlet retorna um objeto FileInfo ao criar um novo arquivo no sistema de arquivos.

AliasInfo

O cmdlet retorna um objeto AliasInfo ao criar um novo alias.

FunctionInfo

O cmdlet retorna um objeto FunctionInfo ao criar uma nova função.

PSVariable

O cmdlet retorna um objeto PSVariable ao criar uma nova variável.

Notas

O Windows PowerShell inclui os seguintes aliases para New-Item:

• ni

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

Ligações Relacionadas

• Clear-Item
• Copy-Item
• Get-Item
• Invoke-Item
• Move-Item
• Remove-Item
• Renomear-Item
• Set-Item
• sobre_Fornecedores