Valor de retorno da função no PowerShell

Eu desenvolvi uma função do PowerShell que executa várias ações que envolvem o provisionamento de sites da Equipe do SharePoint . Por fim, quero que a função retorne a URL do site provisionado como uma String, portanto, no final da minha função, tenho o seguinte código:

$rs = $url.ToString();
return $rs;

O código que chama essa função se parece com:

$returnURL = MyFunction -param 1 ...

Então, eu estou esperando uma String, mas não é. Em vez disso, é um objeto do tipo System.Management.Automation.PSMethod. Por que ele está retornando esse tipo em vez de um tipo String?

O PowerShell tem semântica de retorno realmente maluca - pelo menos quando vista de uma perspectiva de programação mais tradicional. Há duas idéias principais para você entender:

• Toda a saída é capturada e retornada
• A palavra-chave return realmente indica apenas um ponto de saída lógico

Portanto, os dois blocos de script a seguir farão exatamente a mesma coisa:

$a = "Hello, World"
return $a

$a = "Hello, World"
$a
return

A variável $ a no segundo exemplo é deixada como saída no pipeline e, como mencionado, toda a saída é retornada. De fato, no segundo exemplo, você poderia omitir completamente o retorno e obteria o mesmo comportamento (o retorno seria implícito, pois a função naturalmente termina e sai).

Sem mais definições de função, não sei dizer por que você está recebendo um objeto PSMethod. Meu palpite é que você provavelmente tem algo que algumas linhas acima não estão sendo capturadas e estão sendo colocadas no pipeline de saída.

Também é importante notar que você provavelmente não precisa desses pontos e vírgulas - a menos que esteja aninhando várias expressões em uma única linha.

Você pode ler mais sobre a semântica de retorno na página about_Return no TechNet ou chamando o help returncomando do próprio PowerShell.

Essa parte do PowerShell é provavelmente o aspecto mais estúpido. Qualquer saída estranha gerada durante uma função poluirá o resultado. Às vezes, não há saída e, em algumas condições, há outra saída não planejada, além do valor de retorno planejado.

Portanto, removo a atribuição da chamada de função original, para que a saída acabe na tela e depois avance até que algo que eu não planejei saia na janela do depurador (usando o PowerShell ISE ).

Mesmo coisas como reservar variáveis ​​em escopos externos causam saída, como a [boolean]$isEnabledque irrita irritantemente um False, a menos que você o faça [boolean]$isEnabled = $false.

Outra boa é $someCollection.Add("thing")que cospe a nova contagem de coleção.

Com o PowerShell 5, agora temos a capacidade de criar classes. Mude sua função para uma classe, e return retornará apenas o objeto imediatamente anterior a ela. Aqui está um exemplo muito simples.

class test_class {
    [int]return_what() {
        Write-Output "Hello, World!"
        return 808979
    }
}
$tc = New-Object -TypeName test_class
$tc.return_what()

Se isso fosse uma função, a saída esperada seria

Hello World
808979

mas como uma classe, a única coisa retornada é o número inteiro 808979. Uma classe é como uma garantia de que ela retornará apenas o tipo declarado ou nulo.

Como solução alternativa, eu retornei o último objeto da matriz que você retorna da função ... Não é uma ótima solução, mas é melhor que nada:

someFunction {
   $a = "hello"
   "Function is running"
   return $a
}

$b = someFunction
$b = $b[($b.count - 1)]  # Or
$b = $b[-1]              # Simpler

Em suma, uma maneira mais simples de escrever a mesma coisa poderia ser:

$b = (someFunction $someParameter $andAnotherOne)[-1]

Eu passo em torno de um objeto Hashtable simples com um único membro de resultado para evitar a loucura de retorno, pois também quero enviar para o console. Atua através de passagem por referência.

function sample-loop($returnObj) {
  for($i = 0; $i -lt 10; $i++) {
    Write-Host "loop counter: $i"
    $returnObj.result++
  }
}

function main-sample() {
  $countObj = @{ result = 0 }
  sample-loop -returnObj $countObj
  Write-Host "_____________"
  Write-Host "Total = " ($countObj.result)
}

main-sample

Você pode ver exemplos reais de uso no meu projeto GitHub, unpackTunes .

É difícil dizer sem olhar para o código. Verifique se sua função não retorna mais de um objeto e se captura todos os resultados obtidos com outras chamadas. O que você ganha por:

@($returnURL).count

Enfim, duas sugestões:

Transmitir o objeto para string:

...
return [string]$rs

Ou apenas coloque-o entre aspas duplas, igual ao anterior, mas mais curto para digitar:

...
return "$rs"

A descrição de Lucas da função resulta nesses cenários parece correta. Eu só quero entender a causa raiz e a equipe do produto PowerShell faria algo sobre o comportamento. Parece ser bastante comum e me custou muito tempo de depuração.

Para contornar esse problema, eu tenho usado variáveis ​​globais em vez de retornar e usar o valor da chamada de função.

Aqui está outra pergunta sobre o uso de variáveis ​​globais: Definindo uma variável global do PowerShell a partir de uma função em que o nome da variável global é uma variável passada para a função

O seguinte simplesmente retorna 4 como resposta. Quando você substitui as expressões add para strings, ele retorna a primeira string.

Function StartingMain {
  $a = 1 + 3
  $b = 2 + 5
  $c = 3 + 7
  Return $a
}

Function StartingEnd($b) {
  Write-Host $b
}

StartingEnd(StartingMain)

Isso também pode ser feito para uma matriz. O exemplo abaixo retornará "Texto 2"

Function StartingMain {
  $a = ,@("Text 1","Text 2","Text 3")
  Return $a
}

Function StartingEnd($b) {
  Write-Host $b[1]
}

StartingEnd(StartingMain)

Observe que você precisa chamar a função abaixo da própria função. Caso contrário, na primeira execução, ele retornará um erro que não sabe o que é "StartingMain".

As respostas existentes estão corretas, mas às vezes você não está retornando algo explicitamente com a Write-Outputou a return, mas há algum valor misterioso nos resultados da função. Pode ser a saída de uma função embutida comoNew-Item

PS C:\temp> function ContrivedFolderMakerFunction {
>>    $folderName = [DateTime]::Now.ToFileTime()
>>    $folderPath = Join-Path -Path . -ChildPath $folderName
>>    New-Item -Path $folderPath -ItemType Directory
>>    return $true
>> }
PS C:\temp> $result = ContrivedFolderMakerFunction
PS C:\temp> $result


    Directory: C:\temp


Mode                LastWriteTime         Length Name
----                -------------         ------ ----
d-----         2/9/2020   4:32 PM                132257575335253136
True

Todo esse ruído extra da criação do diretório está sendo coletado e emitido na saída. A maneira mais fácil de mitigar isso é adicionar | Out-Nullao final da New-Iteminstrução, ou você pode atribuir o resultado a uma variável e simplesmente não usá-la. Ficaria assim ...

PS C:\temp> function ContrivedFolderMakerFunction {
>>    $folderName = [DateTime]::Now.ToFileTime()
>>    $folderPath = Join-Path -Path . -ChildPath $folderName
>>    New-Item -Path $folderPath -ItemType Directory | Out-Null
>>    # -or-
>>    $throwaway = New-Item -Path $folderPath -ItemType Directory 
>>    return $true
>> }
PS C:\temp> $result = ContrivedFolderMakerFunction
PS C:\temp> $result
True

New-Itemé provavelmente o mais famoso deles, mas outros incluem todos os StringBuilder.Append*()métodos, bem como o SqlDataAdapter.Fill()método.