Partager via

New-PSRoleCapabilityFile

  • Référence
Module:
Microsoft.PowerShell.Core

Crée un fichier qui définit un ensemble de fonctionnalités à exposer via une configuration de session.

Syntaxe

New-PSRoleCapabilityFile
   [-Path] <String>
   [-Guid <Guid>]
   [-Author <String>]
   [-Description <String>]
   [-CompanyName <String>]
   [-Copyright <String>]
   [-ModulesToImport <Object[]>]
   [-VisibleAliases <String[]>]
   [-VisibleCmdlets <Object[]>]
   [-VisibleFunctions <Object[]>]
   [-VisibleExternalCommands <String[]>]
   [-VisibleProviders <String[]>]
   [-ScriptsToProcess <String[]>]
   [-AliasDefinitions <IDictionary[]>]
   [-FunctionDefinitions <IDictionary[]>]
   [-VariableDefinitions <Object>]
   [-EnvironmentVariables <IDictionary>]
   [-TypesToProcess <String[]>]
   [-FormatsToProcess <String[]>]
   [-AssembliesToLoad <String[]>]
   [<CommonParameters>]

Description

L’applet New-PSRoleCapabilityFile de commande crée un fichier qui définit un ensemble de fonctionnalités utilisateur qui peuvent être exposées via des fichiers de configuration de session. Cela inclut la détermination des applets de commande, des fonctions et des scripts disponibles pour les utilisateurs. Le fichier de capacité est un fichier texte lisible par l’homme qui contient une table de hachage des propriétés et des valeurs de configuration de session. Le fichier a une extension de nom de fichier .psrc et peut être utilisé par plusieurs configurations de session.

Tous les paramètres sont New-PSRoleCapabilityFile facultatifs, à l’exception du paramètre Path , qui spécifie le chemin d’accès du fichier. Si vous n’incluez pas de paramètre lorsque vous exécutez l’applet de commande, la clé correspondante dans le fichier de configuration de session est commentée, sauf si elle est notée dans la description du paramètre. Par exemple, si vous n’incluez pas le paramètre AssemblyesToLoad , cette section du fichier de configuration de session est commentée.

Pour utiliser le fichier de capacité de rôle dans une configuration de session, placez d’abord le fichier dans un sous-dossier RoleCapabilities d’un dossier de module PowerShell valide. Référencez ensuite le fichier par nom dans le champ RoleDefinitions dans un fichier de configuration de session PowerShell (.pssc).

Cette applet de commande a été introduite dans Windows PowerShell 5.0.

Exemples

Exemple 1 : Créer un fichier de capacité de rôle vide

Cet exemple crée un fichier de capacité de rôle qui utilise les valeurs par défaut (vides). Le fichier peut être modifié ultérieurement dans un éditeur de texte pour modifier ces paramètres de configuration.

New-PSRoleCapabilityFile -Path ".\ExampleFile.psrc"

Exemple 2 : Créer un fichier de capacité de rôle permettant aux utilisateurs de redémarrer les services et n’importe quel ordinateur VDI

Cet exemple crée un exemple de fichier de capacité de rôle qui permet aux utilisateurs de redémarrer des services et des ordinateurs qui correspondent à un modèle de nom spécifique. Le filtrage de noms est défini en définissant le paramètre ValidatePattern sur l’expression VDI\d+régulière.

$roleParameters = @{
    Path = ".\Maintenance.psrc"
    Author = "User01"
    CompanyName = "Fabrikam Corporation"
    Description = "This role enables users to restart any service and restart any VDI computer."
    ModulesToImport = "Microsoft.PowerShell.Core"
    VisibleCmdlets = "Restart-Service", @{
                      Name = "Restart-Computer"
                      Parameters = @{ Name = "ComputerName"; ValidatePattern = "VDI\d+" }
    }
}
New-PSRoleCapabilityFile @roleParameters

Paramètres

-AliasDefinitions

Ajoute les alias spécifiés aux sessions qui utilisent le fichier de capacité de rôle. Entrez une table de hachage avec les clés suivantes :

  • Nom. Nom de l'alias. Cette clé est obligatoire.
  • Valeur. Commande représentée par l'alias. Cette clé est obligatoire.
  • La description. Chaîne de texte qui décrit l'alias. Cette clé est facultative.
  • Options. Options de l'alias. Cette clé est facultative. La valeur par défaut est Aucune. Les valeurs acceptables pour ce paramètre sont : None, ReadOnly, Constant, Private ou AllScope.

Par exemple : @{Name="hlp";Value="Get-Help";Description="Gets help";Options="ReadOnly"}

Type:IDictionary[]
Position:Named
Valeur par défaut:None
Obligatoire:False
Accepter l'entrée de pipeline:False
Accepter les caractères génériques:False

-AssembliesToLoad

Spécifie les assemblys à charger dans les sessions qui utilisent le fichier de capacité de rôle.

Type:String[]
Position:Named
Valeur par défaut:None
Obligatoire:False
Accepter l'entrée de pipeline:False
Accepter les caractères génériques:False

-Author

Spécifie l’utilisateur qui a créé le fichier de capacité de rôle.

Type:String
Position:Named
Valeur par défaut:None
Obligatoire:False
Accepter l'entrée de pipeline:False
Accepter les caractères génériques:False

-CompanyName

Identifie l’entreprise qui a créé le fichier de capacité de rôle. La valeur par défaut est Unknown.

Type:String
Position:Named
Valeur par défaut:None
Obligatoire:False
Accepter l'entrée de pipeline:False
Accepter les caractères génériques:False

-Copyright

Spécifie un droit d’auteur pour le fichier de capacité de rôle. Si vous omettez ce paramètre, New-PSRoleCapabilityFile génère une instruction de copyright à l’aide de la valeur du paramètre Author .

Type:String
Position:Named
Valeur par défaut:None
Obligatoire:False
Accepter l'entrée de pipeline:False
Accepter les caractères génériques:False

-Description

Spécifie une description du fichier de capacité de rôle.

Type:String
Position:Named
Valeur par défaut:None
Obligatoire:False
Accepter l'entrée de pipeline:False
Accepter les caractères génériques:False

-EnvironmentVariables

Spécifie les variables d’environnement pour les sessions qui exposent ce fichier de capacité de rôle. Entrez une table de hachage dans laquelle les clés sont les noms des variables d'environnement, et les valeurs sont les valeurs des variables d'environnement.

Par exemple : EnvironmentVariables=@{TestShare="\\\\Server01\TestShare"}

Type:IDictionary
Position:Named
Valeur par défaut:None
Obligatoire:False
Accepter l'entrée de pipeline:False
Accepter les caractères génériques:False

-FormatsToProcess

Spécifie les fichiers de mise en forme (.ps1xml) qui s’exécutent dans des sessions qui utilisent le fichier de capacité de rôle. La valeur de ce paramètre doit être un chemin d’accès complet ou absolu des fichiers de mise en forme.

Type:String[]
Position:Named
Valeur par défaut:None
Obligatoire:False
Accepter l'entrée de pipeline:False
Accepter les caractères génériques:False

-FunctionDefinitions

Ajoute les fonctions spécifiées aux sessions qui exposent la fonctionnalité de rôle. Entrez une table de hachage avec les clés suivantes :

  • Nom. Nom de la fonction. Cette clé est obligatoire.
  • ScriptBlock. Corps de la fonction. Entrez un bloc de script. Cette clé est obligatoire.
  • Options. Options de la fonction. Cette clé est facultative. La valeur par défaut est Aucune. Les valeurs acceptables pour ce paramètre sont : None, ReadOnly, Constant, Private ou AllScope.

Par exemple :

@{Name="Get-PowerShellProcess";ScriptBlock={Get-Process PowerShell};Options="AllScope"}

Type:IDictionary[]
Position:Named
Valeur par défaut:None
Obligatoire:False
Accepter l'entrée de pipeline:False
Accepter les caractères génériques:False

-Guid

Spécifie un identificateur unique pour le fichier de capacité de rôle. Si vous omettez ce paramètre, New-PSRoleCapabilityFile génère un GUID pour le fichier. Pour créer un GUID dans PowerShell, tapez [guid]::NewGuid().

Type:Guid
Position:Named
Valeur par défaut:None
Obligatoire:False
Accepter l'entrée de pipeline:False
Accepter les caractères génériques:False

-ModulesToImport

Spécifie les modules qui sont automatiquement importés dans des sessions qui utilisent le fichier de capacité de rôle. Par défaut, toutes les commandes des modules répertoriés sont visibles. Lorsqu’elles sont utilisées avec VisibleCmdlets ou VisibleFunctions, les commandes visibles à partir des modules spécifiés peuvent être restreintes.

Chaque module utilisé dans la valeur de ce paramètre peut être représenté par une chaîne ou par une table de hachage. Une chaîne de module se compose uniquement du nom du module. Une table de hachage de module peut inclure des clés ModuleName, ModuleVersion et GUID . Seule la clé ModuleName est requise.

Par exemple, la valeur suivante se compose d'une chaîne et d'une table de hachage. Toutes les combinaisons de chaînes et de tables de hachage, dans n'importe quel ordre, sont valides.

"TroubleshootingPack", @{ModuleName="PSDiagnostics"; ModuleVersion="1.0.0.0";GUID="c61d6278-02a3-4618-ae37-a524d40a7f44"}

Type:Object[]
Position:Named
Valeur par défaut:None
Obligatoire:False
Accepter l'entrée de pipeline:False
Accepter les caractères génériques:False

-Path

Spécifie le chemin d’accès et le nom du fichier de capacité de rôle. Le fichier doit avoir une .psrc extension de nom de fichier.

Type:String
Position:0
Valeur par défaut:None
Obligatoire:True
Accepter l'entrée de pipeline:False
Accepter les caractères génériques:False

-ScriptsToProcess

Spécifie des scripts à ajouter à des sessions qui utilisent le fichier de capacité de rôle. Entrez le chemin d'accès et les noms de fichiers des scripts. La valeur de ce paramètre doit être un chemin d’accès complet ou absolu des noms de fichiers de script.

Type:String[]
Position:Named
Valeur par défaut:None
Obligatoire:False
Accepter l'entrée de pipeline:False
Accepter les caractères génériques:False

-TypesToProcess

Spécifie les fichiers de type (.ps1xml) à ajouter aux sessions qui utilisent le fichier de capacité de rôle. Entrez les noms de fichiers de type. La valeur de ce paramètre doit être un chemin d’accès complet ou absolu des noms de fichiers de type.

Type:String[]
Position:Named
Valeur par défaut:None
Obligatoire:False
Accepter l'entrée de pipeline:False
Accepter les caractères génériques:False

-VariableDefinitions

Spécifie des variables à ajouter à des sessions qui utilisent le fichier de capacité de rôle. Entrez une table de hachage avec les clés suivantes :

  • Nom. Nom de la variable. Cette clé est obligatoire.
  • Valeur. Valeur de la variable. Cette clé est obligatoire.

Par exemple : @{Name="WarningPreference";Value="SilentlyContinue"}

Type:Object
Position:Named
Valeur par défaut:None
Obligatoire:False
Accepter l'entrée de pipeline:False
Accepter les caractères génériques:False

-VisibleAliases

Limite les alias de la session à ces alias spécifiés dans la valeur de ce paramètre, ainsi que les alias que vous définissez dans le paramètre AliasDefinition . Les caractères génériques sont pris en charge. Par défaut, tous les alias définis par le moteur PowerShell et tous les alias que les modules exportent sont visibles dans la session.

Par exemple, pour limiter les alias disponibles à gm et gcm, utilisez cette syntaxe : VisibleAliases="gcm", "gp"

Quand un paramètre Visible est inclus dans le fichier de capacité de rôle, PowerShell supprime l’applet Import-Module de commande et son ipmo alias de la session.

Type:String[]
Position:Named
Valeur par défaut:None
Obligatoire:False
Accepter l'entrée de pipeline:False
Accepter les caractères génériques:True

-VisibleCmdlets

Limite les applets de commande de la session à celles spécifiées dans la valeur de ce paramètre. Les caractères génériques et les noms qualifiés de module sont pris en charge.

Par défaut, toutes les applets de commande que les modules de l’exportation de session sont visibles dans la session. Utilisez les paramètres SessionType et ModulesToImport pour déterminer quels modules et composants logiciels enfichables sont importés dans la session. Si aucun module dans ModulesToImport n’expose l’applet de commande, New-PSRoleCapabilityFile tente de charger le module approprié.

Quand un paramètre Visible est inclus dans le fichier de configuration de session, PowerShell supprime l’applet Import-Module de commande et son ipmo alias de la session.

Type:Object[]
Position:Named
Valeur par défaut:None
Obligatoire:False
Accepter l'entrée de pipeline:False
Accepter les caractères génériques:True

-VisibleExternalCommands

Limite les fichiers binaires, scripts et commandes externes qui peuvent être exécutés dans la session à ceux spécifiés dans la valeur de ce paramètre.

Par défaut, aucune commande externe n’est visible dans cette session.

Quand un paramètre Visible est inclus dans le fichier de configuration de session, PowerShell supprime l’applet Import-Module de commande et son ipmo alias de la session.

Type:String[]
Position:Named
Valeur par défaut:None
Obligatoire:False
Accepter l'entrée de pipeline:False
Accepter les caractères génériques:False

-VisibleFunctions

Limite les fonctions de la session à celles spécifiées dans la valeur de ce paramètre, ainsi que les fonctions que vous définissez dans le paramètre FunctionDefinitions . Les caractères génériques sont pris en charge.

Par défaut, toutes les fonctions exportées par les modules de la session sont visibles dans cette session. Utilisez les paramètres SessionType et ModulesToImport pour déterminer quels modules sont importés dans la session.

Quand un paramètre Visible est inclus dans le fichier de configuration de session, PowerShell supprime l’applet Import-Module de commande et son ipmo alias de la session.

Type:Object[]
Position:Named
Valeur par défaut:None
Obligatoire:False
Accepter l'entrée de pipeline:False
Accepter les caractères génériques:True

-VisibleProviders

Limite les fournisseurs PowerShell de la session à ceux spécifiés dans la valeur de ce paramètre. Les caractères génériques sont pris en charge.

Par défaut, tous les fournisseurs exportés par un module dans la session sont visibles dans la session. Utilisez les paramètres SessionType et ModulesToImport pour déterminer quels modules sont importés dans la session.

Quand un paramètre Visible est inclus dans le fichier de configuration de session, PowerShell supprime l’applet Import-Module de commande et son ipmo alias de la session.

Type:String[]
Position:Named
Valeur par défaut:None
Obligatoire:False
Accepter l'entrée de pipeline:False
Accepter les caractères génériques:True