Agents d’extension des cmdlets

  • Article

S’applique à : Exchange Server 2013

Les agents d'extension de cmdlet sont des composants de Microsoft Exchange Server 2013 appelés par des cmdlets d'Exchange 2013 lors de l'exécution des cmdlets. Comme leur nom l'indique, les agents d'extension de cmdlet étendent les fonctionnalités des cmdlets qui les appellent en contribuant au traitement des données ou en effectuant des opérations supplémentaires conformément aux exigences des cmdlets. Les agents d'extension de cmdlet sont accessibles sur tout rôle serveur.

Les agents peuvent modifier, remplacer ou étendre les fonctionnalités des cmdlets Exchange Management Shell. Un agent peut attribuer une valeur à un paramètre requis qui n'est pas spécifiée pour une commande, remplacer une valeur attribuée par un utilisateur, effectuer d'autres opérations non comprises dans le flux de travail de la cmdlet pendant son exécution, et davantage.

Par exemple, l’applet de commande New-Mailbox accepte le paramètre Database qui spécifie la base de données de boîtes aux lettres dans laquelle créer une boîte aux lettres. Dans Microsoft Exchange Server 2007, si vous ne spécifiez pas le paramètre Database lorsque vous exécutez l’applet de commande New-Mailbox, la commande échoue. Toutefois, dans Exchange 2013, l’applet de commande New-Mailbox appelle l’agent Mailbox Resources Management lors de l’exécution de l’applet de commande. Si le paramètre Database n’est pas spécifié, l’agent Mailbox Resources Management détermine automatiquement une base de données de boîtes aux lettres appropriée sur laquelle créer la nouvelle boîte aux lettres et insère cette valeur dans le paramètre Database .

Les agents d'extension de cmdlet ne peuvent être appelés que par des cmdlets Exchange 2013 et Microsoft Exchange Server 2010. Les cmdlets Exchange 2007 et celles fournies par d'autres produits Microsoft et tiers ne peuvent pas appeler des agents d'extension de cmdlet. De même, les scripts ne peuvent pas appeler directement les agents d'extension de cmdlet. Toutefois, si les scripts contiennent les cmdlets Exchange 2013, celles-ci continuent à appeler les agents d'extension de cmdlet.

Souhaitez-vous rechercher les tâches de gestion liées aux agents d'extension de cmdlet ? Voir Gérer des agents d'extension de cmdlet.

Priorité de l'agent

La priorité d'un agent détermine l'ordre dans lequel celui-ci est appelé lors de l'exécution d'une cmdlet. Un agent dont la priorité est élevée, proche de zéro (0), est appelé en premier. La priorité d'un agent devient importante quand plusieurs agents tentent de définir la valeur de la même propriété. L'agent dont la priorité est élevée réussit à définir une valeur de propriété, alors que toutes les tentatives ultérieures de définition de la même propriété par les agents dont la priorité est moins élevée sont ignorées. Par exemple, si la propriété Name sur un objet est modifiée par un agent avec la priorité 3 et qu'un autre agent avec la priorité 6 modifie le même objet, la modification apportée par l'agent avec la priorité 6 est ignorée.

Si vous souhaitez utiliser pour Scripting agent définir la valeur des propriétés qui peuvent être définies par d’autres agents de priorité supérieure, vous disposez des options suivantes :

  • Désactivez l'agent qui définit actuellement la propriété.

  • Définissez le sur Scripting agent une priorité supérieure à celle de l’agent existant que vous souhaitez remplacer.

  • Gardez les priorités des agents identiques et assurez-vous que le script qui s’exécute sous respecte Scripting agent la valeur fournie par les autres agents.

Avertissement

La modification de la priorité ou le remplacement de la fonctionnalité d'un agent intégré est une opération avancée. Assurez-vous que vous comprenez totalement les modifications que vous effectuez.

Pour plus d'informations sur la modification de la priorité d'un agent, voir Gérer des agents d'extension de cmdlet.

Agents intégrés

Exchange 2013 inclut plusieurs agents qui peuvent être appelés au moment de l'exécution d'une cmdlet. Le tableau suivant répertorie les agents, leur ordre et indique s'ils sont activés par défaut. Vous ne pouvez ni ajouter ni supprimer des agents d'un serveur qui exécute Exchange 2013. Toutefois, vous pouvez utiliser pour Scripting agent exécuter des scripts Windows PowerShell afin d’étendre les fonctionnalités des applets de commande qui l’utilisent. Pour plus d’informations sur , Scripting agentconsultez la section « Agent de script » plus loin dans cette rubrique.

Vous pouvez activer ou désactiver la plupart des agents ou modifier la priorité des agents si vous souhaitez remplacer les fonctionnalités d’un agent spécifique par les fonctionnalités que vous fournissez dans un script personnalisé que vous appelez à l’aide de Scripting agent. Cependant, certains agents ne peuvent pas être désactivés. Les agents qui ne peuvent pas être désactivés sont appelés agents système et ont leur propriété IsSystem définie sur $True. Le tableau suivant fournit des informations sur les agents d'extension de cmdlet d'Exchange 2013, y compris les agents système.

La configuration des agents est enregistrée au niveau de l'organisation. Lorsque vous activez ou désactivez un agent, ou que définissez sa priorité, vous définissez la configuration de cet agent sur tous les serveurs de l'organisation. L’exception est l’ajout de scripts au Scripting agent. Vous devez mettre à jour les scripts sur chaque serveur individuellement. Pour plus d’informations sur la configuration des scripts à utiliser avec , Scripting agentconsultez la section « Agent de script » plus loin dans cette rubrique.

Avertissement

Le changement de priorité des agents, ou l'activation ou la désactivation des agents, peut provoquer des effets non voulus si vous ne comprenez pas complètement le rôle de chaque agent et comment ils interagissent avec les cmdlets Exchange. Avant de changer la configuration d'un agent, veillez à bien comprendre les changements et résultats voulus et vérifiez que votre script personnalisé fonctionnera comme prévu.

Agents d'extension de cmdlet Exchange 2013

Nom de l’agent Priorité Activé par défaut Agent système
Admin Audit Log agent 255 True Oui
Scripting agent 6 False Non
Mailbox Resources Management agent 5 True Non
OAB Resources Management agent 4 True Non
Query Base DN agent 3 True Non
Provisioning Policy agent 2 True Non
Rus agent 1 True Non
Mailbox Creation Time agent 0 True Non

Agent de script

Vous pouvez utiliser l’agent Scripting agent d’extension d’applet de commande dans Exchange 2013 pour insérer votre propre logique de script dans l’exécution des applets de commande Exchange. À l’aide de Scripting agent, vous pouvez ajouter des conditions, remplacer des valeurs et configurer la création de rapports.

Avertissement

Lorsque vous activez l’agent Scripting agent d’extension d’applet de commande, l’agent est appelé chaque fois qu’une applet de commande est exécutée sur un serveur exécutant Exchange 2013. Cela inclut non seulement les applets de commande exécutées directement par vous dans Exchange Management Shell, mais également les applets de commande exécutées par les services Exchange et le Centre d’administration Exchange (EAC). Nous vous recommandons vivement de tester vos scripts et toutes les modifications que vous apportez au fichier de configuration avant de copier votre fichier de configuration mis à jour sur vos serveurs Exchange 2013 et d’activer l’agent d’extension d’applet de Scripting agent commande.

Chaque fois qu’une applet de commande Exchange est exécutée, l’applet de commande appelle l’agent d’extension d’applet de Scripting agent commande. Lorsque cet agent est appelé, la cmdlet vérifie si des scripts sont configurés pour être appelés par la cmdlet. Si un script doit être exécuté pour une cmdlet, cette dernière tente d'appeler toutes les API définies dans le script. Les API suivantes sont disponibles et appelées dans l'ordre suivant :

  1. ProvisionDefaultProperties : cette API peut être utilisée pour définir des valeurs de propriétés sur des objets lorsqu’ils sont créés. Lorsque vous sélectionnez une valeur, elle est renvoyée à la cmdlet qui définit la valeur sur la propriété. Vous pouvez renseigner des valeurs pour les propriétés si l'utilisateur n'en a pas spécifié ou bien remplacer la valeur saisie par l'utilisateur. Cette API respecte les valeurs définies par des agents de priorité supérieure. L’agent Scripting agent d’extension d’applet de commande ne remplace pas les valeurs définies par les agents de priorité supérieure.

  2. UpdateAffectedIConfigurable : cette API peut être utilisée pour définir des valeurs de propriétés sur des objets une fois tous les autres traitements terminés, mais l’API Validate n’a pas encore été appelée. Cette API respecte les valeurs définies par des agents de priorité supérieure. L’agent Scripting agent d’extension d’applet de commande ne remplace pas les valeurs définies par les agents de priorité supérieure.

  3. Validate : cette API peut être utilisée pour valider les valeurs sur les propriétés d’un objet qui sont sur le point d’être définies par l’applet de commande. Cette API est appelée juste avant l'écriture de données par une cmdlet. Vous pouvez configurer les contrôles de validation qui permettent la réussite ou l'échec d'une cmdlet. Si une cmdlet réussit les contrôles de validation dans cette API, elle est autorisée à écrire les données. Si la cmdlet échoue aux contrôles de validation, elle renvoie toutes les erreurs définies dans cette API.

  4. OnComplete : cette API est utilisée une fois que tout le traitement de l’applet de commande est terminé. Elle peut être utilisée pour exécuter des tâches de post-traitement, comme par exemple, écrire des données dans une base de données externe.

Remarque

L’agent Scripting agent d’extension d’applet de commande n’est pas appelé lorsque les applets de commande avec le Get verbe sont exécutées.

Fichier de configuration de l'agent de script

Le Scripting agent fichier de configuration contient tous les scripts que vous souhaitez Scripting agent exécuter. Les scripts du fichier de configuration sont contenus dans des balises XML qui définissent le début et la fin du script et divers paramètres d'entrée nécessaires pour transmettre les données au script. Les scripts sont écrits à l'aide de la syntaxe Windows PowerShell. Le fichier de configuration est un fichier XML qui utilise les éléments ou les attributs présentés dans le tableau suivant.

Attributs du fichier de configuration de l'agent de script

Élément Attribut Description
Configuration Non applicable Cet élément contient tous les scripts que l’agent d’extension Scripting agent d’applet de commande peut exécuter. La Feature balise est un enfant de cette balise.

Il n’y a qu’une Configuration seule balise dans le fichier de configuration.
Feature Non applicable Cet élément contient un ensemble de scripts associés à une fonctionnalité. Chaque script, défini dans la ApiCall balise enfant, étend une partie spécifique du pipeline d’exécution d’applet de commande. Cette balise contient les Name attributs et Cmdlets .

Il peut y avoir plusieurs Feature balises sous la Configuration balise.
Name Cet attribut contient le nom de la fonctionnalité. Utilisez cet attribut pour identifier la fonctionnalité qui est étendue par les scripts contenus dans la balise.
Cmdlets Cet attribut contient la liste des cmdlets Exchange utilisées par l'ensemble des scripts de cette extension de fonctionnalité. Vous pouvez spécifier plusieurs cmdlets en séparant chacune d'elles par une virgule.
ApiCall Non applicable Cet élément contient des scripts qui peuvent étendre une partie du pipeline d'exécution des cmdlets. Chaque script est défini par le nom de l'appel API dans le pipeline d'exécution des cmdlets qu'il étend. Les noms d'API suivants peuvent être étendus :
  • ProvisionDefaultProperties
  • UpdateAffectedIConfigurable
  • Validate
  • OnComplete
Name Cet attribut inclut le nom de l'appel API qui étend le pipeline d'exécution des cmdlets.
Common Non applicable Cet élément contient des fonctions qui peuvent être utilisées par tout script dans le fichier de configuration.

Chaque serveur Exchange 2013 inclut le fichier ScriptingAgentConfig.xml.sample dans le %ExchangeInstallPath%CmdletExtensionAgents dossier . Le nom de ce fichier doit être modifié à ScriptingAgentConfig.xml sur chaque serveur Exchange 2013 si vous activez l'agent d'extension de cmdlets Agent de script. L'exemple de fichier de configuration contient des modèles de script que vous pouvez utiliser pour mieux comprendre la procédure d'ajout de scripts au fichier de configuration.

Après avoir ajouté un script au fichier de configuration, ou si vous apportez une modification au fichier de configuration, vous devez mettre le fichier à jour sur chaque serveur Exchange 2013 de votre organisation. Cette opération doit être effectuée pour vous assurer que chaque serveur contient une version à jour des scripts exécutés par l’agent Scripting Agent d’extension d’applet de commande.

Certains caractères utilisés généralement dans les scripts ont également une signification particulière dans XML. Pour utiliser ces caractères dans votre script, utilisez des séquences d'échappement. Par exemple, les caractères suivants utilisent une séquence d'échappement :

  • Au lieu d’un signe supérieur à ( > ), utilisez >
  • Au lieu d’un signe inférieur à ( < ), utilisez $lt;
  • Au lieu d’une esperluette ( & ), utilisez &amp;

Activer l'agent de script

L’agent Scripting agent d’extension d’applet de commande est désactivé par défaut. Lorsque vous activez , l’agent Scripting agentest activé pour l’ensemble de l’organisation Exchange 2013. Avant d’activer , Scripting agentvérifiez que le Scripting agent fichier de configuration a été correctement renommé et mis à jour avec vos scripts sur chaque serveur Exchange 2013. Vous recevrez un message d'erreur chaque fois qu'une cmdlet est exécutée si vous n'avez pas renommé le fichier de configuration correctement ou copié un fichier de configuration sur cet ordinateur à partir d'un autre serveur Exchange 2013.

Pour activer , Scripting agentvous devez effectuer les opérations suivantes :

  1. Renommez le fichier ScriptingAgentConfig.xml.sample dans en %ExchangeInstallPath%Bin\CmdletExtensionAgents ScriptingAgentConfig.xml sur chaque serveur Exchange 2013 de votre organisation.

    Remarque

    Vous pouvez copier le fichier de configuration d'un serveur Exchange 2013 dans d'autres serveurs Exchange 2013. Assurez-vous de mettre à jour le fichier de configuration désiré avant de le copier.

  2. Ajoutez votre script au fichier de configuration renommé sur chaque serveur Exchange 2013 de votre organisation.

  3. Activez l’agent d’extension Scripting agent d’applet de commande. Pour plus d'informations sur l'activation des agents d'extension de cmdlets, consultez la rubrique Gérer des agents d'extension de cmdlet.

Priorité de l'agent de script

Par défaut, l’agent d’extension Scripting agent d’applet de commande s’exécute après tous les autres agents, à l’exception de l’agent Scripting agent . Si vous souhaitez qu’un script que vous avez créé remplace un agent existant, vous devez soit désactiver l’autre agent, soit modifier la priorité de l’un ou l’autre agent afin que l’agent Scripting agent d’extension d’applet de commande s’exécute en premier. Pour plus d'informations sur la manière de désactiver ou de modifier la priorité des agents, consultez Gérer des agents d'extension de cmdlet.