Tâches

Les tâches constituent l'historique des scripts qui ont été exécutés.

Les tâches sont le résultat de l'exécution d'un script. Les tâches sont conservées en fonction des paramètres définis au niveau du script et du serveur.

Affichage des tâches

Les tâches peuvent être consultées en cliquant sur la page Automation / Tâches. Cliquez sur le bouton Afficher pour accéder à la tâche. Les tâches en cours peuvent également être annulées.

Liste des tâches

Afficher la sortie d'une tâche

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

Sortie des flux de la tâche

Afficher la sortie du pipeline d'une tâche

Le stockage d'une grande quantité de sorties de pipeline peut nuire aux performances. Vous pouvez ignorer la sortie du pipeline en activant le paramètre Ignorer le 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 disponible à la consultation dans l'onglet Sortie du pipeline.

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

Affichage des erreurs

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

Sortie d'erreur de la tâche

Statut

Les tâches renvoient différents statuts selon la configuration et le résultat de l'exécution. Les paramètres pouvant affecter le statut d'une tâche incluent :

• ErrorActionPreference
• WarningActionPreference

Le tableau suivant décrit la façon dont PowerShell Universal traite les statuts.

Statut	Description	Suppression
Error	Un script a rencontré une erreur non terminante.	Définir ErrorActionPreference à SilentlyContinue
Warning	Un script a généré un avertissement.	Définir WarningActionPreference à SilentlyContinue
Failed	Un script a rencontré une erreur terminante.	Gérer l'erreur terminante ou l'intercepter.
Waiting on Feedback	Un script attend une rétroaction, comme Read-Host.	Éviter les rappels utilisateur tels que read-host.
Running	Le script est en cours d'exécution.	N\A
Queued	Le script est actuellement en file d'attente d'exécution.	N\A

Rétroaction

Certaines tâches nécessitent une rétroaction. Tout script contenant un appel Read-Host attendra jusqu'à ce qu'il y ait une interaction de l'utilisateur avec cette tâche. La tâche sera dans un état En attente de rétroaction, et vous pouvez répondre à cette rétroaction en cliquant sur le bouton Répondre à la rétroaction sur 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.

Appel de tâches depuis PowerShell

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

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

Appeler des scripts depuis des scripts

Vous pouvez également appeler des scripts UA depuis des scripts UA. Lors de l'exécution d'une tâche dans UA, vous n'avez pas besoin de définir manuellement un jeton d'application ou le nom de l'ordinateur. Ces éléments 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 souhaitez attendre la fin du script, utilisez Wait-PSUJob.

Attendre la fin d'un script

Vous pouvez utiliser le cmdlet Wait-PSUJob pour attendre la fin d'une tâche. Redirigez la valeur de retour de Invoke-PSUScript vers Wait-UAJob pour attendre que la tâche se termine. Wait-PSUJob attendra indéfiniment, sauf si le paramètre -Timeout est spécifié.

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

Retourner les données du pipeline

Vous pouvez utiliser le cmdlet 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 durant la tâche. Vous pouvez accéder à ces données depuis 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 d'un script. Pour ce faire, vous devrez utiliser une combinaison de cmdlets pour récupérer le script, l'identifiant 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

Retourner 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 des informations 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 tâche dans une variable $job, attend la fin de la tâche, 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 cmdlets depuis PowerShell Universal sans jeton d'application 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 en dehors de PowerShell Universal.

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

Les cmdlets suivants prennent en charge le mode intégré.

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

Appel de tâches avec REST

Vous pouvez appeler des tâches via REST en utilisant l'API de gestion de PowerShell Universal. Vous aurez besoin d'un jeton d'application valide pour appeler des tâches.

Appeler des scripts avec REST

Pour appeler un script, vous effectuez un HTTP POST vers le point de terminaison du script avec l'identifiant 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 via une chaîne de requête. Les paramètres seront transmis à 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 transmettant la propriété environment dans le contexte de la tâche. La propriété doit correspondre au 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 Exécuter en tant que

Vous pouvez définir le compte Exécuter en tant que en transmettant le nom d'une variable PSCredential dans 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'

Appel de tâches depuis des applications

Vous pouvez utiliser les mêmes cmdlets que vous utilisez dans d'autres scripts PowerShell pour exécuter des scripts dans des applications. Vous souhaiterez peut-être une expérience plus interactive pour ce faire. Voici quelques exemples permettant d'y parvenir en utilisant le framework d'application.

Afficher la sortie

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

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

Dans votre application, vous pouvez démarrer le script en réponse à une interaction de l'utilisateur, puis mettre à jour un élément au fur et à mesure de l'exécution du script. L'exemple ci-dessous crée un bouton et un élément de balise pre servant de destination pour la sortie du script. Lorsque l'utilisateur clique sur le bouton, la tâche démarre et attend sa fin. Dans la boucle, la sortie du script est récupérée, puis l'élément pre est mis à jour avec le contenu de la sortie.

Enfin, un statut mis à jour de la tâche est récupéré et le script attend 100 millisecondes avant de s'exécuter à 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 framework d'application s'interface automatiquement avec les fonctionnalités de PowerShell, comme Write-Progress.

Si vous utilisez le paramètre -Wait de Invoke-PSUScript, la progression du script s'affichera automatiquement dans une boîte de dialogue de votre application. 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 application, nous pouvons simplement appeler le script avec le paramètre -Wait. Lorsque l'utilisateur clique sur le bouton, la progression s'affichera dans l'application.

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 framework d'application s'interface automatiquement avec les fonctionnalités de PowerShell, comme Read-Host.

Si vous utilisez le paramètre -Wait de Invoke-PSUScript, l'utilisateur sera automatiquement invité à saisir des informations lorsque la commande Read-Host est rencontrée. Supposons que nous avons un script qui demande une saisie de l'utilisateur avec Read-Host.

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

Dans votre application, 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 des informations 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.

Identifiant d'exécution de tâche

Le comportement par défaut de PowerShell Universal est de suivre les tâches à l'aide d'un identifiant basé sur un entier int64 auto-incrémenté. Chaque fois qu'une nouvelle tâche est exécutée, son identifiant est supérieur d'une unité à celui de la précédente. En raison de ce comportement, il est facile de deviner d'autres identifiants de tâches, ce qui peut potentiellement constituer un risque de sécurité.

Pour éviter ce problème, vous pouvez activer la fonctionnalité expérimentale JobRunID. Bien qu'en interne le système crée toujours des tâches avec des identifiants numériques croissants, vous ne pouvez pas accéder aux tâches à partir de ces identifiants. À la place, un nouveau champ appelé RunID est utilisé. RunID utilise un GUID plutôt qu'un identifiant pour les recherches. Cela réduit considérablement la capacité d'un attaquant à deviner un identifiant 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