Get-SPSite

The Get-SPSite cmdlet returns a list of site collections matching the specified criteria. You can use this cmdlet alongside with a URL for a specific site. There are also different parameters that could be used to retrieve different sets of site collections, but these are outside the scope of this chapter. Just know that you could, as an example, retrieve all site collections belonging to a specific content database.

$siteCol = Get-SPSite http://localhost

This PowerShell line will return the site collection associated with the http://localhost URL and will assign it to variable $siteCol (see Figure 6-1).

Move-SPSite

Move-SPSite lets you move an existing site collection from one content database to another. It can be useful to regroup together various site collections for backup purposes. The following example assumes that the NewContentDB database already exists and that you are trying to move the specified site collection to it:

Move-SPSite http://localhost -DestinationDatabase NewContentDB

Copy-SPSite

The Copy-SPSite cmdlet makes a copy of an existing site collection. The copy can be done in the same content database or in a different one. You also can use this cmdlet to copy a site collection from one Web Application to another one, as shown in Figure 6-2.

Copy-SPSite http://localhost http://localhost/sites/destination

New-SPSite

New-SPSite creates a new site collection under a SharePoint Web Application. You have the option of specifying under what content database to have it created. If no content databases are specified, SharePoint automatically determines where to store it. Take note that if you don’t specify a template type when creating your new site collection, you will get a prompt asking you to select a template when you’ll first try to access it through the SharePoint interface. If you wish to specify a default web template, you can do so by adding the -Template parameter to the cmdlet call and passing it the name of the template to use. You can find a full list of all template names that are available in SharePoint 2013 by using the Get-SPWebTemplate cmdlet. Figure 6-3 shows the creation of a new site collection using PowerShell.

New-SPSite http://localhost/sites/test  -OwnerAlias "ContosoAdministrator"

Set-SPSite

Set-SPSite applies the specified configuration parameters to a specific site collection. Note that you could also get a reference to your site and directly modify the properties you want. It is what I consider to be a “shortcut” cmdlet:

Set-SPSite http://localhost/sites/test-MaxSize 2000

This example sets a specific quota for the http://localhost/sites/test site collection. The same results could have been achieved by calling the following code:

$siteCol = Get-SPSite http://localhost/sites/test
$siteCol.Quota.StorageMaximumLevel = 2000

The PowerShell snippet in Figure 6-4 proves that the two methods are equivalent.

Remove-SPSite

The Remove-SPSite cmdlet does exactly what you think it does. It deletes a specific site collection from a web application (see Figure 6-5). The only required parameter for this operation is the URL or GUID of the site collection to delete.

Remove-SPSite http://localhost/sites/test

Get-SPDeletedSite

Get-SPDeletedSite is a retriever method that returns a list of site collections that have been deleted based on specific research criteria. For example, you could get a list of all site collections that have been deleted under the “/sites” managed path (see Figure 6-6).

$colSiteCol = Get-SPdeletedSite "/sites/*"

Remove-SPDeletedSite

As you’ve just seen, a special type of site collection object in SharePoint exists, called the Deleted Site Collection. This object is in limbo between life and death. Think of it as being a file in the recycle bin, which is given a second chance. From that state on, a site collection can either be permanently deleted or restored back. Of course, it can be moved over another content database but nothing more.

The Remove-SPDeletedSite cmdlet receives the identity of the deleted site collections you want to permanently delete and deletes it. You can either specify a specific site collection by its GUID, or specify a server-relative URL. Based on the Get-SPDeletedSite example in the preceding section, if we would like to remove the /sites/CreatedVIA-Interface site collection, we could execute the following line of PowerShell.

Remove-SPDeletedSite /sites/CreatedVIA-Interface

Restore-SPDeletedSite

As mentioned in the preceding section, a deleted site collection also can be restored. The Restore-SPDeletedSite cmdlet does the opposite of Remove-SPDeletedSite and actually brings a deleted site collection back from the dead into its former glory, assuming that it was deleted through the web interface and not through PowerShell (see Figure 6-8).

Restore-SPDeletedSite /sites/CreatedVIA-Interface

Putting It Together: Creating a Site Collections Structure

Now that we have learned how easily we can interact with SharePoint site collections using PowerShell, we will build on the environment built in the previous chapter and will create a new site collection for every business unit identified in our fictive company, called Contoso. You will remember that when you created users in your domain, you also created five different security groups, each representing a different business unit. Those were:

• Administration
• Finance
• Human Resources
• Directors
• Tech Support

What you will want to do next is call the New-SPSite cmdlet and let it create these new business site collections. You could just call the cmdlet five times in a row with different parameters, but you’ve learned to do better. Put your newly acquired PowerShell skills to work and write something a bit more creative and reusable. What you are trying to achieve here can actually be achieved as a one liner using a pipe operation. Start by declaring an array containing the name of each business unit, and then pipe each of these names into your New-SPSite cmdlet. Then use the $_ operand to insert the names into the new site collection’s URL as follows (see Figure 6-9):

"Administration", "Finance", "Human Resources", "Directors", "Tech Support" |
%{New-SPSite http://localhost/sites/$_ -OwnerAlias contosoadministrator -Template "STS#0"}

It doesn’t get any simpler than this. You are now ready to dig deeper into the SharePoint object model and start looking at the various ways PowerShell can help you interact with webs.

Get-SPWeb

Get-SPWeb is the main retriever method to get a reference to a SPWeb object. It only requires you to specify the direct URL for the web you are trying to retrieve (see Figure 6-10).

Get-SPWeb "http://localhost/sites/HumanResources"

New-SPWeb

The New-SPWeb cmdlet lets you create a new web under a specified site collection. Table 6-1 lists the different templates that can be used to create new SharePoint 2013 webs and their short names to use with PowerShell.

The following example shows you how to create a new web using the Blank Site template. If you don’t specify a template for it, you’ll be prompted to select one the first time you access it through the SharePoint interface.

New-SPWeb http://localhost/NewWeb -Template "STS#1"

Remove-SPWeb

Remove-SPWeb lets you delete an existing web by specifying its URL. Note that deleting a web using PowerShell deletes it permanently, unless you specify the -Recycle parameter:

Remove-SPWeb http://localhost/NewWeb

If a web is deleted through the SharePoint interface, it becomes a SPDeletedSite object! Yes, you’ve heard me; just like in the case of a deleted site collection, a deleted web becomes the same object. Why is that? Because when you delete a site collection, all you’re doing is actually deleting the webs contained in it. When you restore at least one web in the site collection, you’re automatically restoring the site collection itself. There is such a thing as a SPDeletedSiteCollection object, but it does not expose any methods to remove or to restore itself.

The sad part, however, is that you cannot use the Get-SPDeletedSite cmdlet to retrieve webs that have been deleted in a site collection that still exists. To get a reference to such a web, you’ll need to get a reference to the site collection’s recycle bin, and then obtain a reference to the deleted web by iterating through the list of deleted objects. The example in Figure 6-11 shows you how you could retrieve a list of deleted webs from the recycle bin, and restore them back using PowerShell.

Set-SPWeb

Just like the Set-SPSite cmdlet, the Set-SPWeb is a shortcut command that allows you to configure a specified web. It allows you to specify a new URL, a new name, or a new description, or lets you apply a new template for the web. Again, just as is the case with the site collection level method, you could easily accomplish the same operation by getting a reference to the object using its retriever method, and by assigning values to its properties directly. The following example shows you how you could change the URL of a web using this PowerShell cmdlet (see Figure 6-12).

Set-SPWeb http://localhost/NewWeb -RelativeUrl ModifiedWeb

Export-SPWeb

Export-SPWeb lets you export a web along with all of its lists and libraries and their contents. The operation creates the backup file locally on disk, and generates an associated backup log. If you do not wish to have an export log generated on disk, you can simply us the -NoLogFile parameter. It is also important to note that this cmdlet will not preserve permissions for lists with broken inheritance and for item-level permissions.

Export-SPWeb http://localhost/ModifiedWeb -Path "C:ExportedWeb.cmp"

Import-SPWeb

Peanut butter is to jam what Import-SPWeb is to Export-SPWeb: they just go along together. Cheesy analogy, I know, but what can you do with a backup of something if you don’t have a means to restore it? This cmdlet lets you import a web along with all of its lists, libraries, and items. Just as in the case of the export method, it creates an operation log on disk. You can restore the backup on top of the existing site, or you could make a copy of it by creating a new site and restoring it at this new location, as shown in the following example (see Figure 6-13).

New-SPWeb http://localhost/MyImportedWeb
 
Import-SPWeb http://localhost/MyImportedWeb -Path "C:ExportedWeb.cmp"

Putting It Together: Creating Supporting Webs

You have now learned how easy it is to interact with SharePoint webs using PowerShell. You will now put your new learnings to good use, and continue to build on the example you’ve started in the previous section of this chapter. Now that you’ve created a site collection for each business unit within your organization, you will create workspaces for each team within the business unit. You will declare a multidimensional array with two dimensions: one representing the unit and one that will contains its associated teams. The logic will then loop in each row and create the new webs using the Team Site template (STS#0, as seen earlier in Table 6-1). To make things more exciting, each business unit will see their webs use a different theme to make sure that they can be easily differentiated. We will begin by declaring the array as follow:

$teamArray = @{}
$teamArray["Finance"] = @("Payroll", "Financial Systems", "Procurement")
$teamArray["Human Resources"] = @("Training", "Staff Services", "Recruiting")
$teamArray["Administration"] = @("Executive Assistants", "Planification")
$teamArray["Directors"] = @("CIO", "CEO", "COO")
$teamArray["Tech Support"] = @("Help Desk", "Applications", "Infrastructure")

Your next step is to define what the theme will be for each of these team sites. In SharePoint 2013, themes are now referred to as “Composed Looks.” However, the ApplyTheme method is what you need to use to apply custom theming. A composed look is made of three important parts: a color palette, a font scheme, and a background image. You will declare a second multidimensional array to keep track of what composed look will get applied to what web. The array contains the name of the SharePoint theme that you want to apply. The array will be declared as follows:

$themeArray = @{}
$themeArray["Finance"] = "Sea Monster"
$themeArray["Human Resources"] = "Sketch"
$themeArray["Administration"] = "Characters"
$themeArray["Directors"] = "Wood"
$themeArray["Tech Support"] = "Nature"

In order to get a reference to the appropriate color palette, font scheme, and background image, you need to get a reference to the composed look based on its name, as specified in the previous array. In order to achieve this, you need to get a reference to the site collection’s design catalog. This can be achieved by getting a reference to the site collection and calling the .GetCatalog(<name>) method. Once you have obtained the reference to the catalog, all that’s left to do is to query it based on the composed look’s name. You could get a reference to the Sea Monster theme for the Finance unit by using the following piece of PowerShell code (see Figure 6-14):

$site = Get-SPSite http://localhost/sites/Finance
$designCatalog = $site.GetCatalog("Design")
$seaMonsterTheme = $designCatalog.Items | Where {$_.Name -eq "Sea Monster"}
 
# Color Palette
$seaMonsterTheme["ThemeUrl].Split(',')[1]
 
# Font Scheme
$seaMonsterTheme["FontSchemeUrl"].Split(',')[1]
 
# Image
$seaMonsterTheme["ImageUrl"].Split(',')[1]

Now that both of our arrays have been properly declared and initialized, you can loop through each of the entries and make calls to the New-SPWeb cmdlet for each one. You will need to loop through each of the team array’s keys and use its key value to determine what the associated team is for a given business array:

foreach($businessUnit in $teamArray.Keys) # this returns a list of business units
{
    oreach($team in $teamArray[$businessUnit]
    {
        # At this point we have access to the teams' names, and we can dynamically
        # build the urls for the composed looks using that information    }
}

If you now try to put it all back together, your script will look like the following. You can use a unique set of foreach loops to access both the team and theme arrays. The script should take about five minutes to execute, at the end of which all of your webs will have been properly created:

#Declaring all teams in business units
$teamArray = @{}
$teamArray["Finance"] = @("Payroll", "Financial Systems", "Procurement")
$teamArray["Human Resources"] = @("Training", "Staff Services", "Recruiting")
$teamArray["Administration"] = @("Executive Assistants", "Planification")
$teamArray["Directors"] = @("CIO", "CEO", "COO")
$teamArray["Tech Support"] = @("Help Desk", "Applications", "Infrastructure")
 
#Declaring the various components of composed look for each team
$themeArray = @{}
$themeArray["Finance"] = "Sea Monster"
$themeArray["Human Resources"] = "Sketch"
$themeArray["Administration"] = "Characters"
$themeArray["Directors"] = "Wood"
$themeArray["Tech Support"] = "Nature"
 
foreach($businessUnit in $teamArray.Keys)
{
    $site = Get-SPSite "http://localhost/sites/$businessUnit "
    $catalog = $site.GetCatalog("Design")
    $theme = $catalog.Items | Where {$_.Name -eq $themeArray[$businessUnit]}
 
    foreach($team in $teamArray[$businessUnit])
    {
        #Remove-SPWeb "http://localhost/sites/$businessUnit/$team " -Confirm:$false
        $web = New-SPWeb "http://localhost/sites/$businessUnit/$team " -Template STS#0
                -Name $team
 
        $color = $theme["ThemeUrl"].Split(',')[1].Trim()
        $font = $theme["FontSchemeUrl"].Split(',')[1].Trim()
        $image = $theme["ImageUrl"].Split(',')[1].Trim()
        write-host $color
        $web.ApplyTheme($color, $font, $image, $true)
        write-host $team -backgroundcolor green
 
        $web.Dispose()
    }
    $site.Dispose()
}

To ensure that everything worked as expected, navigate to http://localhost/sites/Finance/Payroll/. Your team site should have been created with the Sea Monster composed look, which is made of an orange suite bar at the top (where you see the mention “SharePoint”), and of green tiles and icons.

I am now ready to dig deeper in the SharePoint object model and start playing with lists and libraries.

Getting a List Instance

SharePoint lists are contained at the web level. Every SPWeb object has a property called Lists that represents an array of all the lists contained in that specific web. In order to get a reference to a specific list, you’ll need to get it from that list array using either its name or its GUID. Another option would be to use the GetList method that expects the list’s relative URL as a parameter. The following example shows you how to get a reference to the Style Library located at the root of our site collection on http://localhost :

$web = Get-SPWeb http://localhost
$list = $web.Lists["Style Library"]
$fields = $list.Fields.InternalName
$fields | Where {$_ -like '*workflow*'}

This gets a list of all the internal names of the fields contained in the Style Library list. Think of internal names as being unique IDs. Each field has two names, an internal one and a display one. There is nothing preventing a list from having two fields with the same display names, but you cannot have two fields with the same internal name being part of the same list. Once you’ve retrieved a list of all internal names, you can query it using the pipeline operator, to retrieve only the field names that contain the word workflow (see Figure 6-15).

Creating a New List

To create a new list instance, you will need to first obtain a reference to the web in which you want to add the list. After the reference is obtained, the new list can be created by calling the .Add() method on the Lists properties of the web object. In most cases, you will be calling the Add() method using three parameters: a title, a description, and the list template associated with your list. To get a full list of all available list templates, as shown in Figure 6-16, you can simply run the following PowerShell command:

$web = Get-SPWeb http://localhost
$web.ListTemplates.Name

Once you have determined what list template you wish to use for your new list, you can call the following commands to have your list created (see Figure 6-17). Note that the Add() method returns a GUID associated with your newly created list, not a SPList object. You will need to get an instance of your new list using either the list’s name or obtained GUID to interact with it further.

$web = Get-SPWeb http://localhost
$ID = $web.Lists.Add("My List", "My Description", $web.ListTemplates["Custom List"])

Removing a List Instance

In order for you to be able to delete a list instance, you will need to get an instance of it first. After an instance has been obtained, you can simply call the Delete() method on it. Just like site collections and webs, deleting a list instance using PowerShell will permanently remove the list, and it won’t be recoverable through the recycle bin. The following code example shows you how to delete the “My List” instance that was created in the previous section:

$web = Get-SPWeb http://localhost
$list = $web.Lists["My List"]
$list.Delete()

In Figure 6-18, I list the titles of all of the lists that exist at the specified web level. You can clearly see that after calling the Delete() method on your list’s instance, it doesn’t show up in the list anymore, which means it has been properly deleted.

Restoring a List Instance

A SharePoint list that gets deleted makes it into the recycle bin before being deleted from the server for good. You then have the option of restoring it by getting a reference to the current site’s recycle bin object, and by iterating through its items. Once you have obtained a reference to the appropriate item in the recycle bin, simply call the Restore() method on it (see Figure 6-19). To have the list deleted permanently, you should call the Delete() method instead.

$spsite = Get-SPSite http://localhost
$bin = $spsite.RecycleBin
$myList = $bin | Where{$_.ItemType - eq "List"}
$myList.Restore()

Copying a List Instance

Sadly, there are no direct ways to copy a SharePoint list using PowerShell. Despite this fact, you could still copy an existing list along with all of its data using a combination of two operations. To be able to copy a SharePoint list instance using PowerShell, you will need to first save your list as a List Template and then create a new copy of the list using that template. Saving a list as a template is as simple as calling the SaveAsTemplate() method on a SharePoint list instance. This method requires you to specify a name for the resulting .stp (template) file, a title for your template, a description, and lets you specify if you’d like to save the list’s content and data as part of the template:

$web = Get-SPWeb http://localhost
$list = $web.Lists["My List"]
$list.SaveAsTemplate("MyTemplate", "My Template", "This is my custom list", $true)

Custom list templates in SharePoint are stored at the site collection level. To get a list of available custom list templates, you’ll need to call the GetCustomListTemplates() method on the site collection object (see Figure 6-20):

$site = Get-SPSite http://localhost
$customTemplates = $site.GetCustomListTemplates($site.RootWeb)

With this information in hand, you are now ready to create a new list using your custom list template. This will result in a new copy of the original SharePoint list to be created. You will need to begin by obtaining a reference to your custom list. This can be achieved by calling the following line of PowerShell:

$myListTemplate = $customTemplates | Where {$_.Name -eq "My Template"}

To create the copy of your list, you will need to call the Add() method on a specific web list collection, like you did in the “Creating a New List” section. This time, however, you will call an overload of the method, meaning that you will call the method using a different set of parameters as input. In order to create a list based on a custom list template, you need to call the method using six parameters as shown here:

$web.Lists.Add("My Copy", # Title
        "Description", # List Description
        "Lists/MyCopy", # Relative URL $myListTemplate.FeatureId, # Feature Id of custom template
        100, # List Type - 100 is for none
        "101") # Document Template Type - 101 is for none

Remember that there is an opportunity to create your own cmdlet to automate these two operations into a single one. You could easily create a new Copy-SPList cmdlet taking the source list, and its destination title as input parameters.

Putting It Together: Creating Common Lists

I will now continue to build upon this demo environment, and put your latest acquired knowledge to use. In real-life scenarios, business units will most likely share some very similar processes. For example, every business unit in an organization will be subject to a set of policies, procedures, and guidelines. It would be considered best practice to keep all documents related to these in a SharePoint document library under each business unit workspace. Another important feature that each business unit may also want to have is a task list to allow various tasks assigned to their employees to be tracked.

You will create a new PowerShell script that will iterate through all the various sites created earlier, and that will create a new document library at its root named “Business Documents” as well as a new task list named “Unit Tasks.” The following script will allow you to do just that, but this time you’ll add a little twist to it. In the previous demo (“Putting it Together: Creating Support Webs”), you had obtained references to each site collection by generating their URLs dynamically. This time around, you will delve into some of the material covered in the next chapters to obtain a reference to the SharePoint web application that you’ve created on port 80. Remember, a web application can be thought of as a container for site collections. All site collections that are hosted on port 80 logically belong to the same web application. By obtaining a reference to this object, you will be able to iterate through all of its contained site collections, and then in turn iterate through the set of webs they each contain:

$webApp = Get-SPWebApplication http://localhost
 
foreach($site in $webApp.Sites)
{
    foreach($web in $site.AllWebs)
    {
        $web.Lists.Add("Business Documents", "",
            $web.ListTemplates["Document Library"]);
        $web.Lists.Add("Unit Tasks", "", $web.ListTemplates["Tasks"]);
    }
}

As you can see from this example, in order to get a reference to a SharePoint web application, you can call the Get-SPWebApplication PowerShell cmdlet.

Getting List Items

To obtain a reference to a list item, you need to obtain a reference to the list that contains it. Once the reference has been obtained, you can get access to a collection of all list items contained in the list by calling the Items property on it. Other than accessing an item directly by its position in the list  (e.g., $list.Items[2] where 2 is the position in the list) there is no way to obtain a reference to a single list item in SharePoint. The best you can do to get a reference to a specific item is to query a collection of items back based on certain criteria, and hope that there is only one item contained in it.

To get a collection of items back, you could either write a CAML query and use it to get a specific set of items back from a list, or you could simply use PowerShell to iterate through the collection of returned items and find the item based on a specific property’s value. Both options are explained in the following example. Figure 6-21 shows the SharePoint list used for the example.

# Assuming a SharePoint List that contains a list of fruits and their unit price.
 
$web = Get-SPWeb http://localhost
$fruitsList = $web.Lists["Fruits"]
 
# Scenario A - Get a reference to the apple item
 
# Option 1 - Write a CAML Query
$query = "<Where><Eq><FieldRef Name='Title' /><Value Type='Text'>Apple</Value></Eq></Where>";
$spQuery = New-Object Microsoft.SharePoint.SPQuery
$spQuery.Query = $query
 
$items = $fruitsList.GetItems($spQuery)
$items[0].Title
 
# Option 2 - Use PowerShell to query by property
$items = $fruitsList.Items | Where {$_.Title -eq "Apple"}
$items.Title

Here is a second example using the same list, to obtain a list of all items that have a unit price of 4$ or more:

# Scenario B - Get items that are 4$ and over
 
# Option 1 - Write a CAML Query
$query = "<Where><Gt><FieldRef Name='Price' /><Value Type='Currency'>4</Value></Gt></Where>"
$spQuery = New-Object Microsoft.SharePoint.SPQuery
$spQuery.Query = $query
 
$expItems = $fruitsList.GetItems($spQuery)
 
# Option 2 - Use PowerShell to query by property
$expItems = $fruitsList.Items | Where{$_["Price"] -gt 4}

Removing a List Item

The operation to delete a list items is fairly simple. All you need to do is obtain the ID of the object that you wish to delete, and then call the Delete() method on the list’s item collection, passing the item’s position in the list as a parameter. As with webs and lists, a deleted list item makes it into the site’s recycle bin and can be restored or deleted from there. As always, remember that only list items that have been deleted through the SharePoint interface are given a second chance in the recycle bin. Those deleted through PowerShell are deleted permanently.

You need to pay special attention when deleting an item from a SharePoint list. The index you’re passing to the Delete() method is actually referencing the position of the item to delete in the list. Simply getting the ID position of the object may not end up deleting the proper object. IDs assigned to items in a list are automatically incremented. Once an item has been deleted, its ID stays reserved, and no other items in that list can have the same id. This could prove to be very confusing, and often results in catastrophic results when forgotten.

For example, assume that you have a list of five different items, say user names. When the list first gets created, all items are given a unique number starting from 1 to 5; this is their ID property. In addition, items in a list are also assigned a relative position in the list, based on the order in which they were added. In the beginning, our five users are all assigned a position number that matches their ID. The next user to be added to the list will automatically be granted an ID of 6, with a position value of 6. Now, let’s assume that user #2 is deleted; what happens to the position values? User #3 will now be shifted down one position in the list, and so will the other three users. Only user #1 will keep its original position. With this in mind, if you were to call the Delete() method passing a position value of 4 as a parameter, user #5 is the user that would actually be deleted.

To make sure that you delete the appropriate item in your list, you need to loop through the list of items and get their exact positions. Then you can call the Delete() method on the collection to have the proper item deleted. To illustrate this, see the SharePoint list in Figure 6-24. I’ve used the following PowerShell code to list each item in the list along with their current position:

$web = Get-SPWeb http://localhost
$fruitsList = $web.Lists["Fruits"]
$position = 0
foreach($fruit in $fruitsList.Items)
{
     Write-Host "Position $position :" $fruit.Title "- ID: " $fruit.Id: $position++
}

The following lines of code will loop through the entire collection of items and compare each item’s ID with the ID of the apple item. If a match is found, then the item at the current position (the apple item) will be removed from the collection (see Figure 6-25):

$web = Get-SPWeb http://localhost
$fruitsList = $web.Lists["Fruits"]
$appleItem = $fruitsList.Items | Where {$_.Title -eq "Apple"}
$appleId = $appleItem.ID
 
$position = 0;
foreach($fruit in $fruitsList.Items)
{
    if($fruit.ID -eq $appleId)
    {
        $fruitsList.Items.Delete($position)
    }
    $position++ # Increases the current position
}

Creating a List Item

There are two methods available in the object model that will allow you to create a new list item in a list. The first one is the AddItem() method from the SharePoint list object, and the second is the Add() method available on the collection of items associated with a list. Both methods have the exact same behavior. You can simply use the one you prefer. You should always remember to use the Update() method on an item once you’ve created it; otherwise, it will not get registered with its parent list and, therefore, won’t be accessible through the SharePoint interface. Figure 6-26 shows the results of using the two methods included in the following code:

$web = Get-SPWeb http://localhost
$fruitsList = $web.Lists["Fruits"]
 
$newItem1 = $fruitsList.AddItem()
$newItem1["Title"] = "Kiwi";
$newItem1["Price"] = 6.99;
$newItem1.Update()
 
$newItem2 = $fruitsList.Items.Add()
$newItem2["Title"] = "Grape"
$newItem2["Price"] = 5.99
$newItem2.Update()

Updating a List Item

Just like any good artifacts supporting CRUD (create, read, update, and delete) operations, list items in SharePoint allow you to update an existing item’s properties. What you’ll need to do is to first get a reference to the item you wish to update, and then modify the value of the property you wish to change by accessing it directly in the fields’ collection. In the current example, a common scenario may be to update the unit price of a specific fruit on a regular basis. The following lines of PowerShell script provide more details on how you could achieve this update, which is then shown in Figure 6-27. Note that once you’ve modified a list item’s property, you do need to call the Update() method on it for the changes to be reflected.

$web = Get-SPWeb http://localhost
$fruitsList = $web.Lists["Fruits"]
 
$bananaItem = $fruitsList.Items | Where {$_.Title -eq "Banana"}
$bananaItem["Price"] = 0.99
$bananaItem.Update()

Putting It Together: Creating Default Tasks Items

In this section, you’ll continue building on your SharePoint organizational workspaces. The goal of this exercise is to loop through all the various business unit sites that you have and add a default task in each team’s “Unit Tasks” list. The default task will simply be called “Get familiar with your unit’s SharePoint workspace,” and it will have a deadline scheduled a week from today. The key thing to take from this exercise is that you will have to use objects that are of the SharePoint scope, and use objects that are built in the core .NET Framework. In this case, you will be using the .NET DateTime object to get next week’s date.

$webApp = Get-SPWebApplication http://localhost
 
foreach($site in $webApp.Sites)
{
    foreach($web in $site.AllWebs)
    {
        $list = $web.Lists["Unit Tasks"]
        $newTask = $list.AddItem();
        $newTask["Title"] = "Get familiar with your unit's SharePoint workspace"
        $today = [System.DateTime]::Now
        $nextWeek = $today.AddDays(7)
        $newTask["DueDate"] = $nextWeek
        $newTask.Update()
    }
}

Getting an Instance of a Field

You’ve already seen how to get a reference to a specific field’s value in the previous section’s examples. When you called a list item property by using a field’s internal name as an index, you’re actually getting a reference to a specific field’s value for a given item. For example, calling $item["FieldName"] will return the value of field "FieldName" associated with the list item $item. To get a reference to the actual field, all you need to do it use the internal name of the field as an index on the list object’s Fields property. This property represents an array containing all of the fields associated with a SharePoint list. The following lines of PowerShell script will create a new SharePoint list, and will iterate through all of its fields and display their internal names:

$web = Get-SPWeb http://localhost
$listID = $web.Lists.Add("DemoList", "", $web.ListTemplates["Custom List"])
$list = $web.Lists[$listID]
foreach($field in $list.Fields)
{
    write-host $field.InternalName" - Hidden:" $field.Hidden" - ReadOnly:" field.ReadOnlyField
}

You will see that some fields listed by the script in Figure 6-28 will look familiar (e.g., title, author, and attachments). Others, however, aren’t recognizable. These are most likely hidden fields that are required by SharePoint. In addition to having a data type defining the type of value that they can accept, fields can have two other properties that can be set to determine their behaviors: the ReadOnlyField and the Hidden properties. One of these two properties set to true on a field will normally indicate that this field is reserved by SharePoint.

Creating a New Field

Fields are created by calling the Add() method on the array of fields associated with a SharePoint list instance. When calling this method, you will need to specify a title for the field, the type of data this field should be accepting, as well as specifying if the field is required or not.

$web = Get-SPWeb http://localhost
$demoList = $web.Lists["DemoList"]
$fieldID = $demoList.Fields.Add("HairColor", [Microsoft.SharePoint.SPFieldType]::Choice, $true)
$myNewChoiceField = $demoList.Fields["HairColor"]
 
$myNewChoiceField.Choices.Add("Brown")
$myNewChoiceField.Choices.Add("Blond")
$myNewChoiceField.Choices.Add("Red")
$myNewChoiceField.Choices.Add("Black")
$myNewChoiceField.Choices.Add("Grey")
$myNewChoiceField.Choices.Add("None")
 
# Need to call the Update() method in order for the choices to appear on interface
$myNewChoiceField.Update()

As you can see in Figure 6-29, the new field has been created in SharePoint with all the values that you provided in PowerShell.

Removing a Field

To remove a field, simply get a reference to the field in question and call the Delete() method on it. The operation of deleting a field is permanent and cannot be recovered. Once a field has been deleted, all of the data that was contained in it is removed as well.

$web = Get-SPWeb http://localhost
$demoList = $web.Lists["DemoList"]
$field = $demoList.Fields["HairColor"]
$field.Delete()

List Permissions on an Object

The following request is something that always comes back: given a specific artifact in SharePoint, I want to know who has access to it. Using PowerShell, it becomes extremely easy to get such information about an object. To illustrate how to obtain information about permissions for a list, I will start by creating a new SharePoint list using PowerShell:

$web = http://localhost
$newListId = $web.Lists.Add("Secure", "", $web.ListTemplates["Custom List"])
$secureList = $web.Lists[$newListId]

By default, using the Add() method with the signature I used here will create the new list and inherit permissions from its parent web. If you want to list the permissions that are applied to it by default, you can simply get access to the RoleAssignments properties of your new list. Doing this will return a list of all users that have some level of access to your list, along with information about what their role definition is (see Figure 6-30):

$newListId = $web.Lists.Add("Secure", "", $web.ListTemplates["Custom List"])
$secureList = $web.Lists[$newListId]
$secureList.RoleAssignments

Breaking Permission Inheritance

The concept of breaking inheritance describes the scenario in which we want to stop permissions on an object from being inherited from its parent container. When breaking inheritance on a container, we are given the choice to copy the parent permissions down to the object’s permissions, or to start fresh. Once the permission inheritance has been broken on an object, modifying the permissions for its parent will not have any impact on it, and vice versa. Permissions inheritance from the parent container can be restored at any time by calling the ResetRoleInheritance() method on the object. The following example shows you how to break inheritance for your list and start fresh with no role assignments (see Figure 6-31):

$web = Get-SPWeb http://localhost
$secureList = $web.Lists["Secure"]
$secureList.BreakRoleInheritance($false)

Granting New Permissions

In order for you to be able to grant new permissions on a SharePoint artifact, you’ll need to start by determining what role definition you want to map the user to and obtain a reference to it. A role definition instance can be obtained at the web level, as shown with the following example code and in Figure 6-32:

$web = Get-SPWeb http://localhost
$fullControlRoleDefinition = $web.RoleDefinitions["Full Control"]

Once a reference has been obtained, you will need to declare a new RoleAssignment variable as follows:

$roleAssignment = New-Object Microsoft.SharePoint.SPRoleAssignment("DOMAIN\UserName","[email protected] ",
"Display_Name","Notes about the assignment");

Now comes the tricky part: linking the role definition you’ve obtained previously with the newly created SPRoleAssignment object. In order to achieve this, you need to declare a new object of type SPRoleDefinitionBindingCollecton, and associate both entities through it:

$bindings = $roleAssignment.RoleDefinitionBindings
$bindings.Add($fullControlRoleDefinition)

Once the linkage has been created, you are now ready to add your new role assignment definition to your list:

$secureList.RoleAssignments.Add($roleAssignment)

This will automatically grant Full Control permission on your secure list to the administrator account, as shown in Figure 6-33.

Removing Permissions

To remove permission for a user on a specific artifact, simply get a reference to the associated role assignment item, and remove it from the list of assignments on the artifact. For example, if you want to remove the permission that you just granted to the administrator account on your secure list, you could call the following lines of PowerShell script:

$web = Get-SPWeb http://localhost
$secureList = $web.Lists["Secure"]
$secureList.RoleAssignments.Remove($web.EnsureUser("CONTOSOAdministrator"))

Updating Permissions

The most straightforward way to update a permission would be to remove the existing one and add a completely new one. Normally, you would update only the role definition portion of an assignment; otherwise, you’d be changing the user associated with a permission entry, which really comes back to creating a new entry all together. There are no ways of updating an existing role assignment without first removing the existing one and adding a new one instead.

Scenario #1 - Bad Memory Management

The following PowerShell code example shows a scenario in which memory is not being freed up and objects not disposed of properly:

$webApp = Get-SPWebApplication http://localhost
for($i = 0; $i -le 10000; $i++)
{
    foreach($site in $webApp.Sites)
    {
        foreach($web in $site.AllWebs)
        {
            Write-host $web.Title
        }
    }
}

In Figure 6-34, you can see that the memory usage of our PowerShell script keeps increasing as time goes by without ever releasing it in a significant way. This is because all of the webs and site collection objects used by our script are kept in memory.

Scenario #2 - Good Memory Management

The following lines of PowerShell code  ensure that you dispose of objects in memory after you are done using them:

$webApp = Get-SPWebApplication http://localhost
for($i = 0; $i -le 10000; $i++)
{
    foreach($site in $webApp.Sites)
    {
        foreach($web in $site.AllWebs)
        {
            Write-host $web.Title
            $web.Dispose()
        }
        $site.Dispose()
    }
}

You can clearly see in Figure 6-35 that the memory usage has greatly improved over your previous scenario. Yes, there are spikes of memory usage, but as objects are being disposed from memory, the overall memory usage goes back to normal right away.