Getting References to Sites, Web Applications, and other Key Objects
This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This page may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.
To work with a deployment of Windows SharePoint Services, your code must first get a reference to the objects it will be working with, including Web sites, site collections, and Web applications. There are two methods for doing this: one applies when your code will be used in a console or Windows-based application; the other applies when your code will be used in a browser-hosted application, such as when you choose "Web Site" as the type of Microsoft Visual Studio project.
Note
Most sample code in the Windows SharePoint Services SDK uses the second method, so if you are writing for a console or Windows-based application, you must change the code. For guidance in doing so, see the section "Console and Windows Applications: Use Object Constructors" later in this topic.
Browser-Hosted Applications: Establish Site Context
To work with a deployment of Windows SharePoint Services by means of a browser-hosted application, your code must first establish the site context or site collection context for requests that are made to the server.
You must obtain the HTTP context of the request in the code. Microsoft recommends that you do this by using the Microsoft.SharePoint.SPContext class and its members. Some examples are as follows.
To return the current site collection, you can use CurrentSite() property.
Note
All examples in this article require a using directive (Imports in Visual Basic) for the Microsoft.SharePoint namespace.
Dim oSiteCollection As SPSite = SPContext.Current.Site
SPSite oSiteCollection = SPContext.Current.Site;
To return the Web site of the current request, you can use SPContext.Current.Web.
Dim oWebSite As SPWeb = SPContext.Current.Web
SPWeb oWebSite = SPContext.Current.Web;
Alternatively, when your code is contained in an .aspx file or the "code behind" in an .aspx.cs file, you can use methods of the SPControl object with the Page.Context property as the parameter. For example, use the GetContextWeb method to get a reference to the current Web site.
Dim oWebSite As SPWeb = SPControl.GetContextWeb(Context)
SPWeb oWebSite = SPControl.GetContextWeb(Context);
Finally, if your .aspx page inherits from UnsecuredLayoutsPageBase or LayoutsPageBase instead of Page, you can use the Site() or Web properties of the former classes to obtain references to the, respectively, the current site collection or Web site. (Or you can use the [P:System.Web.UI.Page,Context] property as the parameter to the GetContextWeb and GetContextSite methods.) LayoutsPageBase gives you some extra SharePoint-oriented functionality, mainly in connection with managing user rights to the page that is not available with Page.
For example, the following code, when used in an .aspx page that inherits from LayoutsPageBase (or the code behind the page) gets a reference to the current Web site.
Note
This example requires a using directive (Imports in Visual Basic) for the Microsoft.SharePoint.WebControls namespace.
Dim oWebSite As SPWeb = this.Web
SPWeb oWebSite = this.Web;
Warning
You should not dispose any SPSite or SPWeb object obtained by any of the above methods. The Windows SharePoint Services 3.0 runtime will dispose of them after page completion. Calling the Dispose or Close method of these objects will result in unpredictable behavior. This is in marked contrast to obtaining references to these types of objects using a constructor as described below in "Console and Windows Applications: Use Object Constructors". There are a number of nuances to the best practices with regard to when objects should and should not be disposed. Carefully study Best Practices: Using Disposable Windows SharePoint Services Objects.
To return the current top-level server farm object, use SPContext.Current.Site.WebApplication.Farm.
Dim oFarm As SPFarm = SPContext.Current.Site.WebApplication.Farm
SPFarm myFarm = SPContext.Current.Site.WebApplication.Farm;
To return the top-level Web site of the current site collection, use the RootWeb property.
Dim oTopSite As SPWeb = SPContext.Current.Site.RootWeb
SPWeb oTopSite = SPContext.Current.Site.RootWeb;
The SPContext class does not limit you to getting the current object of any given type. For example, you can use the SPSite.AllWebs property to obtain a reference to a Web site other than the current one. The following line returns the context of a specified site by using an indexer with the AllWebs property.
Dim oWebSite As SPWeb =
SPContext.Current.Site.AllWebs("myOtherSite")
SPWeb oWebSite = SPContext.Current.Site.AllWebs["myOtherSite"];
Warning
You should explicitly dispose of references to objects obtained through the AllWebs property. There are a number of nuances to the best practices with regard to when objects should and should not be disposed. Carefully study Best Practices: Using Disposable Windows SharePoint Services Objects.
Finally, to get a reference to either the server farm or the current physical server, you can use the static properties SPFarm.Local and SPServer.Local. The following line is an example.
Dim oFarm As SPFarm = SPFarm.Local
SPFarm oFarm = SPFarm.Local;
To use either of the Local properties, you must add using directive (Imports in Visual Basic) for the Microsoft.SharePoint.Administration namespace.
You can use any of the preceding techniques not only in Web applications and .aspx pages, but also in custom Web services and Web Parts.
Important
If you install "Infrastructure Update for Windows SharePoint Services 3.0 (KB951695)," custom solutions may fail if they call the SharePoint object model while impersonation is suspended. If you use Windows authentication and your code calls the SharePoint object model from an IIS worker process, the request must impersonate the calling user’s identity. Windows SharePoint Services configures ASP.NET to impersonate the calling user automatically, but your code may work unexpectedly, or fail, if you suspend impersonation--for example, by calling the RevertToSelf function of the Windows API, or by calling the System.Security.Principal.WindowsIdentity.Impersonate method and passing IntPtr.Zero as the value of the user token parameter. Even if your code does not explicitly revert to self, it might be called by ASP.NET after it reverts to self, such as happens when implementing a virtual path provider; if your code does not impersonate the calling user, it might not function properly.
Console and Windows Applications: Use Object Constructors
The SPContext class has no meaning in a console or Windows-based application. If you are writing code for either of those types of applications and you want to work with a specific site collection, use the SPSite constructor to instantiate an object that represents the site collection, as in the following example.
Note
Your code should dispose any SPSite or SPWeb object obtained by using a constructor. There are a number of nuances to the best practices with regard to when Windows SharePoint Services objects should and should not be disposed. Carefully study Best Practices: Using Disposable Windows SharePoint Services Objects.
Dim oSiteCollection As New SPSite("http://localhost")
...
oSitecollection.Dispose();
SPSite oSiteCollection = new SPSite("http://localhost");
...
oSitecollection.Dispose();
// Even better, take advantage of a "using" block to ensure
// that the object is disposed.
using (SPSite oSiteCollection = new SPSite("http://localhost"))
{
...
}
Note
The "localhost" is a Windows alias for the computer on which the code is running. For console applications, Microsoft recommends that you always use "localhost" instead of the actual server name. This is because a console application can only operate on the local computer anyway. If you hard code a server name, such as "MyServer", then your console application cannot be ported to another computer and your console applications will break if the server's name is ever changed.
After you have a reference to a collection, you can use the AllWebs collection to obtain a reference to a particular web site in the collection.
Dim oWebSite As SPWeb
oWebSite = mySiteCollection.AllWebs("mySite")
...
oWebSite.Dispose();
SPWeb oWebSite = mySiteCollection.AllWebs["mySite"];
...
oWebSite.Dispose();
// Even better, take advantage of a "using" block to ensure
// that the object is disposed.
using (SPWeb oWebSite = mySiteCollection.AllWebs["mySite"])
{
...
}
Alternatively, you can use the OpenWeb method as shown in the following line.
Dim oWebSite As SPWeb
oWebSite = mySiteCollection.OpenWeb("mySite")
...
oWebSite.Dispose();
SPWeb oWebSite = mySiteCollection.OpenWeb("mySite");
...
oWebSite.Dispose();
// Even better, take advantage of a "using" block to ensure
// that the object is disposed.
using (SPWeb oWebSite = mySiteCollection.OpenWeb("mySite"))
{
...
}
See Also
Reference
Determining Where to Build a Custom Application
Concepts
How Do I... in Windows SharePoint Services
Working with List Objects and Collections
Other Resources
Best Practices: Using Disposable Windows SharePoint Services Objects