SharePoint のクライアント ライブラリ コードを使用して基本的な操作を完了するComplete basic operations using SharePoint client library code

SharePoint クライアント オブジェクト モデル (CSOM) を使用して、SharePoint でデータを取得、更新、および管理できます。You can use the SharePoint client object model (CSOM) to retrieve, update, and manage data in SharePoint. SharePoint では、次のようなさまざまな形で CSOM を使用できます。SharePoint makes the CSOM available in several forms:

  • .NET Framework 再頒布可能アセンブリ.NET Framework redistributable assemblies
  • JavaScript ライブラリJavaScript library
  • REST/OData エンドポイントREST/OData endpoints
  • Windows Phone アセンブリWindows Phone assemblies
  • Silverlight 再頒布可能アセンブリSilverlight redistributable assemblies

SharePoint プラットフォームで利用できる API セットの詳細については、「SharePoint で適切な API セットを選択する」を参照してください。For more information about the sets of APIs available on the SharePoint platform, see Choose the right API set in SharePoint.

この記事では、.NET Framework オブジェクト モデルを使用して基本的な操作を実行する方法を説明します。これは、Microsoft ダウンロード センターから再頒布可能パッケージとして入手できます (「SharePoint Server 2013 クライアント コンポーネント SDK」または「SharePoint Online クライアント コンポーネント SDK」を検索)。This article shows how to perform basic operations by using the .NET Framework object model, which is available as a redistributable package on the Microsoft Download Center (search for "SharePoint Server 2013 Client Components SDK" or "SharePoint Online Client Components SDK").

その他のクライアント API の使用方法については、次を参照してください。For information about how to use the other client APIs, see:

SharePoint .NET クライアント オブジェクト モデルを使用した基本的な操作Basic operations with the SharePoint .NET client object model

以降のセクションで、プログラムで完了できるタスクについて説明します。説明には、CSOM の操作を例示する C# コード例が含まれます。The following sections describe tasks that you can complete programmatically, and they include C# code examples that demonstrate CSOM operations.

Visual Studio 2012 で SharePoint 用のアドインを作成すると、.NET Framework アセンブリ、Microsoft.SharePoint.Client.Runtime.dllMicrosoft.SharePoint.Client.dll への参照がプロジェクトに自動的に追加されます。When you create an Add-in for SharePoint project in Visual Studio 2012, references to the .NET Framework assemblies, Microsoft.SharePoint.Client.Runtime.dll and Microsoft.SharePoint.Client.dll, are automatically added to the project. .NET Framework アプリケーションやコンソール アプリケーションなどの他の種類のプロジェクトでは、これらの参照を追加する必要があります。For other kinds of projects, such as .NET Framework applications or console applications, you should add these references. どの SharePoint サーバーでも、ファイルは %ProgramFiles%\Common Files\Microsoft Shared\web server extensions\15\ISAPI にあります。The files are located on any SharePoint server at %ProgramFiles%\Common Files\Microsoft Shared\web server extensions\15\ISAPI.

これらの例では、コードは Microsoft ASP.NET Web ページ用の分離コード ファイルに記述するものとします。All of these examples assume that the code is in a code-behind file for a Microsoft ASP.NET webpage. 次の using ステートメントをこのコード ファイルに追加する必要があります。You must add the following using statement to the code file.

using Microsoft.SharePoint.Client;

特に明記しない限り、これらの例は、ページのクラスに定義されるパラメーターなしメソッド内に記述するものとします。Except where specified otherwise, you can assume that each of these examples is in a parameterless method that is defined in the page's class. また、label1label2 などは、ページの Label オブジェクトの名前です。Also, label1, label2, and so on, are the names of Label objects on the page.

注意

プロバイダー向けのホスト型 SharePoint アドインを ASP.NET Web アプリケーションで作成する際に、アセンブリへの参照を Visual Studio でこの Web アプリケーション プロジェクトに追加する場合は、アセンブリが Web サーバーにインストール済みであるか、アドインの展開前にインストールされることが確実な場合を除き、アセンブリの Copy Local プロパティを True に設定します。When you are making a provider-hosted SharePoint Add-in with an ASP.NET web application, and you add a reference to an assembly to the web application project in Visual Studio, set the Copy Local property of the assembly to True, unless you know that the assembly is already installed on the web server, or you can ensure that it is installed before you deploy your add-in.

.NET Framework は、Microsoft Azure Web ロールと Azure Web サイトにインストールされます。The .NET Framework is installed on Microsoft Azure Web Roles and Azure websites. ただし、SharePoint クライアント アセンブリと、各種の Microsoft マネージ コード拡張機能や基盤はインストールされません。But the SharePoint client assemblies and the various Microsoft managed code extensions and foundations are not installed. Office Developer Tools for Visual Studio 2012 は、SharePoint アドインでよく使われるいくつかのアセンブリへの参照を自動的に追加し、Copy Local プロパティを設定します。Office Developer Tools for Visual Studio 2012 automatically adds references to some assemblies commonly used in SharePoint Add-ins and sets the Copy Local property.

SharePoint Web サイトのタスクSharePoint website tasks

以下の例は、.NET Framework CSOM を使用して Web サイトに関連するタスクを完了する方法を示しています。These examples show how to use the .NET Framework CSOM to complete website-related tasks.

Web サイトのプロパティを取得するRetrieve the properties of a website

SharePoint Web サイトのタイトルを取得します。Retrieve the title of a SharePoint website.


// Starting with ClientContext, the constructor requires a URL to the 
// server running SharePoint. 
ClientContext context = new ClientContext("http://SiteUrl"); 

// The SharePoint web at the URL.
Web web = context.Web; 

// We want to retrieve the web's properties.
context.Load(web); 

// Execute the query to the server.
context.ExecuteQuery(); 

// Now, the web's properties are available and we could display 
// web properties, such as title. 
label1.Text = web.Title;


Web サイトの選択したプロパティのみを取得するRetrieve only selected properties of a website

クライアントの関心が、オブジェクトの一部のプロパティのみにある場合があります。Sometimes, the client is interested only in a few properties of an object. SharePoint .NET Framework CSOM では、サーバー上のオブジェクトからすべてのプロパティを取得する必要はありません。ラムダ式を使用できる匿名メソッドを使用して、特定のプロパティ名を要求できます。The SharePoint .NET Framework CSOM does not require you to get all properties from the object on a server—you can use anonymous methods, which can be lambda expressions, to specifically request property names. クライアント ライブラリは、サーバー上で要求されたプロパティのみのクエリを実行し、サーバーはそれらのプロパティのみをクライアントに送信します。The client library queries only for those properties on the server, and the server sends only those properties to the client. このテクニックを使うと、クライアントとサーバー間の不要なデータ転送を削減できます。This technique reduces unnecessary data transfer between the client and the server. また、オブジェクトのその他の未使用プロパティの中に、ユーザーがアクセス許可を持っていないものがある場合にも有用です。It is also useful when the user does not have permission to one or more of the other, unused properties on an object.

System.Linq 用の using ステートメントを追加する必要があることにご注意ください。Note that you need to add a using statement for System.Linq.

// Starting with ClientContext, the constructor requires a URL to the 
// server running SharePoint. 
ClientContext context = new ClientContext("http://SiteUrl"); 

// The SharePoint web at the URL.
Web web = context.Web; 

// We want to retrieve the web's title and description. 
context.Load(web, w => w.Title, w => w.Description); 

// Execute the query to server.
context.ExecuteQuery(); 

// Now, only the web's title and description are available. If you 
// try to print out other properties, the code will throw 
// an exception because other properties are not available. 
label1.Text = web.Title;
label1.Text = web. Description;

注意

他のプロパティにアクセスしようとした場合、他のプロパティは使用できないため、このコードは例外をスローします。If you try to access other properties, the code throws an exception because other properties are not available.


Web サイトのプロパティに書き込むWrite to website's properties

次の例は、Web サイトのプロパティに書き込む方法を示しています。This example shows how to write to the website's properties.

// Starting with ClientContext, the constructor requires a URL to the 
// server running SharePoint. 
ClientContext context = new ClientContext("http://SiteUrl"); 

// The SharePoint web at the URL.
Web web = context.Web; 

web.Title = "New Title"; 
web.Description = "New Description"; 

// Note that the web.Update() does not trigger a request to the server
// because the client library until ExecuteQuery() is called. 
web.Update(); 

// Execute the query to server.
context.ExecuteQuery(); 


新しい SharePoint Web サイトを作成するCreate a new SharePoint website

次の例は、新しい SharePoint サイトを、現在の Web サイトのサブサイトとして作成する方法を示しています。This example shows how to create a new SharePoint site as a subsite of the current website. 新しい Web サイトを作成するには、WebCreationInformation クラスを使用します。Use the WebCreationInformation class to create a new website. System.Collections.Generic および System.Text 用の using ステートメントも追加する必要があります。You also need to add using statements for System.Collections.Generic and System.Text.

// Starting with ClientContext, the constructor requires a URL to the 
// server running SharePoint. 
ClientContext context = new ClientContext("http://SiteUrl"); 

WebCreationInformation creation = new WebCreationInformation(); 
creation.Url = "web1"; 
creation.Title = "Hello web1"; 
Web newWeb = context.Web.Webs.Add(creation); 

// Retrieve the new web information. 
context.Load(newWeb, w => w.Title); 
context.ExecuteQuery(); 

label1.Text = newWeb.Title; 


SharePoint リストのタスクSharePoint list tasks

以下の例は、.NET Framework CSOM を使用して、リストに関連するタスクを完了する方法を示しています。These examples show how to use the .NET Framework CSOM to complete list-related tasks.

Web サイト内のすべての SharePoint リストを取得するRetrieve all SharePoint lists in a website

次の例では、SharePoint Web サイト内のすべての SharePoint リストを取得します。This example retrieves all SharePoint lists in a SharePoint website. このコードをコンパイルするには、System.Linq 用の using ステートメントを追加する必要があります。To compile this code, you need to add a using statement for System.Linq.

// Starting with ClientContext, the constructor requires a URL to the 
// server running SharePoint. 
ClientContext context = new ClientContext("http://SiteUrl"); 

// The SharePoint web at the URL.
Web web = context.Web; 

// Retrieve all lists from the server. 
context.Load(web.Lists, 
             lists => lists.Include(list => list.Title, // For each list, retrieve Title and Id. 
                                    list => list.Id)); 

// Execute query. 
context.ExecuteQuery(); 

// Enumerate the web.Lists. 
foreach (List list in web.Lists) 
{ 
    label1.Text = label1.Text + ", " + list.Title; 
} 


注意

あるいは、web.Lists プロパティではなく LoadQuery メソッドを使用して、戻り値を別のコレクションに格納することもできます。Alternatively, you can use the LoadQuery method to store the return value in another collection, rather than use the web.Lists property. System.Collections.Generic および System.Linq 用の using ステートメントも追加する必要があります。You will also need to add using statements for System.Collections.Generic and System.Linq. さらに、Microsoft.SharePoint.Client 名前空間用の using ステートメントに対するエイリアスを追加して、そのクラスを明確に参照できるようにします。Also, add an alias to the using statement for the Microsoft.SharePoint.Client namespace so you can refer to its classes unambiguously. 例: using SP = Microsoft.SharePoint.Client;For example, using SP = Microsoft.SharePoint.Client;.


// Starting with ClientContext, the constructor requires a URL to the 
// server running SharePoint. 
ClientContext context = new ClientContext("http://SiteUrl"); 

// The SharePoint web at the URL.
Web web = context.Web; 

// Retrieve all lists from the server, and put the return value in another 
// collection instead of the web.Lists. 
IEnumerable<SP.List> result = context.LoadQuery(web.Lists.Include( // For each list, retrieve Title and Id.
                                                                   list => list.Title, 
                                                                   list => list.Id)); 

// Execute query. 
context.ExecuteQuery(); 

// Enumerate the result. 
foreach (List list in result) 
{ 
    label1.Text = label1.Text + ", " + list.Title; 
} 


SharePoint リストを作成および更新するCreate and update a SharePoint list

次の例では、ListCreationInformation クラスを使用して、SharePoint リストの作成と更新を行います。This example creates a SharePoint list and updates it by using the ListCreationInformation class.

// Starting with ClientContext, the constructor requires a URL to the 
// server running SharePoint. 
ClientContext context = new ClientContext("http://SiteUrl"); 

// The SharePoint web at the URL.
Web web = context.Web; 

ListCreationInformation creationInfo = new ListCreationInformation(); 
creationInfo.Title = "My List"; 
creationInfo.TemplateType = (int)ListTemplateType.Announcements; 
List list = web.Lists.Add(creationInfo); 
list.Description = "New Description"; 

list.Update(); 
context.ExecuteQuery(); 


SharePoint リストを削除するDelete a SharePoint list

次の例では、SharePoint リストを削除します。This example deletes a SharePoint list.

// Starting with ClientContext, the constructor requires a URL to the 
// server running SharePoint. 
ClientContext context = new ClientContext("http://SiteUrl"); 

// The SharePoint web at the URL.
Web web = context.Web; 

List list = web.Lists.GetByTitle("My List"); 
list.DeleteObject(); 

context.ExecuteQuery();  


SharePoint リストにフィールドを追加するAdd a field to a SharePoint list

次の例では、SharePoint リストにフィールドを追加します。This example adds a field to a SharePoint list. Microsoft.SharePoint.Client 名前空間用の using ステートメントに対するエイリアスを追加して、そのクラスを明確に参照できるようにします。Add an alias to the using statement for the Microsoft.SharePoint.Client namespace so you can refer to its classes unambiguously. 例: using SP = Microsoft.SharePoint.Client;For example, using SP = Microsoft.SharePoint.Client;.

注意

この例では、context.CastTo を使用してキャストを行います。The example uses context.CastTo to do a cast. クライアント ライブラリは、クエリの実行前は、返されるオブジェクト "フィールド" の実際の型がわからないため、SharePoint.Field が唯一の可能な型になります。Before executing the query, the client library does not know the real type of the returned object "field", and SharePoint.Field is the only possible type. 実際の型がわかっている場合は、ClientContext.CastTo メソッドを使用してオブジェクトをキャストできます。If you know the real type, you can use the ClientContext.CastTo method to cast the object.

// Starting with ClientContext, the constructor requires a URL to the 
// server running SharePoint. 
ClientContext context = new ClientContext("http://SiteUrl"); 

SP.List list = context.Web.Lists.GetByTitle("Announcements"); 

SP.Field field = list.Fields.AddFieldAsXml("<Field DisplayName='MyField2' Type='Number' />", 
                                           true, 
                                           AddFieldOptions.DefaultValue); 
SP.FieldNumber fldNumber = context.CastTo<FieldNumber>(field); 
fldNumber.MaximumValue = 100; 
fldNumber.MinimumValue = 35; 
fldNumber.Update(); 

context.ExecuteQuery();  


SharePoint リスト アイテムのタスクSharePoint list item tasks

以下の例は、.NET Framework CSOM を使用して、リスト アイテムに関連するタスクを完了する方法を示しています。These examples demonstrate how to use the .NET Framework CSOM to complete tasks that are related to list items.

SharePoint リストからアイテムを取得するRetrieve items from a SharePoint list

次の例では、SharePoint リスト内のアイテムを取得します。This example retrieves the items in a SharePoint list. Microsoft.SharePoint.Client.QueryExpression 用の using ステートメントも追加する必要があります。You also need to add a using statement for Microsoft.SharePoint.Client.QueryExpression.

注意

FolderServerRelativeUrl プロパティを使用して、特定のフォルダーに返されるアイテムを制限できます。You can use the FolderServerRelativeUrl property to further restrict the items that are returned to those in a specified folder.

// Starting with ClientContext, the constructor requires a URL to the 
// server running SharePoint. 
ClientContext context = new ClientContext("http://SiteUrl"); 

// Assume the web has a list named "Announcements". 
List announcementsList = context.Web.Lists.GetByTitle("Announcements"); 

// This creates a CamlQuery that has a RowLimit of 100, and also specifies Scope="RecursiveAll" 
// so that it grabs all list items, regardless of the folder they are in. 
CamlQuery query = CamlQuery.CreateAllItemsQuery(100); 
ListItemCollection items = announcementsList.GetItems(query); 

// Retrieve all items in the ListItemCollection from List.GetItems(Query). 
context.Load(items); 
context.ExecuteQuery(); 
foreach (ListItem listItem in items) 
{ 
    // We have all the list item data. For example, Title. 
    label1.Text = label1.Text + ", " + listItem["Title"]; 
} 


新しいリスト アイテムを作成するCreate a new list item

次の例では、ListItemCreationInformation クラスを使用して新しい SharePoint リスト アイテムを作成します。This example creates a new SharePoint list item by using the ListItemCreationInformation class.

// Starting with ClientContext, the constructor requires a URL to the 
// server running SharePoint. 
ClientContext context = new ClientContext("http://SiteUrl"); 

// Assume that the web has a list named "Announcements". 
List announcementsList = context.Web.Lists.GetByTitle("Announcements"); 

// We are just creating a regular list item, so we don't need to 
// set any properties. If we wanted to create a new folder, for 
// example, we would have to set properties such as 
// UnderlyingObjectType to FileSystemObjectType.Folder. 
ListItemCreationInformation itemCreateInfo = new ListItemCreationInformation(); 
ListItem newItem = announcementsList.AddItem(itemCreateInfo); 
newItem["Title"] = "My New Item!"; 
newItem["Body"] = "Hello World!"; 
newItem.Update(); 

context.ExecuteQuery();  


リスト アイテムを更新するUpdate a list item

次の例では、SharePoint リスト アイテムを更新します。This example updates a SharePoint list item.

// Starting with ClientContext, the constructor requires a URL to the 
// server running SharePoint. 
ClientContext context = new ClientContext("http://SiteUrl"); 

// Assume that the web has a list named "Announcements". 
List announcementsList = context.Web.Lists.GetByTitle("Announcements"); 

// Assume there is a list item with ID=1. 
ListItem listItem = announcementsList.GetItemById(1); 

// Write a new value to the Body field of the Announcement item.
listItem["Body"] = "This is my new value!!"; 
listItem.Update(); 

context.ExecuteQuery();  


リスト アイテムを削除するDelete a list item

次の例では、SharePoint リスト アイテムを削除します。This example deletes a SharePoint list item.

// Starting with ClientContext, the constructor requires a URL to the 
// server running SharePoint. 
ClientContext context = new ClientContext("http://SiteUrl"); 

// Assume that the web has a list named "Announcements". 
List announcementsList = context.Web.Lists.GetByTitle("Announcements"); 

// Assume that there is a list item with ID=2. 
ListItem listItem = announcementsList.GetItemById(2); 
listItem.DeleteObject(); 

context.ExecuteQuery(); } 


SharePoint フィールド タスクSharePoint field tasks

以下の例は、SharePoint .NET Framework CSOM を使用して、フィールドに関連するタスクを完了する方法を示しています。These examples show how to use the SharePoint .NET Framework CSOM to complete field-related tasks.

リスト内のすべてのフィールドを取得するRetrieve all of the fields in a list

次の例では、SharePoint リスト内のすべてのフィールドを取得します。This example retrieves all of the fields in a SharePoint list. さらに、Microsoft.SharePoint.Client 名前空間用の using ステートメントに対するエイリアスも追加して、そのクラスを明確に参照できるようにする必要があります。例: using SP = Microsoft.SharePoint.Client;You also need to add an alias to the using statement for the Microsoft.SharePoint.Client namespace so you can refer to its classes unambiguously; for example, using SP = Microsoft.SharePoint.Client;.

// Starting with ClientContext, the constructor requires a URL to the 
// server running SharePoint. 
ClientContext context = new ClientContext("http://SiteUrl"); 

SP.List list = context.Web.Lists.GetByTitle("Shared Documents"); 
context.Load(list.Fields); 

// We must call ExecuteQuery before enumerate list.Fields. 
context.ExecuteQuery(); 

foreach (SP.Field field in list.Fields) 
{ 
    label1.Text = label1.Text + ", " + field.InternalName;
} 


リストから特定のフィールドを取得するRetrieve a specific field from the list

特定のフィールドに関する情報を取得する場合は、Fields.GetByInternalNameOrTitle メソッドを使用します。If you want to retrieve information about a specific field, use the Fields.GetByInternalNameOrTitle method. このメソッドの戻り値の型は Field です。The return type of this method is Field. クライアントは、クエリの実行前はオブジェクトの型がわからないため、それを派生型にキャストするための C# 構文は使用できません。Before the query is executed, the client does not know the type of object, and C# syntax is not available for casting it to the derived type. したがって、ClientContext.CastTo メソッドを使用してキャストを行い、クライアント ライブラリにオブジェクトを再作成するように命令します。Therefore, use the ClientContext.CastTo method to cast it, which instructs the client library to recreate an object. System.Collections.Generic 用の using ステートメントも追加する必要があります。You also need to add a using statement for System.Collections.Generic. さらに、Microsoft.SharePoint.Client 名前空間用の using ステートメントに対するエイリアスも追加して、そのクラスを明確に参照できるようにする必要があります。You also need to add an alias to the using statement for the Microsoft.SharePoint.Client namespace so you can refer to its classes unambiguously. 例: using SP = Microsoft.SharePoint.Client;For example, using SP = Microsoft.SharePoint.Client;.

注意

この例で使用されている GetByInternalNameOrTitle メソッドは、リモート メソッドです。The GetByInternalNameOrTitle method used in this example is a remote method. クライアント コレクションが既に入力されている場合でも、クライアント コレクションのデータを使用することはありません。It does not use the data from the client collection even if the client collection is already populated.

// Starting with ClientContext, the constructor requires a URL to the 
// server running SharePoint. 
ClientContext context = new ClientContext("http://SiteUrl"); 

SP.List list = context.Web.Lists.GetByTitle("Shared Documents"); 
SP.Field field = list.Fields.GetByInternalNameOrTitle("Title"); 
FieldText textField = context.CastTo<FieldText>(field); 
context.Load(textField); 
context.ExecuteQuery(); 

// Now, we can access the specific text field properties. 
label1.Text = textField.MaxLength; 


SharePoint ユーザー タスクSharePoint user tasks

SharePoint .NET Framework CSOM を使用して、SharePoint ユーザー、グループ、およびユーザー セキュリティを管理できます。You can use the SharePoint .NET Framework CSOM to manage SharePoint users, groups, and user security.

SharePoint グループにユーザーを追加するAdd a user to a SharePoint group

次の例では、Members という名前の SharePoint グループに、ユーザーとユーザー情報を追加します。This example adds a user and some user information to a SharePoint group named Members.

// Starting with ClientContext, the constructor requires a URL to the 
// server running SharePoint. 
ClientContext context = new ClientContext("http://SiteUrl"); 

GroupCollection siteGroups = context.Web.SiteGroups; 

// Assume that there is a "Members" group, and the ID=5. 
Group membersGroup = siteGroups.GetById(5); 

// Let's set up the new user info. 
UserCreationInformation userCreationInfo = new UserCreationInformation(); 
userCreationInfo.Email = "user@domain.com"; 
userCreationInfo.LoginName = "domain\\user"; 
userCreationInfo.Title = "Mr User"; 

// Let's add the user to the group. 
User newUser = membersGroup.Users.Add(userCreationInfo); 

context.ExecuteQuery();  


SharePoint グループ内のすべてのユーザーを取得するRetrieve all users in a SharePoint group

次の例では、Members という名前の SharePoint グループからすべてのユーザーに関する情報を取得します。This example retrieves information about all users from a SharePoint group named Members.

// Starting with ClientContext, the constructor requires a URL to the 
// server running SharePoint. 
ClientContext context = new ClientContext("http://SiteUrl"); 

GroupCollection siteGroups = context.Web.SiteGroups; 

// Assume that there is a "Members" group, and the ID=5. 
Group membersGroup = siteGroups.GetById(5); 
context.Load(membersGroup.Users); 
context.ExecuteQuery(); 

foreach (User member in membersGroup.Users) 
{ 
    // We have all the user info. For example, Title. 
    label1.Text = label1.Text + ", " + member.Title; 
}  


ロールを作成するCreate a role

次の例では、アラートのアクセス許可を作成して管理するロールを作成します。This example creates a role that has create and manage alerts permissions.

// Starting with ClientContext, the constructor requires a URL to the 
// server running SharePoint. 
ClientContext context = new ClientContext("http://SiteUrl"); 

BasePermissions perm = new BasePermissions(); 
perm.Set(PermissionKind.CreateAlerts); 
perm.Set(PermissionKind.ManageAlerts); 

RoleDefinitionCreationInformation creationInfo = new RoleDefinitionCreationInformation(); 
creationInfo.BasePermissions = perm; 
creationInfo.Description = "A role with create and manage alerts permission"; 
creationInfo.Name = "Alert Manager Role"; 
creationInfo.Order = 0; 
RoleDefinition rd = context.Web.RoleDefinitions.Add(creationInfo); 

context.ExecuteQuery();  


ロールにユーザーを追加するAdd a user to a role

次の例では、ロールにユーザーを追加します。This example adds a user to a role.

// Starting with ClientContext, the constructor requires a URL to the 
// server running SharePoint. 
ClientContext context = new ClientContext("http://SiteUrl"); 

// Assume that we have a SiteUser with Login user. 
Principal user = context.Web.SiteUsers.GetByLoginName(@"domain\user"); 

// Assume that we have a RoleDefinition named "Read". 
RoleDefinition readDef = context.Web.RoleDefinitions.GetByName("Read"); 
RoleDefinitionBindingCollection roleDefCollection = new RoleDefinitionBindingCollection(context); 
roleDefCollection.Add(readDef); 
RoleAssignment newRoleAssignment = context.Web.RoleAssignments.Add(user, roleDefCollection); 

context.ExecuteQuery();  


SharePoint .NET クライアント オブジェクト モデルを使用するための規則とベスト プラクティスRules and best practices for using the SharePoint .NET client object model

以下の例は、SharePoint .NET Framework CSOM を使用する際に従う必要がある重要なベスト プラクティスと要件を示しています。These examples illustrate some important best practices and requirements you should conform to when using the SharePoint .NET Framework CSOM.

値のプロパティにアクセスする前に ClientContext.ExecuteQuery を呼び出すCall ClientContext.ExecuteQuery before accessing any value properties

SharePoint .NET Framework CSOM では、SQL に似たプログラミング パターンを使用する必要があります。つまり、データにアクセスする前に、必要なものを宣言して、クエリを実行することが必要です。The SharePoint .NET Framework CSOM requires that you use a SQL-like programming pattern: declare what you want and execute the query before you access the data. たとえば、SharePoint Web サイトのタイトル表示を試行する次のコードは、例外をスローします。For example, the following code, which attempts to display the SharePoint website's title, throws an exception.

// Starting with ClientContext, the constructor requires a URL to the 
// server running SharePoint. 
ClientContext context = new ClientContext("http://SiteUrl"); 

Web web = context.Web; 
label1.Text = web.Title;  


このコードは失敗するのは、SharePoint .NET Framework CSOM コードが次の要件を満たしていないためです。This code fails because SharePoint .NET Framework CSOM code must:

  • アドホック SQL クエリまたはストアド プロシージャをビルドする。Build either an ad hoc SQL query or a stored procedure.
  • SQL クエリを実行する。Execute the SQL query.
  • SQL から結果を読み込む。Read results from SQL.

SharePoint .NET Framework CSOM では、メソッドの呼び出し時にクエリをビルドします。In SharePoint .NET Framework CSOM, when you call a method, you build a query. クエリは蓄積され、ExecuteQuery が呼び出されるまではサーバーに送信されません。Queries accumulate and are not sent to the server until ExecuteQuery is called.

次の例は、Web サイトのタイトルを表示するために必要なコードを示しています。The following example shows the code that is required to display the website's title. System.Linq 用の using ステートメントも追加する必要があります。You also need to add a using statement for System.Linq. さらに、Microsoft.SharePoint.Client 名前空間用の using ステートメントに対するエイリアスを追加して、そのクラスを明確に参照できるようにします。Also, add an alias to the using statement for the Microsoft.SharePoint.Client namespace so you can refer to its classes unambiguously. 例: using SP = Microsoft.SharePoint.Client;For example, using SP = Microsoft.SharePoint.Client;.

// Starting with ClientContext, the constructor requires a URL to the 
// server running SharePoint. 
ClientContext context = new ClientContext("http://SiteUrl"); 

Web web = context.Web; 

context.Load(web, w => w.Title); 

context.ExecuteQuery(); 

label1.Text = web.Title;   


違いは、以下の行の追加です。1 行目は Web の Title プロパティ用のクエリを作成します。The differences are the addition of these lines; the first line creates a query for the web's Title property. 2 行目はクエリを実行します。The second line executes the query.

context.Load(web, w => w.Title); 
context.ExecuteQuery(); 


同じクエリ内のメソッドまたはプロパティから返された値オブジェクトは使用しないDo not use value objects returned from methods or properties in the same query

メソッドまたはプロパティから値オブジェクトが返される場合、クエリを実行し終わるまでそのオブジェクトは使用できません。When a value object is returned from a method or property, you cannot use that object until after you have executed the query. たとえば、次のコードは、親 Web サイトと同じタイトルの SharePoint リストの作成を試行しますが、例外をスローします。For example, the following code tries to create a SharePoint list that has the same title as the parent website, but it throws an exception.

// Starting with ClientContext, the constructor requires a URL to the 
// server running SharePoint. 
ClientContext context = new ClientContext("http://SiteUrl"); 

Web web = context.Web; 
ListCreationInformation creationInfo = new ListCreationInformation();
creationInfo.TemplateType = (int)ListTemplateType.Announcements;
creationInfo.Description = web.Title; 
creationInfo.Title = web.Title; 
List newList = web.Lists.Add(creationInfo);  


例外がスローされるのは、クエリの実行前は、プロパティを使用できないためです。An exception is thrown because the property is not available before you execute the query. SQL では、web.Title の値を保持するローカル変数を宣言し、そのローカル変数を Web の作成に使用します。In SQL, you would declare a local variable to hold the value for web.Title and use the local variable for web creation. クライアント ライブラリでは、ローカル変数は作成できません。In the client library, you can't create a local variable. 次の例に示すように、機能を 2 つの独立したクエリに分割する必要があります。You have to split functionality into two separate queries as is shown in the following example. System.Linq 用の using ステートメントも追加する必要があります。You also need to add a using statement for System.Linq. さらに、Microsoft.SharePoint.Client 名前空間用の using ステートメントに対するエイリアスを追加して、そのクラスを明確に参照できるようにします。Also, add an alias to the using statement for the Microsoft.SharePoint.Client namespace so you can refer to its classes unambiguously. 例: using SP = Microsoft.SharePoint.Client;For example, using SP = Microsoft.SharePoint.Client;.

// Starting with ClientContext, the constructor requires a URL to the 
// server running SharePoint. 
ClientContext context = new ClientContext("http://SiteUrl"); 

Web web = context.Web; 

context.Load(web, w => w.Title, w => w.Description);

context.ExecuteQuery(); 

ListCreationInformation creationInfo = new ListCreationInformation();
creationInfo.TemplateType = (int)ListTemplateType.Announcements;
creationInfo.Description = web.Description; 
creationInfo.Title = web.Title; 
SP.List newList = web.Lists.Add(creationInfo); 

context.ExecuteQuery();  


違いは、次の 3 行です。The difference is the following three lines:

context.Load(web, w => w.Title, w => w.Description);
context.ExecuteQuery(); 
...
context.ExecuteQuery(); 


クライアント オブジェクトを返すメソッドまたはプロパティを、同じクエリ内の別のメソッド呼び出しで使用するUsing methods or properties that return client objects in another method call in the same query

値オブジェクトとは異なり、クライアント オブジェクトは、同じクエリ内の別のメソッドの中で使用できます。Unlike a value object, a client object can be used in another method call in the same query.

.NET リモート処理では、値オブジェクトは値によってマーシャリングされるクラスまたは構造体であり、クライアント オブジェクトは参照によってマーシャリングされるクラスまたは構造体です。たとえば、 ListItem はクライアント オブジェクトであり、 UrlFieldValue およびその他のフィールド値は値オブジェクトです。In .NET remoting, the value object is a class or struct that is marshaled by value, while the client object is a class or struct that is marshaled by reference. For example, the ListItem is a client object, while the UrlFieldValue and other field values are value objects.

クライアント ライブラリでは、対応するサーバー オブジェクトに [ClientCallable(ValueObject = true)] 属性が設定されます。In the client library, the corresponding server object has the [ClientCallable(ValueObject = true)] attribute. これらの値は、プロパティのみを持ち、メソッドがない場合があります。Those values could have only properties and no methods. strings や ints などのプリミティブ型は、値オブジェクトとして処理されます。Primitive types, such as strings and ints, are treated as value objects. すべての値は、クライアントとサーバー間でマーシャリングされます。All the values are marshaled between the client and the server. ValueObject の既定値は false です。The default value of the ValueObject is false.

値オブジェクトに対応するオブジェクトがクライアント オブジェクトです。対応するサーバー オブジェクトに [ClientCallable(ValueObject = false)] 属性がある場合、そのオブジェクトはクライアント オブジェクトです。クライアント オブジェクトの場合は、オブジェクトの作成方法が追跡されます。クライアント ライブラリの実装では、これを ObjectPath と呼びます。たとえば、次のようなコードがあるとします。The counterpart to the value object is the client object. If the corresponding server object has the [ClientCallable(ValueObject = false)] attribute, the object is a client object. For client objects, we keep track of how the object is created; this is called ObjectPath in the client library implementation. For example, if we have code like the following:

ClientContext context = new ClientContext("http://SiteUrl"); 
Web web = context.Web; 
SP.List list = web.Lists.GetByTitle("Announcements"); 

このリストは、以下の手順で作成されることがわかっています。We know that the list is created by:

  • コンテキストから Web プロパティを取得する。Getting the Web property from the context.
  • 上の結果から Lists プロパティを取得する。Getting the Lists property from the above result.
  • 上の結果から Announcements パラメーターを使用して GetByTitle メソッドを呼び出す。Invoking the GetByTitle method with the Announcements parameter from the above result.

SharePoint .NET Framework CSOM からサーバーにこの情報が渡されると、サーバー上でオブジェクトを再作成できます。When the SharePoint .NET Framework CSOM passes this information to the server, you can recreate the object on the server. クライアント ライブラリでは、クライアント オブジェクトが作成される ObjectPath を追跡できます。In the client library, you can keep track of the ObjectPath that the client object created. オブジェクトの作成方法はわかっているので、オブジェクトをパラメーターとして使用して、同じクエリ内で別のメソッドを呼び出すことができます。Because you know how the object is created, you could use the object as a parameter to invoke other methods within the same query.

同じオブジェクトに関するデータの取得をグループ化してパフォーマンスを向上させるGroup data retrieval on the same object together to improve performance

同じオブジェクトから複数のデータを読み取る場合は、そのすべてを単一のクエリ (Load(T, []) メソッドを 1 回呼び出すこと) で取得する必要があります。When reading multiple pieces of data from the same object, you should try to get all of it in a single query; that is, a single call to the Load(T, []) method. 次のコードは、Web サイトのタイトルと説明、および Announcements リストの説明を取得するための 2 つの方法を示しています。The following code shows two ways to retrieve a website's title and description and the Announcements list's description. このコードをコンパイルするには、System.Linq 用の using ステートメントを追加する必要があります。To compile this code, you need to add a using statement for System.Linq. さらに、Microsoft.SharePoint.Client 名前空間用の using ステートメントに対するエイリアスを追加して、そのクラスを明確に参照できるようにします。Also, add an alias to the using statement for the Microsoft.SharePoint.Client namespace so you can refer to its classes unambiguously. 例: using SP = Microsoft.SharePoint.Client;For example, using SP = Microsoft.SharePoint.Client;.


static void Method1() 
{ 
    ClientContext context = new ClientContext("http://SiteUrl"); 
    Web web = context.Web; 
    SP.List list = web.Lists.GetByTitle("Announcements"); 
    context.Load(web, w => w.Title, w => w.Description); 
    context.Load(list, l => l.Description); 
    context.ExecuteQuery(); 
} 

static void Method2() 
{ 
    ClientContext context = new ClientContext("http://SiteUrl"); 
    Web web = context.Web; 
    SP.List list = web.Lists.GetByTitle("Announcements"); 
    context.Load(web, w => w.Title); 
    context.Load(list, l => l.Description); 
    context.Load(web, w => w.Description); 
    context.ExecuteQuery();  
} 


これらの効率は同じではありません。These are not equally efficient. Method1 では、Web のタイトルと説明を取得するコードがグループ化されています。In Method1, the code to retrieve the web's title and description is grouped together. Method2 では、Web のタイトルと説明を取得するコードが他のアクションによって分離されています。In Method2, the code to retrieve the web's title and description is separated by other actions. つまり、Method2 では、同じ Web オブジェクトに関して 2 つの独立したクエリがトリガーされ、同じ Web に対する 2 つの結果セットが存在することになります。This means that Method2 triggers two separated queries on the same web object, and there are two result sets for the same web. クライアント ライブラリは一貫性のあるデータを返そうとするため、2 つ目の結果セットにはタイトルと説明の両方が含まれます。Because the client library tries to return consistent data, the second result set includes both the title and description. 前のコードは、次のように見なすことができます。You could think of the previous code as the following.

Method1: 
SELECT Title, Description FROM Webs WHERE ... 
SELECT Description FROM Lists WHERE … 

Method2: 
SELECT Title FROM Webs WHERE … 
SELECT Description FROM Lists WHERE … 
SELECT Title, Description FROM Webs WHERE … 


オブジェクトのどのプロパティを返すかを指定するSpecify which properties of objects you want to return

SharePoint サーバー オブジェクト モデルでは、 SPWeb オブジェクトを取得する場合は、そのプロパティをすべて検査できます。SQL では、テーブルのすべてのカラムを取得する場合は、次のコードを実行できます。In the SharePoint server object model, if you get an SPWeb object, you can inspect all of its properties. In SQL, to get all of the columns of a table you can run:

SELECT * FROM Webs 

クライアント ライブラリでは、 Load も他のメソッドも、すべてのプロパティを返すことはないため、目的のプロパティを明示的に指定する必要があります。たとえば、次のコードでは、目的のプロパティの指定なしで、Web サイトのオブジェクトを取得しています。その後、2 つのプロパティを読み込もうとしていますが、そのうちの 1 つは Load によって自動的に返されるプロパティには含まれていません。このコードは例外をスローします。In the client library, neither Load nor any other method returns all properties, so you have to explicitly specify what you want. For example, the following code retrieves the website object without specifying which properties to return. It then tries to read two properties and one of them is not among the properties that is automatically returned by Load. This code throws an exception.

// Starting with ClientContext, the constructor requires a URL to the 
// server running SharePoint. 
ClientContext context = new ClientContext("http://SiteUrl"); 

Web web = context.Web; 
context.Load(web); 
context.ExecuteQuery(); 

Console.WriteLine(web.Title); 
Console.WriteLine(web.HasUniqueRoleAssignments);  


このコードのコンパイルを成功させるには、コードを次のように更新します。To get the code to compile successfully, update it to the following. このコードをコンパイルするには、System.Linq 用の using ステートメントを追加する必要があります。To compile this code, you need to add a using statement for System.Linq. さらに、Microsoft.SharePoint.Client 名前空間用の using ステートメントに対するエイリアスを追加して、そのクラスを明確に参照できるようにします。Also, add an alias to the using statement for the Microsoft.SharePoint.Client namespace so you can refer to its classes unambiguously. 例: using SP = Microsoft.SharePoint.Client;For example, using SP = Microsoft.SharePoint.Client;.

// Starting with ClientContext, the constructor requires a URL to the 
// server running SharePoint. 
ClientContext context = new ClientContext("http://SiteUrl"); 

Web web = context.Web; 
context.Load(web); 
context.Load(web, web => web.HasUniqueRoleAssignments); 
context.ExecuteQuery(); 

Console.WriteLine(web.Title); 
Console.WriteLine(web.HasUniqueRoleAssignments);  


データを読み込む前に条件範囲を使用して前提条件をテストするUse conditional scope to test for preconditions before loading data

コードを条件付きで実行するには、ConditionalScope オブジェクトを使用して、条件範囲を設定します。To conditionally execute code, set a conditional scope by using a ConditionalScope object. たとえば、リストが null 以外の場合にリストのプロパティを取得します。For example, retrieve the list property when the list is not null. System.Collections.Generic および System.Linq 用の using ステートメントも追加する必要があります。You also need to add using statements for System.Collections.Generic and System.Linq. さらに、Microsoft.SharePoint.Client 名前空間用の using ステートメントに対するエイリアスを追加して、そのクラスを明確に参照できるようにします。Also, add an alias to the using statement for the Microsoft.SharePoint.Client namespace so you can refer to its classes unambiguously. たとえば、using SP = Microsoft.SharePoint.Client; などです。For example, using SP = Microsoft.SharePoint.Client;.

注意

条件範囲内でメソッドの呼び出しとプロパティの設定を行うことは許可されていません。これは、クライアント ライブラリでは、メソッドの呼び出しとプロパティの設定の副次的影響を追跡しないためです。条件範囲の中では、Load のみを使用する必要があります。Calling method and setting properties within a conditional scope are not permitted, because the client library does not track the side effects of method calls and property settings. You should use only Load inside the conditional scope.

// Starting with ClientContext, the constructor requires a URL to the 
// server running SharePoint. 
ClientContext context = new ClientContext("http://SiteUrl"); 

SP.List list = context.Web.GetCatalog(ListTemplateType.WebPartCatalog); 
BasePermissions perm = new BasePermissions(); 
perm.Set(PermissionKind.ManageLists); 

ConditionalScope scope = 
    new ConditionalScope(context, 
                         () => list.ServerObjectIsNull &amp;&amp; context.Web.DoesUserHavePermissions(perm).Value); 
using (scope.StartScope()) 
{ 
    context.Load(list, l => l.Title); 
} 
context.ExecuteQuery(); 

label1.Text = scope.TestResult.Value; 

if (scope.TestResult.Value) 
{ 
    label1.Text = list.Title; 
}  


例外処理範囲を使用して例外をキャッチするUse an exception handling scope to catch exceptions

次の例は、ExceptionHandlingScope オブジェクトを使用して例外処理範囲を作成および使用する方法を示しています。This example shows how to create and use an exception handling scope with an ExceptionHandlingScope object. このシナリオは、リストの説明を更新し、フォルダーも作成できるようにするものです。The scenario is to update the description of a list and also enable folder creation. リストは存在しない可能性もあります。There is a possibility that the list might not exist.

// Starting with ClientContext, the constructor requires a URL to the 
// server running SharePoint. 
ClientContext context = new ClientContext("http://SiteUrl"); 

ExceptionHandlingScope scope = new ExceptionHandlingScope(context); 

using (scope.StartScope()) 
{ 
    using (scope.StartTry()) 
    { 
        List fooList = context.Web.Lists.GetByTitle("Sample"); 
        fooList.Description = "In Try Block"; 
        fooList.Update(); 
    } 
    using (scope.StartCatch()) 
    { 
        // Assume that if there's an exception, 
        // it can be only because there was no "Sample" list. 
        ListCreationInformation listCreateInfo = new ListCreationInformation(); 
        listCreateInfo.Title = "Sample"; 
        listCreateInfo.Description = "In Catch Block"; 
        listCreateInfo.TemplateType = (int)ListTemplateType.Announcements; 
        List fooList = context.Web.Lists.Add(listCreateInfo); 
    } 
    using (scope.StartFinally()) 
    { 
        List fooList = context.Web.Lists.GetByTitle("Sample"); 
        fooList.EnableFolderCreation = true; 
        fooList.Update(); 
    } 
} 

context.ExecuteQuery();  


関連項目See also