Enabling it is fairly straightforward, as can be seen in this walkthrough. Or so I thought! Yet, as I attempted to navigate the steps, I encountered errors that left me feeling like struggling with supposedly “easy-open” packages.

It always makes me feel stupid when I struggle with “easy-open” packages!

With Windows Command Prompt:

curl: (3) URL rejected: Port number was not a decimal number between 0 and 65535

With PowerShell 5.1:

Invoke-WebRequest : A positional parameter cannot be found that accepts argument ‘–request’.
At line:1 char:1
+ curl –location –request POST ‘https://auth.sitecorecloud.io/oauth/t …
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ CategoryInfo : InvalidArgument: (:) [Invoke-WebRequest], ParameterBindingException
+ FullyQualifiedErrorId : PositionalParameterNotFound,Microsoft.PowerShell.Commands.InvokeWebRequestCommand

Are easy-open packages really easy to open?

My feelings were correct, and the root cause made me feel stupid: The command only worked well when I ran it in PowerShell 7! It’s not clear if this is a requirement for this walkthrough only. I’ve contacted Sitecore and asked for clarifications, as soon as I get a response I’ll update this article.

To make things a little more confusing, a different walkthrough written by my friend and band partner Sebastian Winter, shows that one of the pre-requisites for using the XM Cloud foundation template is PowerShell 5.1, saying that “PowerShell 7 is not supported at this time”.

Don’t have PowerShell 7?

To find out what version of PowerShell you’re running, simply type $PSVersionTable at the prompt. If you don’t have PowerShell 7 installed yet, you can follow this article for instructions on how to install it.

• Sitecore Powershell Extensions (SPE) 7.0 introduces advanced packaging features, but you can also enjoy them in past SPE versions by using our package or Gist.
• You can now selectively include linked items in packages, avoiding the classic all-or-nothing approach.
• Learn how the features work and how to use them.

Introduction

Get ready for an exciting update, folks! Sitecore PowerShell Extensions (SPE) 7.0 is rolling out by the end of this year with some seriously cool new features in the packaging department. And guess what? I had the privilege of implementing these features, which were received very positively by the SPE team (shoutout to the amazing Michael West for his support!)

Also available for older versions of SPE

But fear not, even if you’re using a lower version of SPE, you can still reap the benefits by installing the necessary scripts using the following package: Advanced-Packaging-Features-1-0-zip. Or manually creating the 5 scripts at their respective paths according to this Gist.

Let’s dive into what these advanced packaging features are all about and how to make the most of them!

Rebuild your Link Database

First things first: the new features depend on the Link Database, so you will have to keep it up-to-date. If you are unsure, remember to give your Link Database a good rebuild for the “master” database, at least once before utilizing these features.

Unlocking Selective Packaging Superpowers

Currently, the SPE UI allows you to include linked items in your package, but it is an all-or-nothing deal. If you want to include media items linked to your selected item, you had no choice but to include all of them.

This is how the classic interface works, based on checkboxes:

Well, hold on to your keyboards because the new advanced packaging features now empower you to cherry-pick and selectively include linked items to your package.

The new UI will now show a different set of radio box configurations:

1. Do not include linked items: Linked items are not included in the package.
2. Include parent links only: Only items linked to the selected item (parent) will be considered for inclusion.
3. Include all linked items: All linked items (parent and children) will be considered for inclusion.

If you select either 2 or 3, a new screen will show, allowing you to cherry-pick the linked items you want to include in the package.

As you can see, there are tabs for each kind of linked items (Content, Media, Layouts, System, Templates), making the selection process much easier.

Using the New Features

To access these supercharged packaging powers, simply right-click on any item in the Content Editor and navigate to Scripts > Packaging.

• Important: Starting from SPE 7.0 the original features were substituted with the new ones, so you will see the list as above. However, if you’re using the new features in older SPE versions through my package or Gist, then you’ll notice I’ve added the new features to scripts sufixed with “Advanced”, as can be seen below:

Let’s take a closer look at the options available to fight the packaging confusion crimes, powered by Sitecore PowerShell Extensions:

Quick Download Tree as a Package (Advanced)

This option allows you to download as a package the selected item, along with the additional items you choose to include in the package. You can add child items, and selectively pick those linked items that deserve a spot in your package.

Start New Package (Advanced)

Choosing this option initiates the creation of a new package without immediately downloading it. Don’t worry, though – you’ll have the option to download it later. Once you’ve made this selection, a host of further options becomes available:

1. Add Item to Package (Advanced): This handy feature lets you add the selected item, along with any linked items you desire, to your package.
2. Add Tree to Package (Advanced): Selecting this option adds the selected item, all its children, and the linked items you choose to your package.
3. Preview Package Items (Advanced): Curious about the contents of your package before sealing the deal? This option lists all the items currently added to your package, allowing you to ensure you’ve got items you envisioned.
4. Download Package (Advanced): Finally, when you’re ready to unleash your package upon the world, hit “Download Package”. Your meticulously crafted package, complete with its formidable lineup of items, will be ready for action!

Conclusion

With Sitecore Powershell Extensions 7.0’s advanced packaging features, you now have the power to curate packages like never before. No more settling for all or nothing – select the linked items that truly matter and assemble the perfect package for your Sitecore adventures. So, go ahead and embrace these newfound packaging superpowers.
Get ready to package up greatness, fellow Sitecore heroes!

To the rescue, I’ve created this Powershell Script, which you can use to save your precious time.

What you need to download:

• The Powershell Script itself
• The CSV file with all Sitecore references from this article – Direct link to the CSV file itself is here.
  This file is valid for Sitecore 10.1 – if you need a different version, you will have to prepare and use a different CSV file (Read the article to learn more)

Steps to update each project in your solution:

• Step 1 – If your upgrade requires, update your Project to the target .NET Framework
• Step 2 – Get the NuGet commands to update your project.
• Step 3 – Run the NuGet commands at the Package Manager Console of Visual Studio

It is recommended to update the references gradually, so you can detect and fix any issue as you continue.

In my experience, the following sequence produced good results:

1. If your .NET Framework has changed due to the upgrade, re-install all references not used by Sitecore by running the following command:
   

   .\Update-PackagesFile.ps1 -Csv “C:\temp\NuGet Sitecore.Platform.Assemblies 10.1.0 rev. 005207.csv” -Packages “D:\Git\myproject\packages.config” -ProjectName “MyProject” -DumpUnknownReinstall $true

2. Update the 3rd party references to the target versions, and using this command:
   

   .\Update-PackagesFile.ps1 -Csv “C:\temp\NuGet Sitecore.Platform.Assemblies 10.1.0 rev. 005207.csv” -Packages “D:\Git\myproject\packages.config” -ProjectName “MyProject” -DumpKnownReinstall $true

3. Sometimes 3rd party reference versions didn’t change, but you still want to force them to reinstall.  If that’s your case, use the command:
   

   .\Update-PackagesFile.ps1 -Csv “C:\temp\NuGet Sitecore.Platform.Assemblies 10.1.0 rev. 005207.csv” -Packages “D:\Git\myproject\packages.config” -ProjectName “MyProject” -DumpKnownReinstall $true

4. Finally, uninstall and re-install your Sitecore references (useful when migrating from earlier versions into SC10):
   

   .\Update-PackagesFile.ps1 -Csv “C:\temp\NuGet Sitecore.Platform.Assemblies 10.1.0 rev. 005207.csv” -Packages “D:\Git\myproject\packages.config” -ProjectName “MyProject” -TargetSitecore “10.1” -DumpSitecoreUpdates $true

   or simply update them with this command:

   .\Update-PackagesFile.ps1 -Csv “C:\temp\NuGet Sitecore.Platform.Assemblies 10.1.0 rev. 005207.csv” -Packages “D:\Git\myproject\packages.config” -ProjectName “MyProject” -TargetSitecore “10.1” -DumpSitecoreUpdates $true -KeepSitecoreLibs $true

Full description of parameters:

• Csv (mandatory) – Path to the CSV file
• Packages (mandatory) – Path to the packages.config file
• ProjectName (mandatory) – Project Name
• TargetSitecore – Target Sitecore version
• DumpUnknownReinstall – If $true => Will dump the Update-Package with -reinstall commands for libraries not used by Sitecore
• DumpKnownUpdates – If $true => Will dump the Update-Package commands for known libraries when versions doesn’t match
• DumpKnownReinstall – If $true => Will dump the Update-Package with -reinstall when versions are the same
• DumpSitecoreUpdates – If $true => Will dump the Update-Package for Sitecore.* libraries
• KeepSitecoreLibs
  • If $true  => then the Sitecore entries will NOT be uninstalled (Update)
  • If $false => then the Sitecore entries will be uninstalled and re-installed (useful when migrating from earlier versions into SC10)

UPDATE: Michael West likes this solution and confirmed that it will be part of the next release of SPE (6.0), becoming my first contribution to SPE! Here is the ticket where this implementation is being tracked.

If you are a big fan of Sitecore Powershell Extensions like me, you probably know the Find-Item command, which allows searching your search index in Powershell scripts. This command, however, has an important limitation: you cannot use custom fields to filter and sort from the index. Due to this limitation, extended usage of Find-Item with custom code is usually not possible.

Internally Find-Item uses the base class “Sitecore.ContentSearch.SearchTypes.SearchResultItem“, which does not include any custom fields. What we usually do with C# is to create a class that inherits from “SearchResultItem“, adding our custom fields, such as below:

public class CustomSearchResultItem : SearchResultItem
{
   [IndexField("_templates")]
   [DataMember]
   public virtual List<ID> TemplateIds { get; set; }
}

The Find-Item command, however, does not allow using this field. For instance, the following script:

$props = @{
 Index = "sitecore_master_index"
 Where = "Paths.Contains(@0) And TemplateIds.Contains(@1)"
 WhereValues = [ID]::Parse("{D5B8857B-DE30-4616-84F5-812A7129ACD5}"), [ID]::Parse("{50FFE147-4F48-428B-A417-4D96DD2048FF}")
}
Find-Item @props

Will give the following error:

Find-Item : No property or field 'TemplateIds' exists in type 'SearchResultItem'

Because, yeah… that property is only defined at our custom class, not at SearchResultItem. To circumvent this limitation I built this special command.

Find-CustomItem

This command extends the original Find-Item, allowing you to pass a type that will be used instead of the base SearchResultItem class:

$props = @{
 Index = "sitecore_master_index"
 Type = [PSWebsite.Foundation.Indexing.SearchTypes.BaseSearchResultItem]
 Where = "Paths.Contains(@0) And TemplateIds.Contains(@1)"
 WhereValues = [ID]::Parse("{D5B8857B-DE30-4616-84F5-812A7129ACD5}"), [ID]::Parse("{50FFE147-4F48-428B-A417-4D96DD2048FF}")
}
Find-CustomItem @props

Create the custom command

In order to use Find-CustomItem in your project, you should:

1. Add NuGet references to Sitecore.ContextSearch and Sitecore.ContextSearch.Linq;
2. Add a reference to Cognifide.Powershell.dll;
3. Create a custom FindItemCommand class extending Cognifide.PowerShell.Commandlets.Data.Search.FindItemCommand;
   You can download the whole class here
4. Register your new command with an include patch – make sure the content is according to the following

<?xml version="1.0"?>
<configuration xmlns:patch="http://www.sitecore.net/xmlconfig/">
   <sitecore>
      <powershell>
         <commandlets>
            <add Name="Find Item" type="PSWebsite.Foundation.Indexing.Powershell.Commandlets.FindItemCommand, PSWebsite.Foundation.Indexing" />
         </commandlets>
      </powershell>
   </sitecore>
</configuration>

Limitations

Not all parameters from Find-Item are supported by Find-CustomItem. If you use any of the unsupported parameters along with any custom properties, it will cast the query to the base SearchResultItem, and give the same error as the original Find-Item command.

Supported parameters:

• Index
• Where
• WhereValues
• OrderBy
• First
• Last
• Skip

Unsupported parameters:

• Criteria
• Predicate
• ScopeQuery

For instance, if you have an item with a very long name such as “Subpage with Left Rail Without Footer”, you could choose an Alias as “sub3″ and save 33 characters. Of course, your original item name is preserved, as this only applies to the file system.

In short:

• File path should not exceed 260 chars
• Folder path should not exceed 248 chars

What causes and what to do about

1. You have cloned the repository into a folder with a too large name
   What to do about: 
   1. Make sure you have something short like:
      C:\src\ABC
      instead of
      C:\Source Control\My Client Name Is Long\My Long Project Name
2. TDS project name is too wide – due to the Helix standard TDS projects can have longer names (Eg: MyProject.Foundation.DependencyInjection.Master)
   What to do about:
   1. New projects: avoid long names (Eg: DI instead of DependencyInjection)
   2. Existent projects:
      1. Use the Powershell script to find long paths and apply Aliases
      2. Be proactive to apply Aliases to TDS long names
3. The Sitecore Item Path added to TDS (including the item itself) is too long
   What to do about:
   1. Use the Powershell script to identify long paths, then apply a TDS Alias to each item that makes it longer
   2. EG: this path
      /sitecore/content/mywebsite/This page has a big name/But this page also has a big name/NotToBlame
      has 2 problematic items:
      1. “This page has a big name”
      2. “But this page also has a big name”
   3. Those 2 items must be added to TDS and have their “File System Alias” setup to something smaller

Powershell script

When a certain environment has this issue, make sure to follow the steps described earlier. However, to execute Step 3 you should first discover what items are problematic.

To quickly obtain such a list, use the following Powershell script:

# Script Setup
$pathToScan = “D:\src\ABC”;
$outputToCsv = $false;
$outputToPrompt = $true;
$maxLength = 225;
#########

cls;

if ($pathToScan.IndexOf(“\src”) -eq -1){
$pathToScan = “$pathToScan\src”;
}

# Get all TDS folders
$tdsFolders = Get-ChildItem -Path $pathToScan -File -Recurse | Where-Object {($_.FullName -like ‘*.Master*’) -or ($_.FullName -like ‘*.Core*’)} | Where-Object {($_.FullName -notlike ‘*\bin\*’)};
#$tdsFolders = Get-ChildItem -Path $pathToScan -Directory -Recurse;

# Add properties
foreach ($folder in $tdsFolders){
$folder | Add-Member PathLength $folder.FullName.Length;
}

# Sort
$tdsFoldersSorted = $tdsFolders | sort FullName | sort PathLength -Descending;

# Get Max Length to filter those that will not match
#$maxLength = Read-Host -Prompt ‘Max Length allowed';
$tdsFoldersToShow = $tdsFoldersSorted | Where-Object {$_.PathLength -gt $maxLength};

# Output Loop
$fileName = “$PSScriptRoot\beyond $maxLength.csv”;
$csvText = “”;
if ($outputToCsv){
$csvText = “$($csvText)Length,FullName`n”;
#Add-Content -Path $fileName -Value “Length,FullName”;
}
if ($outputToPrompt){
Write-Output(“Length,FullName”);
}

foreach ($folder in $tdsFoldersToShow){
if ($outputToCsv){
$csvText = “$($csvText)$($folder.PathLength),$($folder.FullName)`n”;
#Add-Content -Path $fileName -Value “$($folder.PathLength),$($folder.FullName)”;
}
if ($outputToPrompt){
Write-Output(“$($folder.PathLength),$($folder.FullName)”);
}
}

if ($outputToCsv){
Add-Content -Path $fileName -Value $csvText;
Write-Output(“File $fileName saved”);
}

Instructions

1. Open the script in Powershell ISE as Administrator
2. Setup script changing variables at the top:
   1. $pathToScan – should point to your git folder
   2. $outputToCsv – Set as $true if you want the script to create a CSV file with results, $false otherwise
   3. $outputToPrompt – Set as $true if you want the script to display results at prompt, $false otherwise
   4. $maxLength – Max length tolerated to a TDS item path – the script will list everything that goes beyond this vale
3. Run the script
4. Use the list obtained to apply instructions Aliases, making paths shorter