Adding new sample

The following article describes how to add a new sample to the CLI for Microsoft 365.

Location

All samples may be found in the docs/docs/sample-scripts folder grouped in categories. CLI for Microsoft 365 script samples are synchronized to the Microsoft Sample Solution Gallery and therefore they need additional metadata to be specified in order to be presented correctly in the gallery.

Structure

Each sample needs to be stored in a separate folder. The folder name should be the same as the sample title (with replaced whitespace with dashes). The sample folder should have the following structure:

my-new-sample/
├─ assets/
│  ├─ preview.png
│  ├─ sample.json
├─ index.md

• assets/sample.json - this file has additional metadata about the sample that is needed in order to properly synchronize the sample to the Microsoft Sample Solution Gallery. More details about the contents of this file may be found in the next chapter
• assets/preview.png - this image will be shown as the sample preview in the Microsoft Sample Solution Gallery. This could present the result of the script sample (ex. if your script adds list items to a SharePoint list the preview image could show a screen of the populated list).
• index.md - this is the main file that contains the sample title, description, author, tags, and the script (or scripts if the sample was developed in multiple technologies/languages)

Sample.json (sample metadata)

[
  {
    "name": "pnp-disable-tenant-wide-extension",
    "source": "pnp",
    "title": "Disable specified Tenant-wide Extension",
    "url": "https://pnp.github.io/cli-microsoft365/sample-scripts/spo/disable-tenant-wide-extension",
    "creationDateTime": "2020-05-20",
    "updateDateTime": "2020-05-20",
    "shortDescription": "Script helps to disable the specified tenant wide extension based on the id parameter.",
    "longDescription": [
      "Tenant Wide Extensions list from the App Catalog helps to manage the activation / deactivation of the tenant wide extensions. The below sample script helps to disable the specified tenant wide extension based on the id parameter."
    ],
    "products": [
      "SharePoint"
    ],
    "categories": [],
    "tags": [
      "tag1",
      "tag2"
    ],
    "metadata": [
      {
        "key": "CLI-FOR-MICROSOFT365",
        "value": "<Provide the version of CLI which was used to develop the sample ex. v6.1>"
      }
    ],
    "thumbnails": [
      {
        "type": "image",
        "order": 100,
        "url": "https://raw.githubusercontent.com/pnp/cli-microsoft365/main/docs/docs/sample-scripts/...etc.../assets/preview.png",
        "alt": "preview image for the sample"
      }
    ],
    "authors": [
      {
        "gitHubAccount": "myName",
        "pictureUrl": "https://avatars.githubusercontent.com/u/123456789?v=4",
        "name": "My Name"
      }
    ],
    "references": [
      {
        "name": "Want to learn more about CLI for Microsoft 365 and the commands",
        "description": "Check out the CLI for Microsoft 365 site to get started and for the reference to the commands.",
        "url": "https://aka.ms/cli-m365"
      }
    ]
  }
]

Sample contents

The sample file should contain a title, a short description, an author, tags, and the script in code blocks. To help you get started you may use the below template.

---
tags:
  - provisioning
  - libraries
---

# My cool sample to add multiple lists in a sites

Author: [author name](https://link)

Short description of the sample functionality.

=== "PowerShell"

    ```powershell
    # m365 cli magic
    ```

=== "Bash"

    ```bash
    # m365 cli magic
    ```