Out-String
Gera objetos de entrada como uma cadeia de caracteres.
Sintaxe
NoNewLineFormatting (Padrão)
Out-String
[-Width <Int32>]
[-NoNewline]
[-InputObject <PSObject>]
[<CommonParameters>]
StreamFormatting
Out-String
[-Stream]
[-Width <Int32>]
[-InputObject <PSObject>]
[<CommonParameters>]
Description
O cmdlet Out-String converte objetos de entrada em cadeias de caracteres. Por padrão, Out-String acumula as cadeias de caracteres e as retorna como uma única cadeia de caracteres, mas você pode usar o parâmetro Stream para direcionar Out-String retornar uma linha de cada vez ou criar uma matriz de cadeias de caracteres. Esse cmdlet permite que você pesquise e manipule a saída da cadeia de caracteres como faria em shells tradicionais quando a manipulação de objeto é menos conveniente.
O PowerShell também adiciona a função oss que chama Out-String -Stream como uma maneira abreviada de usar Out-String em um pipeline.
Exemplos
Exemplo 1: Obter a cultura atual e converter os dados em cadeias de caracteres
Este exemplo obtém as configurações regionais do usuário atual e converte os dados do objeto em cadeias de caracteres.
$C = Get-Culture | Select-Object -Property *
Out-String -InputObject $C -Width 100
Parent : en
LCID : 1033
KeyboardLayoutId : 1033
Name : en-US
IetfLanguageTag : en-US
DisplayName : English (United States)
NativeName : English (United States)
EnglishName : English (United States)
TwoLetterISOLanguageName : en
ThreeLetterISOLanguageName : eng
ThreeLetterWindowsLanguageName : ENU
CompareInfo : CompareInfo - en-US
TextInfo : TextInfo - en-US
IsNeutralCulture : False
CultureTypes : SpecificCultures, InstalledWin32Cultures, FrameworkCultures
NumberFormat : System.Globalization.NumberFormatInfo
DateTimeFormat : System.Globalization.DateTimeFormatInfo
Calendar : System.Globalization.GregorianCalendar
OptionalCalendars : {System.Globalization.GregorianCalendar,
System.Globalization.GregorianCalendar}
UseUserOverride : True
IsReadOnly : False
A variável $C armazena um objeto Selected.System.Globalization.CultureInfo. O objeto é o resultado de Get-Culture enviar a saída pelo pipeline para Select-Object. O parâmetro propriedade usa um curinga asterisco (*) para especificar que todas as propriedades estão contidas no objeto.
Out-String usa o parâmetro InputObject para especificar o objeto CultureInfo armazenado na variável $C. Os objetos em $C são convertidos em uma cadeia de caracteres.
Observação
Para exibir a matriz Out-String, armazene a saída em uma variável e use um índice de matriz para exibir os elementos. Para obter mais informações sobre o índice de matriz, consulte about_Arrays.
$str = Out-String -InputObject $C -Width 100
Exemplo 2: Trabalhando com objetos
Este exemplo demonstra a diferença entre trabalhar com objetos e trabalhar com cadeias de caracteres. O comando exibe um alias que inclui o texto gcm, o alias para Get-Command.
Get-Alias | Out-String -Stream | Select-String -Pattern "gcm"
Alias gcm -> Get-Command
Get-Alias obtém os objetos System.Management.Automation.AliasInfo, um para cada alias e envia os objetos pelo pipeline.
Out-String usa o parâmetro Stream para converter cada objeto em uma cadeia de caracteres em vez de concatenar todos os objetos em uma única cadeia de caracteres.
Os objetos System.String são enviados pelo pipeline e Select-String usa o parâmetro padrão para localizar correspondências para o texto gcm.
Observação
Se você omitir o parâmetro Stream, o comando exibirá todos os aliases porque Select-String localiza o texto gcm na única cadeia de caracteres que Out-String retorna.
Exemplo 3: Usar o parâmetro Width para evitar truncamento
Embora a maior parte da saída de Out-String seja encapsulada para a próxima linha, há cenários em que a saída é truncada pelo sistema de formatação antes de ser passada para Out-String. Você pode evitar truncamento usando o parâmetro largura.
PS> @{TestKey = ('x' * 200)} | Out-String
Name Value
---- -----
TestKey xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx...
PS> @{TestKey = ('x' * 200)} | Out-String -Width 250
Name Value
---- -----
TestKey xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Parâmetros
-InputObject
Especifica os objetos a serem gravados em uma cadeia de caracteres. Insira uma variável que contenha os objetos ou digite um comando ou expressão que obtém os objetos.
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 |
-NoNewline
Remove todas as linhas novas da saída gerada pelo formatador do PowerShell. As linhas novas que fazem parte dos objetos de cadeia de caracteres são preservadas.
Esse parâmetro foi introduzido no PowerShell 6.0.
Propriedades do parâmetro
| Tipo: | SwitchParameter |
| Valor padrão: | False |
| Dá suporte a curingas: | False |
| DontShow: | False |
Conjuntos de parâmetros
NoNewLineFormatting
| Cargo: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline pelo nome da propriedade: | False |
| Valor dos argumentos restantes: | False |
-Stream
Por padrão, Out-String gera uma única cadeia de caracteres formatada como você a veria no console, incluindo quaisquer cabeçalhos em branco ou novas linhas à direita. O parâmetro Stream permite que Out-String produzam cada linha uma por uma. A única exceção a isso são cadeias de caracteres de várias linhas. Nesse caso, Out-String ainda produzirá a cadeia de caracteres como uma única cadeia de caracteres multilinha.
Propriedades do parâmetro
| Tipo: | SwitchParameter |
| Valor padrão: | False |
| Dá suporte a curingas: | False |
| DontShow: | False |
Conjuntos de parâmetros
StreamFormatting
| Cargo: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline pelo nome da propriedade: | False |
| Valor dos argumentos restantes: | False |
-Width
Especifica o número de caracteres em cada linha de saída. Todos os caracteres adicionais são encapsulados para a próxima linha ou truncados, dependendo do cmdlet do formatador usado. O parâmetro Width aplica-se somente a objetos que estão sendo formatados. Se você omitir esse parâmetro, a largura será determinada pelas características do programa host. Nas janelas do terminal (console), a largura da janela atual é usada como o valor padrão. As janelas do console do PowerShell são padrão para uma largura de 80 caracteres na instalação.
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: | 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
PSObject
Você pode redirecionar qualquer objeto para este cmdlet.
Saídas
String
Esse cmdlet retorna a cadeia de caracteres que ele cria do objeto de entrada.
Observações
Os cmdlets que contêm o verbo Out não formatizam objetos. Os cmdlets Out enviam objetos para o formatador para o destino de exibição especificado.
O PowerShell 7.2 adicionou a capacidade de controlar como as sequências de escape ANSI são renderizadas. A saída decorada por ANSI passada para Out-String pode ser alterada com base na configuração da propriedade $PSStyle.OutputRendering. Para saber mais, consulte about_ANSI_Terminals.
