Freigeben über

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 Cmdlet New-PSRoleCapabilityFile erstellt eine Datei, die eine Reihe von Benutzerfunktionen definiert, die über Sitzungskonfigurationsdateien verfügbar gemacht werden können. Dazu gehört das Bestimmen, welche Cmdlets, Funktionen und Skripts benutzern zur Verfügung stehen. Die Funktionsdatei ist eine lesbare Textdatei, die eine Hashtabelle mit Sitzungskonfigurationseigenschaften und -werten enthält. Die Datei hat die Dateinamenerweiterung PSRC und kann von mehr als einer Sitzungskonfiguration verwendet werden.

Alle Parameter von New-PSRoleCapabilityFile sind optional, mit Ausnahme des Path-Parameters, der den Pfad für die Datei angibt. Wenn Sie beim Ausführen des Cmdlets keinen Parameter angeben, wird der entsprechende Schlüssel in der Sitzungskonfigurationsdatei auskommentiert, außer wenn in der Parameterbeschreibung angegeben. Wenn Sie z. B. den parameter "AssembliesToLoad" nicht einschließen, wird dieser Abschnitt der Sitzungskonfigurationsdatei auskommentiert.

Um die Rollenfunktionsdatei in einer Sitzungskonfiguration zu verwenden, platzieren Sie die Datei zuerst in einem RoleCapabilities-Unterordner Unterordner eines gültigen PowerShell-Modulordners. Verweisen Sie dann auf die Datei anhand des Namens 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 jeden VDI-Computer neu starten können

In diesem Beispiel wird eine Beispiel-Rollenfunktionsdatei erstellt, mit der Benutzer Dienste und Computer neu starten können, die einem bestimmten Namensmuster entsprechen. Die Namensfilterung wird durch Festlegen des ValidatePattern-Parameters 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 ist None. 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"}

Typ:IDictionary[]
Position:Named
Standardwert:None
Erforderlich:False
Pipelineeingabe akzeptieren:False
Platzhalterzeichen akzeptieren:False

-AssembliesToLoad

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

Typ:String[]
Position:Named
Standardwert:None
Erforderlich:False
Pipelineeingabe akzeptieren:False
Platzhalterzeichen akzeptieren:False

-Author

Gibt den Benutzer an, der die Rollenfunktionsdatei erstellt hat.

Typ:String
Position:Named
Standardwert:None
Erforderlich:False
Pipelineeingabe akzeptieren:False
Platzhalterzeichen akzeptieren:False

-CompanyName

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

Typ:String
Position:Named
Standardwert:None
Erforderlich:False
Pipelineeingabe akzeptieren:False
Platzhalterzeichen akzeptieren:False

-Copyright

Gibt ein Copyright für die Rollenfunktionsdatei an. Wenn Sie diesen Parameter weglassen, generiert New-PSRoleCapabilityFile eine Copyright-Anweisung mit dem Wert des parameters Author.

Typ:String
Position:Named
Standardwert:None
Erforderlich:False
Pipelineeingabe akzeptieren:False
Platzhalterzeichen akzeptieren:False

-Description

Gibt eine Beschreibung für die Rollenfunktionsdatei an.

Typ:String
Position:Named
Standardwert:None
Erforderlich:False
Pipelineeingabe akzeptieren:False
Platzhalterzeichen akzeptieren: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 Umgebungsvariablenwerte sind.

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

Typ:IDictionary
Position:Named
Standardwert:None
Erforderlich:False
Pipelineeingabe akzeptieren:False
Platzhalterzeichen akzeptieren: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.

Typ:String[]
Position:Named
Standardwert:None
Erforderlich:False
Pipelineeingabe akzeptieren:False
Platzhalterzeichen akzeptieren: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 ist None. 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"}

Typ:IDictionary[]
Position:Named
Standardwert:None
Erforderlich:False
Pipelineeingabe akzeptieren:False
Platzhalterzeichen akzeptieren:False

-Guid

Gibt einen eindeutigen Bezeichner für die Rollenfunktionsdatei an. Wenn Sie diesen Parameter weglassen, generiert New-PSRoleCapabilityFile eine GUID für die Datei. Geben Sie [guid]::NewGuid()ein, um eine neue GUID in PowerShell zu erstellen.

Typ:Guid
Position:Named
Standardwert:None
Erforderlich:False
Pipelineeingabe akzeptieren:False
Platzhalterzeichen akzeptieren: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 VisibleFunctionskönnen die in den angegebenen Modulen sichtbaren Befehle 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 Modulhashtabelle kann ModuleName-, ModuleVersion-und GUID- Schlüssel enthalten. Es ist nur der schlüssel ModuleName erforderlich.

Der folgende Wert besteht beispielsweise aus einer Zeichenfolge und einer Hashtabelle. Eine beliebige 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"}

Typ:Object[]
Position:Named
Standardwert:None
Erforderlich:False
Pipelineeingabe akzeptieren:False
Platzhalterzeichen akzeptieren:False

-Path

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

Typ:String
Position:0
Standardwert:None
Erforderlich:True
Pipelineeingabe akzeptieren:False
Platzhalterzeichen akzeptieren:False

-ScriptsToProcess

Gibt Skripts an, die Sitzungen hinzugefügt werden sollen, die die Rollenfunktionsdatei verwenden. Geben Sie den Pfad und dateinamen der Skripts ein. Der Wert dieses Parameters muss ein vollständiger oder absoluter Pfad der Skriptdateinamen sein.

Typ:String[]
Position:Named
Standardwert:None
Erforderlich:False
Pipelineeingabe akzeptieren:False
Platzhalterzeichen akzeptieren:False

-TypesToProcess

Gibt Typdateien (.ps1xml) an, die Sitzungen hinzugefügt werden sollen, die die Rollenfunktionsdatei verwenden. Geben Sie die Typdateinamen ein. Der Wert dieses Parameters muss ein vollständiger oder absoluter Pfad des Typs "Dateinamen" sein.

Typ:String[]
Position:Named
Standardwert:None
Erforderlich:False
Pipelineeingabe akzeptieren:False
Platzhalterzeichen akzeptieren:False

-VariableDefinitions

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

  • Name. Name der Variablen. Dieser Schlüssel ist erforderlich.
  • Wert. Variabler Wert. Dieser Schlüssel ist erforderlich.

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

Typ:Object
Position:Named
Standardwert:None
Erforderlich:False
Pipelineeingabe akzeptieren:False
Platzhalterzeichen akzeptieren:False

-VisibleAliases

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

Wenn Sie beispielsweise die verfügbaren Aliase auf gm und gcm beschränken möchten, verwenden Sie die folgende Syntax: VisibleAliases="gcm", "gp"

Wenn ein Visible Parameter in der Rollenfunktionsdatei enthalten ist, entfernt PowerShell das cmdlet Import-Module und dessen ipmo Alias aus der Sitzung.

Typ:String[]
Position:Named
Standardwert:None
Erforderlich:False
Pipelineeingabe akzeptieren:False
Platzhalterzeichen akzeptieren:True

-VisibleCmdlets

Beschränkt die Cmdlets in der Sitzung auf diejenigen, die im Wert dieses Parameters angegeben sind. Wildcardzeichen und modulqualifizierte Namen werden unterstützt.

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

Wenn ein Visible-Parameter in der Sitzungskonfigurationsdatei enthalten ist, entfernt PowerShell das cmdlet Import-Module und dessen ipmo Alias aus der Sitzung.

Typ:Object[]
Position:Named
Standardwert:None
Erforderlich:False
Pipelineeingabe akzeptieren:False
Platzhalterzeichen akzeptieren:True

-VisibleExternalCommands

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

In dieser Sitzung sind standardmäßig keine externen Befehle sichtbar.

Wenn ein Visible-Parameter in der Sitzungskonfigurationsdatei enthalten ist, entfernt PowerShell das cmdlet Import-Module und dessen ipmo Alias aus der Sitzung.

Typ:String[]
Position:Named
Standardwert:None
Erforderlich:False
Pipelineeingabe akzeptieren:False
Platzhalterzeichen akzeptieren:False

-VisibleFunctions

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

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

Wenn ein Visible-Parameter in der Sitzungskonfigurationsdatei enthalten ist, entfernt PowerShell das cmdlet Import-Module und dessen ipmo Alias aus der Sitzung.

Typ:Object[]
Position:Named
Standardwert:None
Erforderlich:False
Pipelineeingabe akzeptieren:False
Platzhalterzeichen akzeptieren:True

-VisibleProviders

Beschränkt die PowerShell-Anbieter in der Sitzung auf diejenigen, die im Wert dieses Parameters angegeben sind. Wildcardzeichen 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 Visible-Parameter in der Sitzungskonfigurationsdatei enthalten ist, entfernt PowerShell das cmdlet Import-Module und dessen ipmo Alias aus der Sitzung.

Typ:String[]
Position:Named
Standardwert:None
Erforderlich:False
Pipelineeingabe akzeptieren:False
Platzhalterzeichen akzeptieren:True