New-PSRoleCapabilityFile

  • Referentie
Module:
Microsoft.PowerShell.Core

Hiermee maakt u een bestand dat een set mogelijkheden definieert die moeten worden weergegeven 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 kan 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 eigenschappen en waarden van sessieconfiguratie bevat. Het bestand heeft de bestandsextensie .psrc en kan worden gebruikt door meer dan één sessieconfiguratie.

Alle parameters zijn optioneel, met uitzondering van New-PSRoleCapabilityFile de parameter Path , waarmee het pad 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, behalve waar vermeld in de beschrijving van de parameter. Als u bijvoorbeeld de parameter AssemblyiesToLoad niet opneemt, wordt die sectie van het sessieconfiguratiebestand als commentaar weergegeven.

Als u het functiemogelijkheidsbestand in een sessieconfiguratie wilt gebruiken, plaatst u het bestand eerst in een submap RoleCapabilities 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 functiemogelijkheidsbestand maken waarmee gebruikers services en elke VDI-computer opnieuw kunnen opstarten

In dit voorbeeld wordt een voorbeeld van een functiefunctiebestand 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

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

  • Name. 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 None. 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
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-AssembliesToLoad

Hiermee geeft u de assembly's die moeten worden geladen in de sessies die gebruikmaken van het functiemogelijkheidsbestand.

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

-Author

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

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

-CompanyName

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

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

-Copyright

Hiermee geeft u een copyright op voor het functiefunctiebestand. 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
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Description

Hiermee geeft u een beschrijving voor het functiefunctiebestand.

Type:String
Position:Named
Default value:None
Required:False
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
Required:False
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 functiemogelijkheidsbestand. De waarde van deze parameter moet een volledig of absoluut pad van de opmaakbestanden zijn.

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

-FunctionDefinitions

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

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

Voorbeeld:

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

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

-Guid

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

Type:Guid
Position:Named
Default value:None
Required:False
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 functiemogelijkheidsbestand. Standaard zijn alle opdrachten in vermelde modules zichtbaar. Bij gebruik met VisibleCmdlets of VisibleFunctions kunnen de opdrachten die zichtbaar zijn vanuit de opgegeven modules worden beperkt.

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

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

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

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

-Path

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

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

-ScriptsToProcess

Hiermee geeft u scripts toe te voegen aan sessies die gebruikmaken van het functiemogelijkheidsbestand. 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
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-TypesToProcess

Hiermee geeft u typebestanden (.ps1xml) toe te voegen aan sessies die gebruikmaken van het functiemogelijkheidsbestand. 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
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-VariableDefinitions

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

  • Name. Naam van de variabele. Deze sleutel is vereist.
  • Waarde. Variabele waarde. Deze sleutel is vereist.

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

Type:Object
Position:Named
Default value:None
Required:False
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 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, verwijdert PowerShell de cmdlet en ipmo de Import-Module alias uit de sessie.

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

-VisibleCmdlets

Hiermee beperkt u 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 de cmdlet beschikbaar maken, New-PSRoleCapabilityFile probeert u de juiste module te laden.

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

Type:Object[]
Position:Named
Default value:None
Required:False
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 cmdlet en ipmo de Import-Module alias uit de sessie.

Type:String[]
Position:Named
Default value:None
Required:False
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 eventuele functies die u definieert in de parameter FunctionDefinitions . 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 cmdlet en ipmo de Import-Module alias uit de sessie.

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

-VisibleProviders

Hiermee beperkt u 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 cmdlet en ipmo de Import-Module alias uit de sessie.

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