Join-String
Combina objetos do pipeline em uma única cadeia de caracteres.
Sintaxe
Default (Default)
Join-String
[[-Property] <PSPropertyExpression>]
[[-Separator] <String>]
[-OutputPrefix <String>]
[-OutputSuffix <String>]
[-UseCulture]
[-InputObject <PSObject[]>]
[<CommonParameters>]
SingleQuote
Join-String
[[-Property] <PSPropertyExpression>]
[[-Separator] <String>]
[-OutputPrefix <String>]
[-OutputSuffix <String>]
[-SingleQuote]
[-UseCulture]
[-InputObject <PSObject[]>]
[<CommonParameters>]
DoubleQuote
Join-String
[[-Property] <PSPropertyExpression>]
[[-Separator] <String>]
[-OutputPrefix <String>]
[-OutputSuffix <String>]
[-DoubleQuote]
[-UseCulture]
[-InputObject <PSObject[]>]
[<CommonParameters>]
Format
Join-String
[[-Property] <PSPropertyExpression>]
[[-Separator] <String>]
[-OutputPrefix <String>]
[-OutputSuffix <String>]
[-FormatString <String>]
[-UseCulture]
[-InputObject <PSObject[]>]
[<CommonParameters>]
Description
O cmdlet Join-String 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 cadeia de caracteres e unidos ao separador padrão $OFS.
Observação
Quando você define $OFS seu valor é usado para unir matrizes quando elas são convertidas em cadeias de caracteres até que a variável seja redefinida para $null. Como usar $OFS pode ter efeitos não intencionais em outro lugar em seu código, é melhor usar o parâmetro separador de.
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: unir nomes de diretório
Este exemplo une nomes de diretório, encapsula a saída em aspas duplas e separa os nomes de diretório com uma vírgula e um 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 para a unidade de C:\.
Os objetos são enviados pelo pipeline para Join-String. O parâmetro Property especifica os nomes de diretório. O parâmetro DoubleQuote encapsula os nomes de diretório com marcas de aspas duplas.
O parâmetro Separador especifica usar uma vírgula e um espaço (, ) para separar os nomes de diretório.
Os objetos Get-ChildItem são System.IO.DirectoryInfo e Join-String converte 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 de nomes de diretório, encapsula a saída em 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 para a unidade de C:\.
Os objetos são enviados pelo pipeline para Join-String.
O bloco de script do parâmetro Property usa variável automática ($_) para especificar a subcadeia de caracteres de propriedade de nome de cada objeto. A subcadeia de caracteres 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 marcas de aspas simples. O parâmetro separador de especifica usar um ponto-e-vírgula (;) para separar os nomes do diretório.
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 com cada serviço em uma linha separada e recuado 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 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 usa o parâmetro propriedade para especificar os nomes de serviço. O parâmetro Separador especifica três caracteres especiais que representam um retorno de carro (`r), uma nova linha (`n) e uma guia (`t). O OutputPrefix insere um rótulo Services: com uma nova linha e uma 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 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 em aspas duplas.
Propriedades do parâmetro
| Tipo: | SwitchParameter |
| Valor padrão: | False |
| Dá suporte a curingas: | False |
| DontShow: | False |
Conjuntos de parâmetros
DoubleQuote
| Cargo: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline pelo nome da propriedade: | False |
| Valor dos argumentos restantes: | 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 de Formatação Composta.
Propriedades do parâmetro
| Tipo: | String |
| Valor padrão: | None |
| Dá suporte a curingas: | False |
| DontShow: | False |
Conjuntos de parâmetros
Format
| Cargo: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline pelo nome da propriedade: | False |
| Valor dos argumentos restantes: | False |
-InputObject
Especifica o texto a ser ingressado. Insira uma variável que contenha o texto ou digite um comando ou expressão que obtém os objetos a serem unidos em cadeias de caracteres.
Propriedades do parâmetro
| Tipo: | PSObject[] |
| Valor padrão: | None |
| Dá suporte a curingas: | False |
| DontShow: | False |
Conjuntos de parâmetros
(All)
| Cargo: | Named |
| Obrigatório: | False |
| Valor do pipeline: | True |
| Valor do pipeline pelo nome da propriedade: | False |
| Valor dos argumentos restantes: | 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), newline (`n) e tab (`t).
Propriedades do parâmetro
| Tipo: | String |
| Valor padrão: | None |
| Dá suporte a curingas: | False |
| DontShow: | False |
| Aliases: | Op |
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 |
-OutputSuffix
Texto acrescentado à cadeia de caracteres de saída. A cadeia de caracteres pode conter caracteres especiais, como retorno de carro (`r), newline (`n) e tab (`t).
Propriedades do parâmetro
| Tipo: | String |
| 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 |
-Property
O nome de uma propriedade, ou uma expressão de propriedade, a ser convertida em texto.
Propriedades do parâmetro
| Tipo: | PSPropertyExpression |
| Valor padrão: | None |
| Dá suporte a curingas: | False |
| DontShow: | False |
Conjuntos de parâmetros
(All)
| Cargo: | 0 |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline pelo nome da propriedade: | False |
| Valor dos argumentos restantes: | False |
-Separator
Texto ou caracteres, como vírgula ou ponto-e-vírgula inserido entre o texto de cada objeto de pipeline.
Por padrão, os objetos de pipeline são unidos sem um separador. Se o separador de campo de saída variável de preferência ($OFS) for definido, 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 cadeias de caracteres até que a variável seja redefinida para $null. Como usar $OFS pode ter efeitos não intencionais em outro lugar em seu código, é melhor usar o parâmetro separador de.
Propriedades do parâmetro
| Tipo: | String |
| Valor padrão: | None |
| Dá suporte a curingas: | False |
| DontShow: | False |
Conjuntos de parâmetros
(All)
| Cargo: | 1 |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline pelo nome da propriedade: | False |
| Valor dos argumentos restantes: | False |
-SingleQuote
Encapsula o valor da cadeia de caracteres de cada objeto de pipeline entre aspas simples.
Propriedades do parâmetro
| Tipo: | SwitchParameter |
| Valor padrão: | False |
| Dá suporte a curingas: | False |
| DontShow: | False |
Conjuntos de parâmetros
SingleQuote
| Cargo: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline pelo nome da propriedade: | False |
| Valor dos argumentos restantes: | False |
-UseCulture
Usa o separador de lista para a cultura atual como delimitador de item. Para localizar o separador de lista para uma cultura, use o seguinte comando: (Get-Culture).TextInfo.ListSeparator.
Propriedades do parâmetro
| Tipo: | SwitchParameter |
| Valor padrão: | False |
| 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 |
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.