Aide-mémoire des actions personnalisées

Cet article fournit une série de conseils pour vous aider à maximiser l'efficacité de votre script PowerShell lors de la création d'une action personnalisée dans CoreView :

Get-DomainFromSid

• Get-DomainFromSid: extrait le domaine à partir d'une valeur SID.

Exemple :

Get-DomainFromSid -Sid S-1-5-21-1454471165-1004335555-1606986666-6666

Get-ServerFromDn

• Get-ServerFromDn: extrait le domaine à partir d'un nom unique.

Exemple :

Get-ServerFromDn -dn "CN=user_1,DC=child,DC=server,DC=local"

Get-ListDomains

• Get-ListDomains: cette fonction fournit les domaines d'une forêt.

Exemple :

Get-ListDomains

Get-ReverseOrganizationUnit

• Get-ReverseOrganizationUnit: si la valeur commence par DC=, la fonction inverse le chemin.

Exemple :

Get-ReverseOrganizationUnit -ou "DC=local,DC=contoso,OU=folder"

unicode

• unicode: transforme une chaîne en UTF-8. 

Exemple :

unicode -str "value"

Get-CountriesLookup

• Get-CountriesLookup: contient une table de correspondance des pays

Get-CountryCodeFromDisplayName

• Get-CountryCodeFromDisplayName: cette fonction renvoie le code ISO à partir du nom affiché d'un pays. 

Exemple :

Get-CountryCodeFromDisplayName -displayName "Italy"

Get-CountryDisplayNameFromCode

• Get-CountryDisplayNameFromCode: cette fonction renvoie le nom affiché à partir du code ISO d'un pays. 

Exemple :

Get-CountryDisplayNameFromCode -countryCode "IT"

Get-CvOnpremExchangeCredential, Get-CvADCredential, Get-CvEmailAddresses

• Get-CvOnpremExchangeCredential: cette fonction récupère l'objet d'identifiants Exchange local. Toutefois, cette fonction est limitée à un seul contexte de forêt.
• Get-CvADCredential: cette fonction récupère les informations d'identification à partir d'une session Active Directory (AD) ouverte. Elle est limitée à un seul contexte de forêt.
• Get-CvEmailAddresses: à partir d'une chaîne fournie en entrée avec une ou plusieurs adresses e-mail séparées par une virgule, cette fonction renvoie une liste d'adresses e-mail même si certains éléments contiennent une virgule dans leur nom.

Exemple :

Get-CvEmailAddresses -emailAddresses "fake@domain.com,x500:/o=ExchangeLabs/ou=Exchange Administrative Group (test)/cn=Recipients/cn=1511b2015ac3521f8355f08ca5be1af0-my, test"

Get-CvGroupCategoryFromValue

• Get-CvGroupCategoryFromValue: à partir d'une valeur de type de groupe (un entier) et d'un e-mail, cette fonction renvoie le type, afin de comprendre si ce groupe est un groupe de sécurité ou un groupe de distribution.

Exemple :

Get-CvGroupCategoryFromValue -groupTypeValue 8 -mail "fake_distribution@domain.com"

Replace-Upn

• Replace-Upn: cette fonction remplace un caractère simple ' par un double ''.

Exemple :

Replace-Upn -upn "user'c.example@contoso.com"

Refresh-CVGraphToken

• Refresh-CVGraphToken: cette fonction est conçue pour actualiser le jeton de la session Microsoft Graph. Elle est particulièrement utile lorsque vous devez vous assurer que le jeton de votre session est valide et à jour.

Get-InfrastructureMasterByDomain

• Get-InfrastructureMasterByDomain: cette fonction obtient la valeur d'un rôle au niveau du domaine appelé Maître d'infrastructure.

Exemple :

Get-InfrastructureMasterByDomain -domain "contoso.local"

ConvertFrom-CVCanonicalObject

• ConvertFrom-CVCanonicalObject: cette fonction convertit un nom canonique (CN) en nom unique (DN).

Exemple :

ConvertFrom-CVCanonicalObject -CanonicalName "Constoso.local/OU Users/myUser"

Retry-CvCommand

• Retry-CvCommand: cette fonction est conçue pour relancer un bloc de script plusieurs fois. Cela est utile lorsqu'une opération peut échouer par intermittence ou lorsque les données ne sont pas disponibles immédiatement. 

La fonction accepte six paramètres :

1. $scriptBlock: il s'agit de la commande que vous voulez exécuter. Elle doit être transmise sous forme de bloc de script.
2. $params: ce sont les paramètres de la commande dans le bloc de script.
3. $retryCount: il s'agit d'un paramètre facultatif qui spécifie le nombre de fois où la commande doit être retentée en cas d'échec. La valeur par défaut est 10.
4. $sleepTime: il s'agit d'un paramètre facultatif qui spécifie la durée (en secondes) pendant laquelle la fonction doit attendre avant de relancer la commande. La valeur par défaut est de 3 secondes.
5. $throwException: il s'agit d'un paramètre facultatif qui indique si une exception doit être levée si la commande échoue après toutes les tentatives.
6. $stopOnNull: lorsqu'il est défini sur $true, la fonction arrête le modèle de nouvelle tentative si le résultat du bloc de script est null, même si le nombre maximum de tentatives n'a pas été atteint.

Exemples :

# Use Case 1: Retry with Exception Thrown
# Description: The Retry-CvCommand function attempts to execute the provided script block 'get-aduser' three times for the given 'fake@contoso.com' identity. The function is configured to throw an exception (ErrorAction Stop) if the user does not exist. In this scenario, after three attempts, the function throws an exception indicating that the user doesn't exist.
    $sbUseCase1 ={
        param ($identity)
        get-aduser -Identity $identity -ErrorAction Stop
    }
    $result = Retry-CvCommand -scriptBlock $sbUseCase1 -params "fake@contoso.com" -retryCount 3 -sleepTime 1 -throwException $true
# Use Case 2: Retry without Exception Handling
# Description: The Retry-CvCommand function retries executing the script block 'get-aduser' three times for the given 'fake@contoso.com' identity. However, this time, the function is not configured to throw exceptions (ErrorAction not set to Stop) so the Retry-CvCommand can't catch the exception, and the function will fail three times.
    $sbUseCase2 ={
        param ($identity)
        get-aduser -Identity $identity
    }
    $result = Retry-CvCommand -scriptBlock $sbUseCase2 -params "fake@contoso.com" -retryCount 3 -sleepTime 1 -throwException $false
# Use Case 3: Stop Retry on Null Result
# Description: The Retry-CvCommand function retrieves the 'Office' property of an Active Directory user with the provided identity. In this case the user exist but the office property is null so we can will stop immediately the execution (stopOnNull is set to $true). This behavior is useful when you don't want to continue retrying if a certain condition (null result) is met.
    $sbUseCase3 ={
        param ($identity)
        $office = get-aduser -Identity $identity -Properties Office | Select-Object Office
        return $office.Office
    }
    $result = Retry-CvCommand -scriptBlock $sbUseCase3 -params "CN=joker j,OU=OU_test,DC=contoso,DC=local" -retryCount 3 -sleepTime 1 -stopOnNull $true

Get-CvCustomAttributes

• Get-CvCustomAttributes: cette fonction fournit certaines informations, comme le type et l'attribut omSyntax d'un attribut Active Directory. La fonction nécessite deux paramètres :

1. className: Active Directory comprend un schéma par défaut avec de nombreuses classes d'objets, comme les utilisateurs, les groupes, les ordinateurs, les unités d'organisation, etc. Ces objets sont appelés « Classes » ; par exemple, nous pourrions définir la valeur « User ».
2. ldapCustomAttributesName: il s'agit du nom utilisé par les clients LDAP pour lire et écrire l'attribut, par exemple « costCenter ».

Exemple :

Get-CvCustomAttributes -className 'User' -ldapCustomAttributesName 'CostCenter'

Connect-CvPnPOnlineFromCurrentConnection (SharePoint et PNP)

• Connect-CvPnPOnlineFromCurrentConnection: se connecte à un site SharePoint Online (URL secondaire) en utilisant le contexte actuel (identifiant ou certificat) de la connexion active.

Paramètres :

• -secondaryUrl : URL complète du site cible (par exemple https://contoso.sharepoint.com/sites/marketing).
• ReturnConnection (facultatif) : lorsqu'il est présent, Connect-PnPOnline est appelé avec -ReturnConnection. La fonction renvoie l'objet de connexion PnP. Utilisez-le avec des cmdlets prenant en charge -Connection(par exemple Get-PnPList -Connection $conn).

Exemple :

Connect-CvPnPOnlineFromCurrentConnection -secondaryUrl https://contoso.sharepoint.com/sites/marketing

Connect-CvSpoServiceFromCurrentConnection

• Connect-CvSpoServiceFromCurrentConnection: initialise une connexion à un autre service d'administration SharePoint Online en utilisant le contexte actuel de la session active. Utilisez cette fonction au lieu de gérer manuellement les objets d'identifiants.

Exemple :

Connect-CvSpoServiceFromCurrentConnection -secondaryUrl https://contoso-admin.sharepoint.com