Feedback

New-PSRoleCapabilityFile

  • Referentie
Module:
Microsoft.PowerShell.Core

Hiermee maakt u een bestand dat een set mogelijkheden definieert die beschikbaar moeten worden gemaakt via een sessieconfiguratie.

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

Description

De New-PSRoleCapabilityFile cmdlet maakt een bestand dat een set gebruikersmogelijkheden definieert die kunnen worden weergegeven via sessieconfiguratiebestanden. Dit omvat het bepalen welke cmdlets, functies en scripts beschikbaar zijn voor gebruikers. Het mogelijkheidsbestand is een door mensen leesbaar tekstbestand dat een hashtabel met sessieconfiguratie-eigenschappen en -waarden bevat. Het bestand heeft de extensie .psrc en kan worden gebruikt door meer dan één sessieconfiguratie.

Alle parameters van zijn optioneel, met uitzondering van New-PSRoleCapabilityFile de parameter Path , waarmee het bestandspad voor het bestand wordt opgegeven. Als u geen parameter opneemt wanneer u de cmdlet uitvoert, wordt de bijbehorende sleutel in het sessieconfiguratiebestand als commentaar weergegeven, met uitzondering van waar vermeld in de parameterbeschrijving. Als u bijvoorbeeld de parameter AssembliesToLoad niet opneemt, wordt die sectie van het sessieconfiguratiebestand als commentaar weergegeven.

Als u het functiebestand voor rollen in een sessieconfiguratie wilt gebruiken, plaatst u eerst het bestand in een RoleCapabilities-submap van een geldige PowerShell-modulemap. Verwijs vervolgens naar het bestand op naam in het veld RoleDefinitions in een PowerShell Session Configuration-bestand (.pssc).

Deze cmdlet is geïntroduceerd in Windows PowerShell 5.0.

Voorbeelden

Voorbeeld 1: Een leeg functiebestand maken

In dit voorbeeld wordt een nieuw functiemogelijkheidsbestand gemaakt dat gebruikmaakt van de standaardwaarden (lege waarden). Het bestand kan later worden bewerkt in een teksteditor om deze configuratie-instellingen te wijzigen.

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

Voorbeeld 2: Een functiebestand maken waarmee gebruikers services en elke VDI-computer opnieuw kunnen opstarten

In dit voorbeeld wordt een voorbeeld van een functiemogelijkheidsbestand gemaakt waarmee gebruikers services en computers opnieuw kunnen opstarten die overeenkomen met een specifiek naampatroon. Naamfiltering wordt gedefinieerd door de parameter ValidatePattern in te stellen op de reguliere expressie VDI\d+.

$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

Parameters

-AliasDefinitions

Hiermee worden de opgegeven aliassen toegevoegd aan sessies die gebruikmaken van het functiemogelijkheidsbestand. Voer een hash-tabel in met de volgende sleutels:

  • Naam. Naam van de alias. Deze sleutel is vereist.
  • Waarde. De opdracht die de alias vertegenwoordigt. Deze sleutel is vereist.
  • Beschrijving Een tekenreeks die de alias beschrijft. Deze sleutel is optioneel.
  • Opties. Aliasopties. Deze sleutel is optioneel. De standaardwaarde is Geen. De acceptabele waarden voor deze parameter zijn: None, ReadOnly, Constant, Private of AllScope.

Bijvoorbeeld: @{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

Hiermee geeft u de assembly's op die moeten worden geladen in de sessies die gebruikmaken van het functiebestand voor rollen.

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

Hiermee geeft u de gebruiker die het functiebestand voor de rol heeft gemaakt.

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

Identificeert het bedrijf dat het functiebestand voor rollen heeft gemaakt. De standaardwaarde is Onbekend.

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

Hiermee geeft u een copyright voor het rolmogelijkheidsbestand. Als u deze parameter weglaat, New-PSRoleCapabilityFile genereert u een copyright-instructie met behulp van de waarde van de parameter Auteur .

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

Hiermee geeft u een beschrijving voor het functiebestand voor rollen.

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

Hiermee geeft u de omgevingsvariabelen op voor sessies die dit functiemogelijkheidsbestand beschikbaar maken. Voer een hashtabel in waarin de sleutels de namen van de omgevingsvariabelen zijn en de waarden de omgevingsvariabelewaarden zijn.

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

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

Hiermee geeft u de opmaakbestanden (.ps1xml) op die worden uitgevoerd in sessies die gebruikmaken van het functiebestand voor rollen. De waarde van deze parameter moet een volledig of absoluut pad van de opmaakbestanden zijn.

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

Hiermee worden de opgegeven functies toegevoegd aan sessies die de functiemogelijkheid beschikbaar maken. Voer een hash-tabel in met de volgende sleutels:

  • Naam. Naam van de functie. Deze sleutel is vereist.
  • ScriptBlock. Hoofdtekst van functie. Voer een scriptblok in. Deze sleutel is vereist.
  • Opties. Functieopties. Deze sleutel is optioneel. De standaardwaarde is Geen. De acceptabele waarden voor deze parameter zijn: None, ReadOnly, Constant, Private of AllScope.

Bijvoorbeeld:

@{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

Hiermee geeft u een unieke id voor het functiebestand van de rol. Als u deze parameter weglaat, New-PSRoleCapabilityFile genereert u een GUID voor het bestand. Als u een nieuwe GUID in PowerShell wilt maken, typt u [guid]::NewGuid().

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

Hiermee geeft u de modules op die automatisch worden geïmporteerd in sessies die gebruikmaken van het functiebestand voor rollen. Standaard zijn alle opdrachten in de vermelde modules zichtbaar. Bij gebruik met VisibleCmdlets of VisibleFunctions kunnen de opdrachten die zichtbaar zijn vanuit de opgegeven modules worden beperkt.

Elke module die in de waarde van deze parameter wordt gebruikt, kan worden vertegenwoordigd door een tekenreeks of een hashtabel. Een moduletekenreeks bestaat alleen uit de naam van de module. Een module-hashtabel kan ModuleName-, ModuleVersion- en GUID-sleutels bevatten. Alleen de ModuleName-sleutel is vereist.

De volgende waarde bestaat bijvoorbeeld uit een tekenreeks en een hashtabel. Elke combinatie van tekenreeksen en hashtabellen is in elke volgorde geldig.

"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

Hiermee geeft u het pad en de bestandsnaam van het functiebestand. Het bestand moet een .psrc bestandsnaamextensie hebben.

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

Hiermee geeft u scripts op die moeten worden toegevoegd aan sessies die gebruikmaken van het functiebestand voor rollen. Voer het pad en de bestandsnamen van de scripts in. De waarde van deze parameter moet een volledig of absoluut pad van de bestandsnamen van het script zijn.

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

Hiermee geeft u typebestanden (.ps1xml) aan om toe te voegen aan sessies die gebruikmaken van het functiebestand voor rollen. Voer de bestandsnaam van het type in. De waarde van deze parameter moet een volledig of absoluut pad van het type bestandsnamen zijn.

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

Hiermee geeft u variabelen op die moeten worden toegevoegd aan sessies die gebruikmaken van het functiebestand. Voer een hash-tabel in met de volgende sleutels:

  • Naam. Naam van de variabele. Deze sleutel is vereist.
  • Waarde. Variabele waarde. Deze sleutel is vereist.
  • Opties. Variabele opties. Deze sleutel is optioneel. De standaardwaarde is Geen. De acceptabele waarden voor deze parameter zijn: None, ReadOnly, Constant, Private of AllScope.

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

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

Beperkt de aliassen in de sessie tot die aliassen die zijn opgegeven in de waarde van deze parameter, plus eventuele aliassen die u in de parameter AliasDefinition definieert. Jokertekens worden ondersteund. Standaard zijn alle aliassen die zijn gedefinieerd door de PowerShell-engine en alle aliassen die door modules worden geëxporteerd, zichtbaar in de sessie.

Als u bijvoorbeeld de beschikbare aliassen wilt beperken tot gm en gcm, gebruikt u deze syntaxis: VisibleAliases="gcm", "gp"

Wanneer een zichtbare parameter is opgenomen in het functiebestand van de rol, verwijdert PowerShell de Import-Module cmdlet en ipmo de alias uit de sessie.

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

Beperkt de cmdlets in de sessie tot de cmdlets die zijn opgegeven in de waarde van deze parameter. Jokertekens en module gekwalificeerde namen worden ondersteund.

Standaard zijn alle cmdlets die de modules in de sessieexport zichtbaar zijn in de sessie. Gebruik de parameters SessionType en ModulesToImport om te bepalen welke modules en modules in de sessie worden geïmporteerd. Als er geen modules in ModulesToImport beschikbaar maken, New-PSRoleCapabilityFile probeert u de juiste module te laden.

Wanneer een zichtbare parameter is opgenomen in het sessieconfiguratiebestand, verwijdert PowerShell de Import-Module cmdlet en ipmo de alias ervan uit de sessie.

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

Hiermee beperkt u de externe binaire bestanden, scripts en opdrachten die in de sessie kunnen worden uitgevoerd tot de bestanden die zijn opgegeven in de waarde van deze parameter.

Standaard zijn er geen externe opdrachten zichtbaar in deze sessie.

Wanneer een zichtbare parameter is opgenomen in het sessieconfiguratiebestand, verwijdert PowerShell de Import-Module cmdlet en ipmo de alias ervan uit de sessie.

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

Beperkt de functies in de sessie tot de functies die zijn opgegeven in de waarde van deze parameter, plus alle functies die u in de parameter FunctionDefinitions definieert. Jokertekens worden ondersteund.

Standaard zijn alle functies die door modules in de sessie worden geëxporteerd, zichtbaar in die sessie. Gebruik de parameters SessionType en ModulesToImport om te bepalen welke modules in de sessie worden geïmporteerd.

Wanneer een zichtbare parameter is opgenomen in het sessieconfiguratiebestand, verwijdert PowerShell de Import-Module cmdlet en ipmo de alias ervan uit de sessie.

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

Beperkt de PowerShell-providers in de sessie tot de providers die zijn opgegeven in de waarde van deze parameter. Jokertekens worden ondersteund.

Standaard zijn alle providers die door een module in de sessie worden geëxporteerd, zichtbaar in de sessie. Gebruik de parameters SessionType en ModulesToImport om te bepalen welke modules in de sessie worden geïmporteerd.

Wanneer een zichtbare parameter is opgenomen in het sessieconfiguratiebestand, verwijdert PowerShell de Import-Module cmdlet en ipmo de alias ervan uit de sessie.

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