Tâches

Les tâches sont le résultat de l'exécution d'un script. Les tâches sont conservées selon les paramètres du script et du serveur.

Consulter les tâches

Les tâches peuvent être consultées en cliquant sur la page Automatisation / Tâches. Cliquez sur le bouton Afficher pour naviguer vers la tâche. Les tâches en cours peuvent aussi être annulées.

Liste des tâches

Afficher la sortie de la tâche

Les flux PowerShell standards tels que information, host, error, warning et verbose sont affichés dans le volet de sortie.

Sortie du flux de la tâche

Afficher la sortie du pipeline de la tâche

Le stockage d'une grande quantité de sortie de pipeline peut nuire à la performance. Vous pouvez éliminer la sortie du pipeline en configurant le paramètre Discard Pipeline sur les scripts.

La sortie du pipeline des tâches est également stockée dans PowerShell Universal. Tout objet écrit dans le pipeline est stocké en CliXml et peut être consulté dans l'onglet Pipeline Output.

Vous pouvez développer l'arborescence pour voir les objets et les propriétés provenant du pipeline.

Sortie du pipeline de la tâche

Consulter les erreurs

Toute erreur écrite dans le flux d'erreurs sera disponible dans l'onglet Error de la page de la tâche.

Sortie d'erreur de la tâche

Statut

Les tâches retournent différents statuts selon la configuration et le résultat de l'exécution. Les paramètres qui peuvent influencer le statut d'une tâche comprennent :

• ErrorActionPreference
• WarningActionPreference

Le tableau suivant décrit comment PowerShell Universal traite les statuts.

Statut	Description	Supprimer
Error	Un script a subi une erreur non bloquante.	Définir ErrorActionPreference à SilentlyContinue
Warning	Un script a généré un avertissement.	Définir WarningActionPreference à SilentlyContinue
Failed	Un script a subi une erreur bloquante.	Gérer l'erreur bloquante ou l'intercepter.
En attente de rétroaction	Un script attend une rétroaction, comme Read-Host.	Évitez les rappels à l'utilisateur comme read-host.
Running	Le script est en cours d'exécution.	N\A
Queued	Le script est actuellement en file d'attente pour être exécuté.	N\A

Rétroaction

Certaines tâches nécessiteront une rétroaction. Tout script qui contient un appel Read-Host attendra qu'il y ait une interaction de l'utilisateur avec cette tâche. La tâche sera dans l'état Waiting for Feedback, et vous pouvez répondre à cette rétroaction en cliquant sur le bouton Response to Feedback dans la page de la tâche.

Tâche en attente de rétroaction

Pour accepter une SecureString avec un champ de saisie de mot de passe, vous pouvez utiliser le paramètre -AsSecureString de Read-Host.

Appeler des tâches à partir de PowerShell

Vous pouvez utiliser Invoke-PSUScript pour appeler des tâches à partir de la ligne de commande. Vous aurez besoin d'un jeton d'appli valide pour le faire. Les paramètres sont définis à l'aide de paramètres dynamiques sur l'applet de commande Invoke-PSUScript.

Invoke-PSUScript -Script 'Script1.ps1' -RequiredParameter 'Hello'

Appeler des scripts à partir de scripts

Vous pouvez aussi appeler des scripts UA à partir de scripts UA. Lorsque vous exécutez une tâche dans UA, vous n'avez pas besoin de définir manuellement un jeton d'appli ni le nom de l'ordinateur. Ceux-ci seront définis pour vous. Vous pouvez simplement appeler Invoke-PSUScript dans votre script pour démarrer un autre script. Les deux tâches seront affichées dans l'interface. Si vous voulez attendre la fin du script, utilisez Wait-PSUJob.

Attendre la fin d'un script

Vous pouvez utiliser l'applet de commande Wait-PSUJob pour attendre la fin d'une tâche. Acheminez la valeur de retour de Invoke-PSUScript vers Wait-UAJob pour attendre que la tâche soit terminée. Wait-PSUJob attendra indéfiniment à moins que le paramètre -Timeout ne soit spécifié.

Invoke-PSUScript -Script 'Script1.ps1' -RequiredParameter 'Hello' | Wait-PSUJob

Retourner les données du pipeline

Vous pouvez utiliser l'applet de commande Get-PSUJobPipelineOutput pour retourner la sortie du pipeline produite par une tâche. Cette sortie de pipeline sera constituée d'objets désérialisés qui ont été écrits dans le pipeline pendant la tâche. Vous pouvez accéder à ces données à partir de tout endroit où vous avez accès à l'API de gestion de PowerShell Universal.

Get-PSUJobPipelineOutput -JobId 10

Retourner la sortie de la dernière tâche

Il peut être nécessaire de retourner la sortie de la dernière exécution de tâche d'un script. Pour ce faire, vous devrez utiliser une combinaison d'applets de commande pour récupérer le script, l'ID de la dernière tâche, puis retourner la sortie du pipeline ou de l'hôte.

$Job = Get-PSUScript -Name 'Script.ps1' | Get-PSUJob -OrderDirection Descending -First 1
Get-PSUJobPipelineOutput -Job $Job
Get-PSUJobOutput -Job $Job

Retourne la sortie de la dernière tâche sous forme d'objet

Par défaut, Get-PSUJobOutput retourne la sortie sous forme de chaîne. Pour retourner la sortie sous forme d'objet contenant de l'information sur la sortie, utilisez -AsObject.

$Job = Get-PSUScript -Name 'Script.ps1' | Get-PSUJob -OrderDirection Descending -First 1
Get-PSUJobOutput -Job $Job -AsObject

Appeler un script et attendre la sortie

Vous pouvez utiliser le paramètre -Wait de Invoke-PSUScript pour y parvenir.

$Output = Invoke-PSUScript -Script 'Script1.ps1' -RequiredParameter 'Hello' -Wait

De plus, l'exemple suivant appelle un script, stocke l'objet de tâche dans une variable $job, attend que la tâche soit terminée, puis retourne la sortie du pipeline et de l'hôte.

Invoke-PSUScript -Script 'Script1.ps1' -RequiredParameter 'Hello' | Tee-Object -Variable job | Wait-PSUJob

$Output = Get-PSUJobPipelineOutput -Job $Job
Get-PSUJobOutput -Job $Job

Mode intégré

Le mode intégré permet d'appeler ces applets de commande depuis PowerShell Universal sans jeton d'appli ni nom d'ordinateur. Il utilise le canal RPC interne pour communiquer.

Vous pouvez définir le paramètre -Integrated pour passer en mode intégré. Ce paramètre ne fonctionne pas à l'extérieur de PowerShell Universal.

Invoke-PSUScript -Script 'Script.ps1' -Integrated

Les applets de commande suivantes prennent en charge le mode intégré.

• Get-PSUScript
• Invoke-PSUScript
• Get-PSUJob
• Get-PSUJobOutput
• Get-PSUJobPipelineOutput
• Get-PSUJobFeedback
• Set-PSUJobFeedback
• Wait-PSUJob

Appeler des tâches avec REST

Vous pouvez appeler des tâches par REST à l'aide de l'API de gestion de PowerShell Universal. Vous aurez besoin d'un jeton d'appli valide pour appeler des tâches.

Appeler des scripts avec REST

Pour appeler un script, vous effectuez une requête HTTP POST vers le terminal du script avec l'ID du script que vous souhaitez exécuter.

Invoke-RestMethod http://localhost:5000/api/v1/script/7 -Method POST -Body "" -Headers @{ Authorization = "Bearer appToken" } -ContentType 'application/json'

Fournir des paramètres

Vous pouvez fournir des paramètres à la tâche au moyen d'une chaîne de requête. Les paramètres seront fournis à votre script sous forme de chaînes.

$Parameters = @{
    Uri = "http://localhost:5000/api/v1/script/path/PNP.ps1?Server=tester&Domain=test" 
    Method = "POST"
    Headers = @{Authorization = "Bearer $Apptoken"}
    ContentType = 'application/json'
    Body = '{}'
}

Invoke-RestMethod @Parameters

Définir l'environnement

Vous pouvez définir l'environnement en passant la propriété d'environnement au contexte de la tâche. La propriété doit être le nom d'un environnement défini dans votre instance PSU.

$JobContext = @{
    Environment = "PowerShell 7"
} | ConvertTo-Json

Invoke-RestMethod http://localhost:5000/api/v1/script/7 -Method POST -Body $JobContext -Headers @{ Authorization = "Bearer appToken" } -ContentType 'application/json'

Définir le compte d'exécution

Vous pouvez définir le compte d'exécution en passant le nom d'une variable PSCredential à la propriété Credential.

$JobContext = @{
    Credential = "MyUser"
} | ConvertTo-Json

Invoke-RestMethod http://localhost:5000/api/v1/script/7 -Method POST -Body $JobContext -Headers @{ Authorization = "Bearer appToken" } -ContentType 'application/json'

Appeler des tâches à partir d'applis

Vous pouvez utiliser les mêmes applets de commande que vous utilisez dans d'autres scripts PowerShell pour exécuter des scripts dans des applis. Vous voudrez peut-être une expérience plus interactive en le faisant. Voici quelques exemples de la façon d'y parvenir à l'aide du cadre d'applis.

Afficher la sortie

Vous pouvez utiliser les applets de commande Invoke-PSUScript et Get-PSUJobOutput pour créer un élément d'interface qui se met à jour pendant l'exécution du script. Supposons que vous avez un script comme celui ci-dessous. Il écrit simplement dans le flux Information toutes les 100 millisecondes, 100 fois.

1..100 | % {
    Write-Output "Hello $_"
    Start-Sleep -Milliseconds 100
}

Dans votre appli, vous pouvez démarrer le script en fonction d'une interaction de l'utilisateur, puis mettre à jour un élément pendant l'exécution du script. L'exemple ci-dessous crée un bouton et un élément de balise pre qui servira de destination pour la sortie du script. Lorsque l'utilisateur clique sur le bouton, la tâche démarre et il attend qu'elle se termine. Dans la boucle, il récupère la sortie du script, puis met à jour l'élément pre avec le contenu de la sortie.

Enfin, il récupère un statut mis à jour de la tâche et attend 100 millisecondes avant de s'exécuter de nouveau.

New-UDApp -Content {
    New-UDButton -Text "Run Script" -OnClick {
        $Job = Invoke-PSUScript -Name "AppExample.ps1" -Integrated
        while($Job.Status -eq 'Queued' -or $Job.Status -eq 'Running')
        {
            $Output = Get-PSUJobOutput -Job $Job
            Set-UDElement -Id 'output' -Content {
                $Output | ForEach-Object {
                    $_ +  [Environment]::NewLine
                }
            }
            $Job = Get-PSUJob -Id $Job.Id
            Start-Sleep -Milliseconds 100
        }
    } -ShowLoading

    New-UDElement -Tag 'pre' -Id 'output'
}

Afficher la progression

L'hôte PowerShell du cadre d'applis s'interfacera automatiquement avec des fonctionnalités de PowerShell, comme Write-Progress.

Si vous utilisez le paramètre -Wait de Invoke-PSUScript, il affichera automatiquement la progression du script dans un dialogue dans votre appli. Supposons que nous avons un script défini comme ci-dessous. Ce script écrit la progression toutes les 100 millisecondes.

1..100 | % {
    Write-Progress -Activity "Working..." -PercentComplete $_
    Start-Sleep -Milliseconds 100
}

Dans notre appli, nous pouvons simplement appeler le script avec le paramètre -Wait. Lorsque l'utilisateur clique sur le bouton, la progression sera affichée dans l'appli.

New-UDApp -Content {
    New-UDButton -Text "Run Script" -OnClick {
        Invoke-PSUScript -Name "AppExample.ps1" -Integrated -Wait
    } -ShowLoading
}

Demander une saisie

L'hôte PowerShell du cadre d'applis s'interfacera automatiquement avec des fonctionnalités de PowerShell, comme Read-Host.

Si vous utilisez le paramètre -Wait de Invoke-PSUScript, il demandera automatiquement une saisie à l'utilisateur lorsqu'il rencontrera la commande Read-Host. Supposons que nous avons un script qui demande une saisie de l'utilisateur à l'aide de Read-Host.

Read-Host -Prompt "What should I say?"

Dans votre appli, appelez simplement le script avec le paramètre -Wait.

New-UDApp -Content {
    New-UDButton -Text "Run Script" -OnClick {
        Invoke-PSUScript -Name "AppExample.ps1" -Integrated -Wait
    } -ShowLoading
}

L'utilisateur sera alors invité à saisir une valeur pendant l'exécution du script.

Variables définies dans les tâches

Les variables définies dans les tâches se trouvent sur la page des variables.

ID d'exécution de tâche

Le comportement par défaut de PowerShell Universal est de suivre les tâches en fonction d'un ID à incrémentation automatique basé sur int64. Chaque fois qu'une nouvelle tâche est exécutée, son ID est supérieur d'une unité à celui de la précédente. En raison de ce comportement, il est facile de deviner les ID d'autres tâches, ce qui peut potentiellement représenter un risque de sécurité.

Afin d'éviter ce problème, vous pouvez activer la fonctionnalité expérimentale JobRunID. Bien qu'à l'interne le système crée toujours des tâches avec des ID numériques croissants, vous ne pouvez pas accéder aux tâches à partir de ces ID. À la place, un nouveau champ appelé RunID est utilisé. RunID utilise un GUID plutôt qu'un ID pour les recherches. Cela réduit grandement la capacité d'un attaquant à devinier un ID de tâche.

Vous devrez activer cette fonctionnalité pour l'utiliser.

Set-PSUSetting -JobRunId

API

• Invoke-PSUScript
• Get-PSUJob
• Get-PSUJobFeedback
• Get-PSUJobOutput
• Get-PSUJobPipelineOutput
• Wait-PSUJob