DOCSEARCHbyAlgolia
Submit Docs

PnP PowerShell Documentation

repository·dev·Indexed 21 days ago

https://github.com/pnp/powershell

A cross-platform, .NET 8 based PowerShell module providing nearly 900 cmdlets for managing Microsoft 365 services, including SharePoint Online, Teams, Entra ID, Microsoft Project, and Security & Compliance. Version 3.x requires PowerShell 7.4.0 or newer and is specifically designed for SharePoint Online, serving as the community-driven successor to the original PnP-PowerShell module.

Tokens
403.5K
Snippets
1.4K
Records
1.9K
Agent score
68%

What's inside PnP PowerShell

  1. Overview of PnP PowerShell

    dev

    PnP PowerShell is a .NET 8 based PowerShell module that provides nearly 900 cmdlets for managing Microsoft 365 environments. It supports services including:

    • SharePoint Online
    • Microsoft Teams
    • Microsoft Project
    • Security & Compliance
    • Entra ID

    Note on Compatibility: This version is cross-platform (Windows, macOS, and Linux) but is specifically designed for SharePoint Online. It is the successor to the original PnP-PowerShell module. Unlike the older version, this cross-platform module does not support SharePoint On-Premises.

  2. Overview of using PnP PowerShell with Microsoft Search

    dev

    PnP PowerShell can be used to ingest organizational content from external sources (such as corporate intranets, documentation sites, databases, fileshares, or helpdesk ticketing systems) into the Microsoft Search index. This allows Microsoft Search to act as a unified search engine for content residing outside the Microsoft landscape.

    By indexing this data, you can provide users with a single search interface that points to various content sources. This can also be combined with Microsoft Copilot for Microsoft 365 to allow AI to answer questions using your indexed organizational data.

  3. Connect an SPFx Form Customizer to a Content Type

    dev

    You can use Set-PnPContentType to associate an SPFx Form Customizer with a content type. This allows you to customize the forms (New, Edit, or Display) used with that content type.

    There are two ways to do this:

    1. Apply to all forms (New, Edit, and Display): Use the convenience parameters -FormClientSideComponentId and -FormClientSideComponentProperties.
    2. Apply to a specific form type: Use the specific parameters for the form you want to target:
      • Display Form: -DisplayFormClientSideComponentId and -DisplayFormClientSideComponentProperties.
      • New Item Form: -NewFormClientSideComponentId and -NewFormClientSideComponentProperties.
      • Edit Item Form: -EditFormClientSideComponentId and -EditFormClientSideComponentProperties.
    # Update all forms (New, Edit, and Display) at once
Set-PnPContentType -Identity "Project Document" -List "Projects" -FormClientSideComponentId "dfed9a30-ec25-4aaf-ae9f-a68f3598f13a" -FormClientSideComponentProperties '{ "someKey": "some value" }'

# Update ONLY the display form
Set-PnPContentType -Identity "Project Document" -List "Projects" -DisplayFormClientSideComponentId "dfed9a30-ec25-4aaf-ae9f-a68f3598f13a" -DisplayFormClientSideComponentProperties '{ "someKey": "some value" }'

  4. Configure alert frequency and timing with Add-PnPAlert

    dev

    The -Frequency parameter determines how often alerts are sent, and the -Time parameter controls the specific schedule.

    • Daily: Use -Time to specify the time of day. For example, -Time (Get-Date -Hour 11 -Minute 00 -Second 00) will send alerts every day at 11:00 AM.
    • Weekly: The -Time parameter sets the day and time of the week based on the date provided. For example, if today is Friday at 5:00 PM and you provide (Get-Date).AddDays(1), the alert will be scheduled for Saturdays at 5:00 PM.
    • Immediate: Alerts are sent immediately.

    Important Note on Timezones: In the SharePoint Online web interface, the date and time shown for alerts will be converted to its equivalent in PST (Redmond time zone), regardless of the site's region configuration. Verify the timing on your specific tenant to account for potential timezone offsets.

    Add-PnPAlert -Title "Daily summary" -List "Demo List" -Frequency Daily -ChangeType All -Time (Get-Date -Hour 11 -Minute 00 -Second 00)

  5. Synchronize and delete terms during Import-PnPTermSet

    dev

    By default, Import-PnPTermSet only adds or updates terms. If you want the imported file to be the 'source of truth' and remove any terms currently in the term set that are missing from your CSV file, you must include the -SynchronizeDeletions switch.

    Warning: This will remove existing terms (and their children) that are not explicitly defined in the import file.

    # This command will remove terms in the 'Standard Terms' set that are not in the CSV
Import-PnPTermSet -GroupName 'Standard Terms' -Path 'C:\Temp\ImportTermSet.csv' -SynchronizeDeletions

  6. Other Notable Changes in PnP PowerShell 2.x

    dev

    Provisioning Schema

    Support for the 2019-03 PnP Provisioning schema has been removed from all provisioning-related cmdlets. You must use 2019-09 or later.

    The -Web Parameter

    The -Web parameter has been removed from Web-level cmdlets. To target a specific subweb, use Connect-PnPOnline -Url [subweburl] instead.

    Output Type Changes

    Be aware of changes to returned object types in your scripts:

    • Add-PnPTeamsTab:
      • If -Type SharePointPageAndList is used, -WebSiteUrl is now mandatory.
      • If -Type Planner is used, -ContentUrl is now mandatory.
    • Get-PnPAzureADGroupOwner: Returns PnP.PowerShell.Commands.Model.Microsoft365User.
    • Get-PnPAzureADGroupMember: Returns PnP.PowerShell.Commands.Model.Microsoft365User.
    • Get-PnPAzureADGroup: Returns PnP.PowerShell.Commands.Model.Graph.Group.
    • New-PnPAzureADGroup: Returns PnP.PowerShell.Commands.Model.Graph.Group.
    • Get-PnPUserProfileProperty: Returns SortedDictionary<string, object>.

  7. Configure Microsoft Search result visibility (All vertical vs. Custom Vertical)

    dev

    Once content is indexed, you must decide how it appears in search results. You have two primary options:

    1. Include in the 'All' vertical

    This allows results to appear alongside standard Microsoft 365 results. Important: If you want your ingested items to appear in Microsoft 365 Copilot results, you must include them in the 'All' vertical.

    • How to configure: In the Microsoft 365 Admin Center > Settings > Search & intelligence > Data sources, click Include Connector Results next to your connector.

    2. Create a Custom Vertical (Dedicated Tab)

    This creates a specific tab in Microsoft 365 Search that shows only results from your connector.

    • How to configure: In the Microsoft 365 Admin Center > Settings > Search & intelligence > Customizations > Verticals, click + Add.
    • Follow the wizard to name the vertical, select your connector, and optionally add queries or filters.

  8. Use parameters in tenant templates

    dev

    You can parameterize your tenant templates by using the -Parameters parameter with a hashtable. Inside your template file, you can reference these values using the {parameter:<Key>} token. This is useful for making templates reusable across different environments.

    For example, if you pass -Parameters @{"ListTitle"="Projects"}, any instance of {parameter:ListTitle} in your template will be replaced with the string Projects during application.

    Invoke-PnPTenantTemplate -Path "myfile.pnp" -Parameters @{"ListTitle"="Projects";"parameter2"="a second value"}

  9. Paginate container results

    dev

    When a SharePoint Embedded application contains more than 5,000 containers, use the -Paged switch to enable pagination.

    1. Run the command with -Paged to receive the first 5,000 containers and a <Paging Token>.
    2. Use the -PagingToken parameter with the provided token to retrieve the next batch of up to 5,000 containers.
    3. If no more containers are available, the output will return the message End of Containers view.

  10. Use different OrgAssetTypes for images and templates

    dev

    When calling Add-PnPOrgAssetsLibrary, use the -OrgAssetType parameter to define the purpose of the library:

    • ImageDocumentLibrary (Default): Best for images. Contents are accessible from any site or page via the SharePoint filepicker.
    • OfficeTemplateLibrary: Suggested for Office files. These will appear in the templates section of Office desktop apps and Office Online.

    Note on Copilot: If you want the library to be searchable via Copilot in Office applications, you must use -OrgAssetType ImageDocumentLibrary and set -IsCopilotSearchable $true. Using this flag with any other asset type will result in an error.

    # Example: Adding an Office Template Library
Add-PnPOrgAssetsLibrary -LibraryUrl "https://tenant.sharepoint.com/sites/templates/office" -OrgAssetType OfficeTemplateLibrary

# Example: Adding an Image Library searchable by Copilot
Add-PnPOrgAssetsLibrary -LibraryUrl "https://tenant.sharepoint.com/sites/branding/images" -OrgAssetType ImageDocumentLibrary -IsCopilotSearchable $true

  11. Handle deprecated -Web parameter

    dev

    The -Web parameter is marked as obsolete on many cmdlets. This parameter was used to execute cmdlets on a subweb underneath the current web. Due to underlying API changes, this parameter will be removed in a future release.

    Workaround: To work with a subweb, connect directly to the subweb using its full URL with Connect-PnPOnline.

  12. Validate search result type properties with -Validate

    dev

    The -Validate switch ensures that the properties you are applying are valid before the update is committed.

    • External Connectors: The cmdlet fetches the connector's schema. If a rule property does not exist in the schema, the cmdlet throws an error. Invalid display properties produce a warning.
    • SharePoint Content Sources: Property names are checked against known default managed properties. Unrecognized properties produce a warning (to allow for custom/autogenerated properties), but not an error.
    • Display Templates: Validates that the template is valid JSON and uses a supported Adaptive Card version (1.3).

    Standard search display properties (title, titleUrl, modifiedBy, modifiedTime, description) are always considered valid.