New-PSRoleCapabilityFile

  • Referenz
Modul:
Microsoft.PowerShell.Core

Erstellt eine Datei, die eine Reihe von Funktionen definiert, die über eine Sitzungskonfiguration verfügbar gemacht werden sollen.

Syntax

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>]

Beschreibung

Das New-PSRoleCapabilityFile Cmdlet erstellt eine Datei, die einen Satz von Benutzerfunktionen definiert, die über Sitzungskonfigurationsdateien verfügbar gemacht werden können. Dies umfasst die Bestimmung, welche Cmdlets, Funktionen und Skripts für Benutzer verfügbar sind. Die Funktionsdatei ist eine menschlichen lesbare Textdatei, die eine Hashtabelle der Sitzungskonfigurationseigenschaften und -werte enthält. Die Datei verfügt über eine PSRC-Dateinamenerweiterung und kann von mehr als einer Sitzungskonfiguration verwendet werden.

Alle Parameter New-PSRoleCapabilityFile sind optional, außer für den Pfadparameter , der den Dateipfad für die Datei angibt. Wenn Sie beim Ausführen des Cmdlets keinen Parameter enthalten, wird der entsprechende Schlüssel in der Sitzungskonfigurationsdatei kommentiert, außer wo in der Parameterbeschreibung angegeben ist. Wenn Sie beispielsweise den AssemblysToLoad-Parameter nicht einschließen, wird dieser Abschnitt der Sitzungskonfigurationsdatei auskommentiert.

Um die Rollenfunktionsdatei in einer Sitzungskonfiguration zu verwenden, platzieren Sie zuerst die Datei in einem RoleCapabilities-Unterordner eines gültigen PowerShell-Modulordners. Verweisen Sie dann auf die Datei nach Name im Feld "RoleDefinitions " in einer PowerShell-Sitzungskonfigurationsdatei (PSSC).

Dieses Cmdlet wurde in Windows PowerShell 5.0 eingeführt.

Beispiele

Beispiel 1: Erstellen einer leeren Rollenfunktionsdatei

In diesem Beispiel wird eine neue Rollenfunktionsdatei erstellt, die die Standardwerte (leer) verwendet. Die Datei kann später in einem Text-Editor bearbeitet werden, um diese Konfigurationseinstellungen zu ändern.

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

Beispiel 2: Erstellen einer Rollenfunktionsdatei, mit der Benutzer Dienste und alle VDI-Computer neu starten können

In diesem Beispiel wird eine Beispielfunktionsdatei erstellt, mit der Benutzer Dienste und Computer neu starten können, die einem bestimmten Namenmuster entsprechen. Die Namefilterung wird durch Festlegen des Parameters ValidatePattern auf den regulären Ausdruck VDI\d+definiert.

$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

Parameter

-AliasDefinitions

Fügt die angegebenen Aliase zu Sitzungen hinzu, die die Rollenfunktionsdatei verwenden. Geben Sie eine Hashtabelle mit den folgenden Schlüsseln ein:

  • Name. Name des Alias. Dieser Schlüssel ist erforderlich.
  • Wert. Der Befehl, den der Alias darstellt. Dieser Schlüssel ist erforderlich.
  • Beschreibung Eine Textzeichenfolge, die den Alias beschreibt. Dieser Schlüssel ist optional.
  • Optionen. Aliasoptionen. Dieser Schlüssel ist optional. Der Standardwert lautet „Keine“. Die zulässigen Werte für diesen Parameter sind: None, ReadOnly, Constant, Private oder AllScope.

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

Type:IDictionary[]
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False

-AssembliesToLoad

Gibt die Assemblys an, die in die Sitzungen geladen werden sollen, die die Rollenfunktionsdatei verwenden.

Type:String[]
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False

-Author

Gibt den Benutzer an, der die Rollenfunktionsdatei erstellt hat.

Type:String
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False

-CompanyName

Identifiziert das Unternehmen, das die Rollenfunktionsdatei erstellt hat. Der Standardwert ist Unknown (Unbekannt).

Type:String
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False

-Copyright

Gibt ein Copyright für die Rollenfunktionsdatei an. Wenn Sie diesen Parameter auslassen, New-PSRoleCapabilityFile generiert eine Copyright-Anweisung mithilfe des Werts des Author-Parameters .

Type:String
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False

-Description

Gibt eine Beschreibung für die Rollenfunktionsdatei an.

Type:String
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False

-EnvironmentVariables

Gibt die Umgebungsvariablen für Sitzungen an, die diese Rollenfunktionsdatei verfügbar machen. Geben Sie eine Hashtabelle ein, in der die Schlüssel die Namen der Umgebungsvariablen und die Werte die Werte der Umgebungsvariablen sind.

Beispiel: EnvironmentVariables=@{TestShare="\\\\Server01\TestShare"}

Type:IDictionary
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False

-FormatsToProcess

Gibt die Formatierungsdateien (PS1xml) an, die in Sitzungen ausgeführt werden, die die Rollenfunktionsdatei verwenden. Der Wert dieses Parameters muss ein vollständiger oder absoluter Pfad der Formatierungsdateien sein.

Type:String[]
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False

-FunctionDefinitions

Fügt die angegebenen Funktionen zu Sitzungen hinzu, die die Rollenfunktion verfügbar machen. Geben Sie eine Hashtabelle mit den folgenden Schlüsseln ein:

  • Name. Name der Funktion. Dieser Schlüssel ist erforderlich.
  • ScriptBlock. Funktionstext. Geben Sie einen Skriptblock ein. Dieser Schlüssel ist erforderlich.
  • Optionen. Funktionsoptionen. Dieser Schlüssel ist optional. Der Standardwert lautet „Keine“. Die zulässigen Werte für diesen Parameter sind: "None", "ReadOnly", "Constant", "Private" oder "AllScope".

Zum Beispiel:

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

Type:IDictionary[]
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False

-Guid

Gibt einen eindeutigen Bezeichner für die Rollenfunktionsdatei an. Wenn Sie diesen Parameter auslassen, New-PSRoleCapabilityFile wird eine GUID für die Datei generiert. Geben Sie [guid]::NewGuid()zum Erstellen einer neuen GUID in PowerShell einen neuen GUID ein.

Type:Guid
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False

-ModulesToImport

Gibt die Module an, die automatisch in Sitzungen importiert werden, die die Rollenfunktionsdatei verwenden. Standardmäßig sind alle Befehle in aufgelisteten Modulen sichtbar. Bei Verwendung mit VisibleCmdlets oder VisibleFunctions können die Befehle, die aus den angegebenen Modulen sichtbar sind, eingeschränkt werden.

Jedes Modul, das im Wert dieses Parameters verwendet wird, kann durch eine Zeichenfolge oder durch eine Hashtabelle dargestellt werden. Eine Modulzeichenfolge besteht nur aus dem Namen des Moduls. Eine Modul-Hashtabelle kann ModuleName, ModuleVersion und GUID-Schlüssel enthalten. Nur der ModuleName-Schlüssel ist erforderlich.

Beispielsweise besteht der folgende Wert aus einer Zeichenfolge und einer Hashtabelle. Jede Kombination aus Zeichenfolgen und Hashtabellen, in beliebiger Reihenfolge, ist gültig.

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

Type:Object[]
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False

-Path

Gibt den Pfad und den Dateinamen der Rollenfunktionsdatei an. Die Datei muss über eine .psrc Dateinamenerweiterung verfügen.

Type:String
Position:0
Default value:None
Accept pipeline input:False
Accept wildcard characters:False

-ScriptsToProcess

Gibt Skripts an, die Sitzungen hinzufügen, die die Rollenfunktionsdatei verwenden. Geben Sie den Pfad und die Dateinamen der Skripts ein. Der Wert dieses Parameters muss ein vollständiger oder absoluter Pfad der Skriptdateinamen sein.

Type:String[]
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False

-TypesToProcess

Gibt Typdateien (PS1xml) an, um Sitzungen hinzuzufügen, die die Rollenfunktionsdatei verwenden. Geben Sie die Typdateinamen ein. Der Wert dieses Parameters muss ein vollständiger oder absoluter Pfad der Typdateinamen sein.

Type:String[]
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False

-VariableDefinitions

Gibt Variablen an, die zu Sitzungen hinzugefügt werden, die die Rollenfunktionsdatei verwenden. Geben Sie eine Hashtabelle mit den folgenden Schlüsseln ein:

  • Name. Name der Variable. Dieser Schlüssel ist erforderlich.
  • Wert. Variablenwert. Dieser Schlüssel ist erforderlich.
  • Optionen. Variablenoptionen. Dieser Schlüssel ist optional. Der Standardwert lautet „Keine“. Die zulässigen Werte für diesen Parameter sind: "None", "ReadOnly", "Constant", "Private" oder "AllScope".

Beispiel: @{Name="WarningPreference";Value="SilentlyContinue";Options="AllScope"}

Type:Object
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False

-VisibleAliases

Beschränkt die Aliase in der Sitzung auf diese Aliase, die im Wert dieses Parameters angegeben sind, sowie alle Aliase, die Sie im AliasDefinition-Parameter definieren. Platzhalterzeichen werden unterstützt. Standardmäßig sind alle Aliase, die vom PowerShell-Modul definiert sind, und alle Aliase, die exportiert werden, in der Sitzung sichtbar.

Um beispielsweise die verfügbaren Aliase auf gm und gcm zu beschränken, verwenden Sie diese Syntax: VisibleAliases="gcm", "gp"

Wenn ein sichtbarer Parameter in der Rollenfunktionsdatei enthalten ist, entfernt PowerShell das Import-Module Cmdlet und seinen ipmo Alias aus der Sitzung.

Type:String[]
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:True

-VisibleCmdlets

Beschränkt die Cmdlets in der Sitzung auf jene, die im Wert dieses Parameters angegeben wurden. Freihalterzeichen und modulqualifizierte Namen werden unterstützt.

Standardmäßig sind alle Cmdlets, die die Module im Sitzungsexport enthalten, in der Sitzung sichtbar. Verwenden Sie die SessionType- und ModulesToImport-Parameter, um zu bestimmen, welche Module und Snap-Ins in die Sitzung importiert werden. Wenn kein Modul in ModulesToImport das Cmdlet verfügbar macht, wird versucht, New-PSRoleCapabilityFile das entsprechende Modul zu laden.

Wenn ein sichtbarer Parameter in der Sitzungskonfigurationsdatei enthalten ist, entfernt PowerShell das Cmdlet und seinen Import-Moduleipmo Alias aus der Sitzung.

Type:Object[]
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:True

-VisibleExternalCommands

Beschränkt die externen Binärdateien, Skripts und Befehle, die in der Sitzung auf diejenigen ausgeführt werden können, die im Wert dieses Parameters angegeben sind.

Standardmäßig sind in dieser Sitzung keine externen Befehle sichtbar.

Wenn ein sichtbarer Parameter in der Sitzungskonfigurationsdatei enthalten ist, entfernt PowerShell das Cmdlet und seinen Import-Moduleipmo Alias aus der Sitzung.

Type:String[]
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False

-VisibleFunctions

Beschränkt die Funktionen in der Sitzung auf diejenigen, die im Wert dieses Parameters angegeben sind, sowie alle Funktionen, die Sie im Parameter FunctionDefinitions definieren. Platzhalterzeichen werden unterstützt.

Standardmäßig sind alle funktionen, die von Modulen in der Sitzung exportiert wurden, in dieser Sitzung sichtbar. Verwenden Sie die Parameter SessionType und ModulesToImport , um zu bestimmen, welche Module in die Sitzung importiert werden.

Wenn ein sichtbarer Parameter in der Sitzungskonfigurationsdatei enthalten ist, entfernt PowerShell das Cmdlet und seinen Import-Moduleipmo Alias aus der Sitzung.

Type:Object[]
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:True

-VisibleProviders

Beschränkt die PowerShell-Anbieter in der Sitzung auf diejenigen, die im Wert dieses Parameters angegeben sind. Platzhalterzeichen werden unterstützt.

Standardmäßig sind alle von einem Modul in der Sitzung exportierten Anbieter in der Sitzung sichtbar. Verwenden Sie die Parameter SessionType und ModulesToImport , um zu bestimmen, welche Module in die Sitzung importiert werden.

Wenn ein sichtbarer Parameter in der Sitzungskonfigurationsdatei enthalten ist, entfernt PowerShell das Cmdlet und seinen Import-Moduleipmo Alias aus der Sitzung.

Type:String[]
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:True