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 (Default)

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 ele 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

Esse 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 entre aspas 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

Esse 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

Esse 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, embora o PowerShell armazene um caminho e um nome de arquivo para ele.

Nesse 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 o 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 um BOM (byte-order-mark).

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", está incluído no valor do parâmetro caminho , em vez de ser especificado no valor de Name. Conforme indicado pela sintaxe, qualquer formulário de comando é válido.

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 Caminho usa várias cadeias de caracteres, você pode usá-la 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 dá suporte a curingas no parâmetro Path. O comando a seguir cria um arquivo temp.txt em todos os diretórios especificados pelos curingas no parâmetro caminho.

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 no diretório atual. O cmdlet New-Item gera os itens que você criou, 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, de destino é um alias para o parâmetro value. O destino do link simbólico deve ser um caminho totalmente qualificado.

Exemplo 8: Usar 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: Usar o parâmetro -Force para substituir arquivos existentes

Este exemplo cria um arquivo com um valor e 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 com uma chave vazia do Registro.

Parâmetros

-ApplicationName

Esse é um parâmetro dinâmico disponibilizado pelo provedor de do 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 do parâmetro

Tipo:	String
Valor padrão:	None
Dá suporte a curingas:	False
DontShow:	False

Conjuntos de parâmetros

nameSet

Cargo:	Named
Obrigatório:	False
Valor do pipeline:	False
Valor do pipeline pelo nome da propriedade:	False
Valor dos argumentos restantes:	False

-Authentication

Esse é um parâmetro dinâmico disponibilizado pelo provedor de do 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 do parâmetro

Tipo:	AuthenticationMechanism
Valor padrão:	None
Dá suporte a curingas:	False
DontShow:	False

Conjuntos de parâmetros

(All)

Cargo:	Named
Obrigatório:	False
Valor do pipeline:	False
Valor do pipeline pelo nome da propriedade:	False
Valor dos argumentos restantes:	False

-CertificateThumbprint

Esse é um parâmetro dinâmico disponibilizado pelo provedor de do 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 do WSMan. Insira a impressão digital do certificado.

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

Propriedades do parâmetro

Tipo:	String
Valor padrão:	None
Dá suporte a curingas:	False
DontShow:	False

Conjuntos de parâmetros

(All)

Cargo:	Named
Obrigatório:	False
Valor do pipeline:	False
Valor do pipeline pelo nome da propriedade:	False
Valor dos argumentos restantes:	False

-Confirm

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

Propriedades do parâmetro

Tipo:	SwitchParameter
Valor padrão:	False
Dá suporte a curingas:	False
DontShow:	False
Aliases:	cf

Conjuntos de parâmetros

(All)

Cargo:	Named
Obrigatório:	False
Valor do pipeline:	False
Valor do pipeline pelo nome da propriedade:	False
Valor dos argumentos restantes:	False

-ConnectionURI

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

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

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

Propriedades do parâmetro

Tipo:	Uri
Valor padrão:	None
Dá suporte a curingas:	False
DontShow:	False

Conjuntos de parâmetros

pathSet

Cargo:	Named
Obrigatório:	True
Valor do pipeline:	False
Valor do pipeline pelo nome da propriedade:	False
Valor dos argumentos restantes:	False

-Credential

Observação

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

Propriedades do parâmetro

Tipo:	PSCredential
Valor padrão:	Current user
Dá suporte a curingas:	False
DontShow:	False

Conjuntos de parâmetros

(All)

Cargo:	Named
Obrigatório:	False
Valor do pipeline:	False
Valor do pipeline pelo nome da propriedade:	True
Valor dos argumentos restantes:	False

-Force

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

Você não pode usar a Força 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 do parâmetro

Tipo:	SwitchParameter
Valor padrão:	None
Dá suporte a curingas:	False
DontShow:	False

Conjuntos de parâmetros

(All)

Cargo:	Named
Obrigatório:	False
Valor do pipeline:	False
Valor do pipeline pelo nome da propriedade:	False
Valor dos argumentos restantes:	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 sua localização estiver em uma unidade de FileSystem, os seguintes valores serão permitidos:

• File
• Directory
• SymbolicLink
• Junction
• HardLink

Quando você cria um arquivo usando esse método, o arquivo resultante é codificado como UTF-8 sem um BOM (byte-order-mark).

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

• Certificate Provider
• Certificate
• Store
• StoreLocation

Para obter mais informações, consulte about_Providers.

Propriedades do parâmetro

Tipo:	String
Valor padrão:	None
Dá suporte a curingas:	False
DontShow:	False
Aliases:	Tipo

Conjuntos de parâmetros

(All)

Cargo:	Named
Obrigatório:	False
Valor do pipeline:	False
Valor do pipeline pelo nome da propriedade:	True
Valor dos argumentos restantes:	False

-Name

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

Propriedades do parâmetro

Tipo:	String
Valor padrão:	None
Dá suporte a curingas:	False
DontShow:	False

Conjuntos de parâmetros

nameSet

Cargo:	Named
Obrigatório:	True
Valor do pipeline:	False
Valor do pipeline pelo nome da propriedade:	True
Valor dos argumentos restantes:	False

-Options

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

Especifica o valor da propriedade Options 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 somente no escopo atual.
• AllScope: o alias é copiado para qualquer novo escopo criado.
• Unspecified: a opção não está especificada

Propriedades do parâmetro

Tipo:	ScopedItemOptions
Valor padrão:	None
Dá suporte a curingas:	False
DontShow:	False

Conjuntos de parâmetros

(All)

Cargo:	Named
Obrigatório:	False
Valor do pipeline:	False
Valor do pipeline pelo nome da propriedade:	False
Valor dos argumentos restantes:	False

-OptionSet

Esse é um parâmetro dinâmico disponibilizado pelo provedor de do 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 do parâmetro

Tipo:	Hashtable
Valor padrão:	None
Dá suporte a curingas:	False
DontShow:	False
Aliases:	Sistema operacional

Conjuntos de parâmetros

(All)

Cargo:	Named
Obrigatório:	False
Valor do pipeline:	False
Valor do pipeline pelo nome da propriedade:	False
Valor dos argumentos restantes:	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 Nameou incluí-lo no Path. Os nomes de itens passados usando o parâmetro nome do são criados em relação ao valor do parâmetro caminho.

Para esse cmdlet, o parâmetro Path funciona como o parâmetro LiteralPath de outros cmdlets. Caracteres curinga não são interpretados. Todos os caracteres são passados para o provedor do local. O provedor pode não dar suporte a todos os caracteres. Por exemplo, você não pode criar um nome de arquivo que contenha um caractere asterisco (*).

Propriedades do parâmetro

Tipo:	String[]
Valor padrão:	Current location
Dá suporte a curingas:	False
DontShow:	False

Conjuntos de parâmetros

pathSet

Cargo:	0
Obrigatório:	True
Valor do pipeline:	False
Valor do pipeline pelo nome da propriedade:	True
Valor dos argumentos restantes:	False

nameSet

Cargo:	0
Obrigatório:	False
Valor do pipeline:	False
Valor do pipeline pelo nome da propriedade:	True
Valor dos argumentos restantes:	False

-Port

Esse é um parâmetro dinâmico disponibilizado pelo provedor de do 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 do parâmetro

Tipo:	Int32
Valor padrão:	None
Dá suporte a curingas:	False
DontShow:	False

Conjuntos de parâmetros

(All)

Cargo:	Named
Obrigatório:	True
Valor do pipeline:	False
Valor do pipeline pelo nome da propriedade:	False
Valor dos argumentos restantes:	False

-SessionOption

Esse é um parâmetro dinâmico disponibilizado pelo provedor de do 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 de WS-Management.

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

Propriedades do parâmetro

Tipo:	SessionOption
Valor padrão:	None
Dá suporte a curingas:	False
DontShow:	False
Aliases:	SO

Conjuntos de parâmetros

(All)

Cargo:	Named
Obrigatório:	False
Valor do pipeline:	False
Valor do pipeline pelo nome da propriedade:	False
Valor dos argumentos restantes:	False

-UseSSL

Esse é um parâmetro dinâmico disponibilizado pelo provedor de do 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 do parâmetro

Tipo:	SwitchParameter
Valor padrão:	None
Dá suporte a curingas:	False
DontShow:	False

Conjuntos de parâmetros

nameSet

Cargo:	Named
Obrigatório:	False
Valor do pipeline:	False
Valor do pipeline pelo nome da propriedade:	False
Valor dos argumentos restantes:	False

-UseTransaction

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

Propriedades do parâmetro

Tipo:	SwitchParameter
Valor padrão:	False
Dá suporte a curingas:	False
DontShow:	False
Aliases:	usetx

Conjuntos de parâmetros

(All)

Cargo:	Named
Obrigatório:	False
Valor do pipeline:	False
Valor do pipeline pelo nome da propriedade:	False
Valor dos argumentos restantes:	False

-Value

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

Propriedades do parâmetro

Tipo:	Object
Valor padrão:	None
Dá suporte a curingas:	False
DontShow:	False
Aliases:	Meta

Conjuntos de parâmetros

(All)

Cargo:	Named
Obrigatório:	False
Valor do pipeline:	True
Valor do pipeline pelo nome da propriedade:	True
Valor dos argumentos restantes:	False

-WhatIf

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

Propriedades do parâmetro

Tipo:	SwitchParameter
Valor padrão:	False
Dá suporte a curingas:	False
DontShow:	False
Aliases:	wi

Conjuntos de parâmetros

(All)

Cargo:	Named
Obrigatório:	False
Valor do pipeline:	False
Valor do pipeline pelo nome da propriedade:	False
Valor dos argumentos restantes:	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 redirecionar 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.

Observações

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

• ni

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

Links Relacionados

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