Join-String

Módulo:

Microsoft.PowerShell.Utility

Combina objetos do pipeline em uma única cadeia de caracteres.

Sintaxe

Join-String
    [[-Property] <PSPropertyExpression>]
    [[-Separator] <String>]
    [-OutputPrefix <String>]
    [-OutputSuffix <String>]
    [-UseCulture]
    [-InputObject <PSObject[]>]
    [<CommonParameters>]

Join-String
    [[-Property] <PSPropertyExpression>]
    [[-Separator] <String>]
    [-OutputPrefix <String>]
    [-OutputSuffix <String>]
    [-SingleQuote]
    [-UseCulture]
    [-InputObject <PSObject[]>]
    [<CommonParameters>]

Join-String
    [[-Property] <PSPropertyExpression>]
    [[-Separator] <String>]
    [-OutputPrefix <String>]
    [-OutputSuffix <String>]
    [-DoubleQuote]
    [-UseCulture]
    [-InputObject <PSObject[]>]
    [<CommonParameters>]

Join-String
    [[-Property] <PSPropertyExpression>]
    [[-Separator] <String>]
    [-OutputPrefix <String>]
    [-OutputSuffix <String>]
    [-FormatString <String>]
    [-UseCulture]
    [-InputObject <PSObject[]>]
    [<CommonParameters>]

Description

O Join-String cmdlet une ou combina texto de objetos de pipeline em uma única cadeia de caracteres.

Se nenhum parâmetro for especificado, os objetos de pipeline serão convertidos em uma string e unidos com o separador $OFSpadrão.

Observação

Quando você define $OFS seu valor é usado para unir matrizes quando elas são convertidas em strings até que a variável seja redefinida para $null. Como o uso $OFS pode ter efeitos não intencionais em outro lugar em seu código, é melhor usar o parâmetro Separator .

Ao especificar um nome de propriedade, o valor da propriedade é convertido em uma cadeia de caracteres e unido em uma cadeia de caracteres.

Em vez de um nome de propriedade, um bloco de script pode ser usado. O resultado do bloco de script é convertido em uma cadeia de caracteres antes de ser unido para formar o resultado. Ele pode combinar o texto da propriedade de um objeto ou o resultado do objeto que foi convertido em uma cadeia de caracteres.

Esse cmdlet foi introduzido no PowerShell 6.2.

Exemplos

Exemplo 1: Nomes de diretório de junção

Este exemplo une nomes de diretórios, encapsula a saída entre aspas duplas e separa os nomes de diretórios com vírgula e espaço (, ). A saída é um objeto de cadeia de caracteres.

Get-ChildItem -Directory C:\ | Join-String -Property Name -DoubleQuote -Separator ', '

"PerfLogs", "Program Files", "Program Files (x86)", "Users", "Windows"

Get-ChildItem usa o parâmetro Directory para obter todos os nomes de diretório da C:\ unidade. Os objetos são enviados pelo pipeline para Join-String. O parâmetro Property especifica os nomes de diretório. O parâmetro DoubleQuote envolve os nomes de diretório com aspas duplas. O parâmetro Separator especifica o uso de uma vírgula e espaço (, ) para separar os nomes dos diretórios.

Os Get-ChildItem objetos são System.IO.DirectoryInfo e Join-String convertem os objetos em System.String.

Exemplo 2: Usar uma subcadeia de caracteres de propriedade para unir nomes de diretório

Este exemplo usa um método de subcadeia de caracteres para obter as quatro primeiras letras dos nomes de diretório, encapsula a saída entre aspas simples e separa os nomes de diretório com um ponto-e-vírgula (;).

Get-ChildItem -Directory C:\ | Join-String -Property {$_.Name.SubString(0,4)} -SingleQuote -Separator ';'

'Perf';'Prog';'Prog';'User';'Wind'

Get-ChildItem usa o parâmetro Directory para obter todos os nomes de diretório da C:\ unidade. Os objetos são enviados pelo pipeline para Join-String.

O bloco de script de parâmetro Propriedade usa a variável automática ($_) para especificar a subcadeia de caracteres da propriedade Name de cada objeto. A substring obtém as quatro primeiras letras de cada nome de diretório. A subcadeia de caracteres especifica as posições inicial e final do caractere. O parâmetro SingleQuote encapsula os nomes de diretório com aspas simples. O parâmetro Separator especifica o uso de um ponto-e-vírgula (;) para separar os nomes dos diretórios.

Para obter mais informações sobre variáveis automáticas e subcadeias de caracteres, consulte about_Automatic_Variables e Subcadeia de caracteres.

Exemplo 3: Exibir saída de junção em uma linha separada

Este exemplo une nomes de serviço a cada serviço em uma linha separada e recuada por uma guia.

Get-Service -Name se* | Join-String -Property Name -Separator "`r`n`t" -OutputPrefix "Services:`n`t"

Services:
    seclogon
    SecurityHealthService
    SEMgrSvc
    SENS
    Sense
    SensorDataService
    SensorService
    SensrSvc
    SessionEnv

Get-Service usa o parâmetro Name with para especificar serviços que começam com se*. O asterisco (*) é um curinga para qualquer caractere.

Os objetos são enviados pelo pipeline para Join-String que use o parâmetro Property para especificar os nomes de serviço. O parâmetro Separator especifica três caracteres especiais que representam um retorno de carro (`r), uma nova linha (`n) e uma tabulação (`t). O OutputPrefix insere um rótulo Services: com uma nova linha e uma nova guia antes da primeira linha de saída.

Para obter mais informações sobre caracteres especiais, consulte about_Special_Characters.

Exemplo 4: Criar uma definição de classe a partir de um objeto

Este exemplo gera uma definição de classe do PowerShell usando um objeto existente como modelo.

Este exemplo de código usa splatting para reduzir o comprimento da linha e melhorar a legibilidade. Para obter mais informações, consulte about_Splatting.

$obj = [pscustomobject] @{Name = "Joe"; Age = 42}
$parms = @{
  Property = "Name"
  FormatString = '  ${0}'
  OutputPrefix = "class {`n"
  OutputSuffix = "`n}`n"
  Separator = "`n"
}
$obj.PSObject.Properties | Join-String @parms

class {
  $Name
  $Age
}

Parâmetros

-DoubleQuote

Encapsula o valor da cadeia de caracteres de cada objeto de pipeline entre aspas duplas.

Tipo:	SwitchParameter
Cargo:	Named
Valor padrão:	False
Obrigatório:	False
Aceitar a entrada de pipeline:	False
Aceitar caracteres curinga:	False

-FormatString

Especifica uma cadeia de caracteres de formato que especifica como cada objeto de pipeline deve ser formatado antes de juntá-los. Use o espaço reservado {0} para representar o objeto atual. Se você precisar manter as chaves ({}) na cadeia de caracteres formatada, poderá escapar delas dobrando as chaves ({{ e }}).

Para obter mais informações, consulte o método String.Format e Composite Formatting.

Tipo:	String
Cargo:	Named
Valor padrão:	None
Obrigatório:	False
Aceitar a entrada de pipeline:	False
Aceitar caracteres curinga:	False

-InputObject

Especifica o texto a ser unido. Insira uma variável que contenha o texto ou digite um comando ou expressão que faça com que os objetos se juntem em cadeias de caracteres.

Tipo:	PSObject[]
Cargo:	Named
Valor padrão:	None
Obrigatório:	False
Aceitar a entrada de pipeline:	True
Aceitar caracteres curinga:	False

-OutputPrefix

Texto inserido antes da cadeia de caracteres de saída. A cadeia de caracteres pode conter caracteres especiais, como retorno de carro (`r), nova linha (`n) e tabulação (`t).

Tipo:	String
Aliases:	op
Cargo:	Named
Valor padrão:	None
Obrigatório:	False
Aceitar a entrada de pipeline:	False
Aceitar caracteres curinga:	False

-OutputSuffix

Texto acrescentado à cadeia de caracteres de saída. A cadeia de caracteres pode conter caracteres especiais, como retorno de carro (`r), nova linha (`n) e tabulação (`t).

Tipo:	String
Aliases:	os
Cargo:	Named
Valor padrão:	None
Obrigatório:	False
Aceitar a entrada de pipeline:	False
Aceitar caracteres curinga:	False

-Property

O nome de uma propriedade, ou uma expressão de propriedade, a ser convertida em texto.

Tipo:	PSPropertyExpression
Cargo:	0
Valor padrão:	None
Obrigatório:	False
Aceitar a entrada de pipeline:	False
Aceitar caracteres curinga:	False

-Separator

Texto ou caracteres, como uma vírgula ou ponto-e-vírgula, inseridos entre o texto de cada objeto de pipeline.

Por padrão, os objetos de pipeline são unidos sem um separador. Se a variável de preferência Separador de campo de saída ($OFS) estiver definida, esse valor será usado, a menos que esse parâmetro seja especificado.

Observação

Quando você define $OFS seu valor é usado para unir matrizes quando elas são convertidas em strings até que a variável seja redefinida para $null. Como o uso $OFS pode ter efeitos não intencionais em outro lugar em seu código, é melhor usar o parâmetro Separator .

Tipo:	String
Cargo:	1
Valor padrão:	None
Obrigatório:	False
Aceitar a entrada de pipeline:	False
Aceitar caracteres curinga:	False

-SingleQuote

Encapsula o valor da cadeia de caracteres de cada objeto de pipeline entre aspas simples.

Tipo:	SwitchParameter
Cargo:	Named
Valor padrão:	False
Obrigatório:	False
Aceitar a entrada de pipeline:	False
Aceitar caracteres curinga:	False

-UseCulture

Usa o separador de lista para a cultura atual como o delimitador de item. Para localizar o separador de lista de uma cultura, use o seguinte comando: (Get-Culture).TextInfo.ListSeparator.

Tipo:	SwitchParameter
Cargo:	Named
Valor padrão:	False
Obrigatório:	False
Aceitar a entrada de pipeline:	False
Aceitar caracteres curinga:	False

Entradas

PSObject

Saídas

String

Links Relacionados

• about_Automatic_Variables
• about_Special_Characters
• Subcadeia de caracteres