Realizar operaciones básicas con código de biblioteca de cliente de SharePoint

Artículo
04/08/2023

Puede usar el modelo de objetos de cliente (CSOM) de SharePoint para recuperar, actualizar y administrar datos en SharePoint. SharePoint ofrece el CSOM de varias formas:

Ensamblados redistribuibles de .NET Framework
Biblioteca de JavaScript (JSOM)
Extremos REST/OData
Ensamblados de Windows Phone (en desuso)
Ensamblados redistribuibles de Silverlight (en desuso)

Para obtener información sobre los conjuntos de API disponibles en la plataforma de SharePoint, vea Elegir el conjunto de API correcto en SharePoint 2013).

Este artículo muestra cómo realizar operaciones básicas con el modelo de objetos de .NET Framework, que está disponible como un paquete redistribuible en la galería de NuGet.

Para obtener información sobre cómo usar las demás API de cliente, vea lo siguiente:

Operaciones básicas con el modelo de objetos de cliente .NET de SharePoint

En las secciones siguientes se describen las tareas que puede completar mediante programación y se incluyen ejemplos de código C# que muestran operaciones CSOM.

Al crear un proyecto de complemento de SharePoint en Visual Studio 2012, se agregan automáticamente al proyecto referencias a los ensamblados de .NET Framework, Microsoft.SharePoint.Client.Runtime.dll y Microsoft.SharePoint.Client.dll. En otros tipos de proyectos, como aplicaciones de .NET Framework o aplicaciones de consola, debería agregar estas referencias. Los archivos se encuentran en cualquier servidor de SharePoint en %ProgramFiles%\Common Files\Microsoft Shared\web server extensions\15\ISAPI.

En todos estos ejemplos se presupone que el código se encuentra en un archivo de código subyacente de una página web de Microsoft ASP.NET. Se debe agregar la siguiente instrucción using al archivo de código.

using Microsoft.SharePoint.Client;

Salvo que se especifique lo contrario, puede suponer que cada uno de estos ejemplos se incluye en un método sin parámetros que se define en la clase de la página. Además, label1, label2, etc., son los nombres de los objetos Label de la página.

Nota:

Si crea un complemento de SharePoint hospedado por el proveedor con una aplicación web ASP.NET y agrega una referencia a un ensamblado en el proyecto de aplicación web de Visual Studio, establezca la propiedad Copia local del ensamblado en True, a menos que sepa que el ensamblado está ya instalado en el servidor web o que pueda asegurar que está instalado antes de implementar el complemento.

.NET Framework se instala en roles web de Microsoft Azure y sitios web de Azure. Pero los ensamblados de cliente de SharePoint y las diversas fundaciones y extensiones de código administradas de Microsoft no se instalan. Office Developer Tools para Visual Studio 2012 agrega automáticamente referencias a algunos ensamblados que se usan habitualmente en complementos de SharePoint y establece la propiedad Copia Local.

Tareas de sitio web de SharePoint

En estos ejemplos se muestra cómo usar CSOM de .NET Framework para completar las tareas relacionadas con el sitio web.

Recuperar las propiedades de un sitio web

Recuperar el título de un sitio web de SharePoint

// Starting with ClientContext, the constructor requires a URL to the
// server running SharePoint.
ClientContext context = new ClientContext("https://{site_url}");

// 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;

Recuperar solo las propiedades seleccionadas de un sitio web

A veces, el cliente solo está interesado en algunas propiedades de un objeto. El CSOM de .NET Framework de SharePoint no requiere que se obtengan todas las propiedades del objeto en un servidor. Se pueden usar métodos anónimos, que pueden ser expresiones lambda, para solicitar específicamente los nombres de las propiedades. La biblioteca de cliente solo consulta esas propiedades en el servidor y este solo envía esas propiedades al cliente. Esta técnica reduce las transferencias de datos innecesarias entre el cliente y el servidor. También resulta útil cuando el usuario no tiene permiso para una o varias de las demás propiedades de un objeto que no se usan.

También tiene que agregar una instrucción using de System.Linq.

// Starting with ClientContext, the constructor requires a URL to the
// server running SharePoint.
ClientContext context = new ClientContext("https://{site_url}");

// 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 aren't available.
label1.Text = web.Title;
label1.Text = web.Description;

Nota:

Si trata de obtener acceso a otras propiedades, el código produce una excepción porque las otras propiedades no están disponibles.

Escribir en las propiedades de un sitio web

En este ejemplo se muestra cómo escribir en las propiedades de un sitio web.

// Starting with ClientContext, the constructor requires a URL to the
// server running SharePoint.
ClientContext context = new ClientContext("https://{site_url}");

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

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

// Note that the web.Update() doesn't trigger a request to the server.
// Requests are only sent to the server from the client library when
// the ExecuteQuery() method is called.
web.Update();

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

Crear un sitio web de SharePoint

En este ejemplo se muestra cómo crear un sitio de SharePoint como subsitio del sitio web actual. Use la clase WebCreationInformation para crear un nuevo sitio web. También tiene que agregar instrucciones using para System.Collections.Generic y System.Text.

// Starting with ClientContext, the constructor requires a URL to the
// server running SharePoint.
ClientContext context = new ClientContext("https://{site_url}");

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;

Tareas de lista de SharePoint

En estos ejemplos se muestra cómo usar el CSOM de .NET Framework para completar las tareas relacionadas con listas.

Recuperar todas las listas de SharePoint en una web

En este ejemplo se recuperan todas las listas de SharePoint de un sitio web de SharePoint. Para compilar el código, tiene que agregar una instrucción using para System.Linq.

// Starting with ClientContext, the constructor requires a URL to the
// server running SharePoint.
ClientContext context = new ClientContext("https://{site_url}");

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

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

// Execute query.
context.ExecuteQuery();

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

Nota:

También puede usar el método LoadQuery para almacenar el valor devuelto en otra colección, en lugar de usar la propiedad web.Lists. También tendrá que agregar instrucciones using para System.Collections.Generic y System.Linq. Además, agregue un alias a la instrucción "using" en el espacio de nombres Microsoft.SharePoint.Client para poder hacer referencia a sus clases de forma inequívoca. Por ejemplo, using SP = Microsoft.SharePoint.Client;.

// Starting with ClientContext, the constructor requires a URL to the
// server running SharePoint.
ClientContext context = new ClientContext("https://{site_url}");

// 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;
}

Crear y actualizar una lista de SharePoint

En este ejemplo se crea una lista de SharePoint y se actualiza con la clase ListCreationInformation.

// Starting with ClientContext, the constructor requires a URL to the
// server running SharePoint.
ClientContext context = new ClientContext("https://{site_url}");

// 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();

Eliminar una lista de SharePoint

En este ejemplo se elimina una lista de SharePoint.

// Starting with ClientContext, the constructor requires a URL to the
// server running SharePoint.
ClientContext context = new ClientContext("https://{site_url}");

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

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

context.ExecuteQuery();

Agregar un campo a una lista de SharePoint

En este ejemplo se agrega un campo a una lista de SharePoint. Agregue un alias a la instrucción "using" en el espacio de nombres Microsoft.SharePoint.Client para poder hacer referencia a sus clases de forma inequívoca. Por ejemplo, using SP = Microsoft.SharePoint.Client;.

Nota:

En el ejemplo se usa context.CastTo para realizar una conversión. Antes de ejecutar la consulta, la biblioteca de cliente no conoce el tipo real del objeto devuelto "field" y SharePoint.Field es el único tipo posible. Si conoce el tipo real, puede usar el método ClientContext.CastTo<RealType> para convertir el objeto.

// Starting with ClientContext, the constructor requires a URL to the
// server running SharePoint.
ClientContext context = new ClientContext("https://{site_url}");

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();

Tareas de elemento de lista de SharePoint

En estos ejemplos se muestra cómo usar el CSOM de .NET Framework para completar tareas relacionadas con elementos de lista.

Recuperar elementos de una lista de SharePoint

En este ejemplo se recuperan los elementos de una lista de SharePoint. También tiene que agregar una instrucción using para Microsoft.SharePoint.Client.QueryExpression.

Nota:

Puede usar la propiedad FolderServerRelativeUrl para restringir aún más los elementos que se devuelven a los que se encuentran en una carpeta determinada.

// Starting with ClientContext, the constructor requires a URL to the
// server running SharePoint.
ClientContext context = new ClientContext("https://{site_url}");

// 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"];
}

Crear un elemento de lista

En este ejemplo se crea un elemento de lista de SharePoint con ListItemCreationInformation.

// Starting with ClientContext, the constructor requires a URL to the
// server running SharePoint.
ClientContext context = new ClientContext("https://{site_url}");

// 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();

Actualizar un elemento de lista

En este ejemplo se actualiza un elemento de lista de SharePoint.

// Starting with ClientContext, the constructor requires a URL to the
// server running SharePoint.
ClientContext context = new ClientContext("https://{site_url}");

// 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();

Eliminar un elemento de lista

En este ejemplo se elimina un elemento de lista de SharePoint.

// Starting with ClientContext, the constructor requires a URL to the
// server running SharePoint.
ClientContext context = new ClientContext("https://{site_url}");

// 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(); }

Tareas de campo de SharePoint

En estos ejemplos se muestra cómo usar el CSOM de .NET Framework de SharePoint para completar las tareas relacionadas con campos.

Recuperar todos los campos de una lista

En este ejemplo se recuperan todos los campos de una lista de SharePoint. También tiene que agregar un alias a la instrucción using para el espacio de nombres Microsoft.SharePoint.Client para poder hacer referencia a sus clases de forma inequívoca; por ejemplo, using SP = Microsoft.SharePoint.Client;.

// Starting with ClientContext, the constructor requires a URL to the
// server running SharePoint.
ClientContext context = new ClientContext("https://{site_url}");

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;
}

Recuperar un campo específico de la lista

Si quiere recuperar información sobre un campo específico, use el método Fields.GetByInternalNameOrTitle. El tipo de valor devuelto de este método es Field. Antes de ejecutar la consulta, el cliente no conoce el tipo de objeto y la sintaxis de C# no está disponible para convertirlo en el tipo derivado. Por lo tanto, use el método ClientContext.CastTo para convertirlo. Esto indica a la biblioteca de cliente que vuelva a crear un objeto. También tiene que agregar una instrucción using para System.Collections.Generic. También tiene que agregar un alias a la instrucción using en el espacio de nombres Microsoft.SharePoint.Client para poder hacer referencia a sus clases de forma inequívoca. Por ejemplo, using SP = Microsoft.SharePoint.Client;.

Nota:

El método GetByInternalNameOrTitle usado en este ejemplo es un método remoto. No utiliza los datos de la colección del cliente aunque esta última ya esté llena.

// Starting with ClientContext, the constructor requires a URL to the
// server running SharePoint.
ClientContext context = new ClientContext("https://{site_url}");

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;

Tareas de usuario de SharePoint

Puede usar el CSOM de .NET Framework de SharePoint para administrar usuarios, grupos y seguridad de usuarios de SharePoint.

Agregar un usuario a un grupo de SharePoint

En este ejemplo se agrega un usuario y cierta información de usuario a un grupo de SharePoint denominado Miembros.

// Starting with ClientContext, the constructor requires a URL to the
// server running SharePoint.
ClientContext context = new ClientContext("https://{site_url}");

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();

Recuperar todos los usuarios de un grupo de SharePoint

En este ejemplo se recupera información de todos los usuarios de un grupo de SharePoint denominado Miembros.

// Starting with ClientContext, the constructor requires a URL to the
// server running SharePoint.
ClientContext context = new ClientContext("https://{site_url}");

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;
}

Crear un rol

En este ejemplo se crea un rol que tiene que crear y administrar permisos de alertas.

// Starting with ClientContext, the constructor requires a URL to the
// server running SharePoint.
ClientContext context = new ClientContext("https://{site_url}");

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();

Agregar un usuario a un rol

En este ejemplo se agrega un usuario a un rol.

// Starting with ClientContext, the constructor requires a URL to the
// server running SharePoint.
ClientContext context = new ClientContext("https://{site_url}");

// 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();

Reglas y procedimientos recomendados para el modelo de objetos de cliente de .NET de SharePoint

Estos ejemplos ilustran algunos requisitos y procedimientos recomendados importantes que debe cumplir al usar el CSOM de .NET Framework de SharePoint.

Llamar a ClientContext.ExecuteQuery antes de obtener acceso a las propiedades del valor

El CSOM de .NET Framework de SharePoint requiere el uso de un modelo de programación similar a SQL: declarar lo que se necesita y ejecutar la consulta para tener acceso a los datos. Por ejemplo, en el siguiente código, que intenta mostrar el título del sitio web de SharePoint, se genera una excepción.

// Starting with ClientContext, the constructor requires a URL to the
// server running SharePoint.
ClientContext context = new ClientContext("https://{site_url}");

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

Este código produce errores porque el código CSOM de .NET Framework de SharePoint debe:

crear un procedimiento almacenado o una consulta SQL ad hoc
ejecutar la consulta SQL
leer los resultados de SQL

En el CSOM de .NET Framework de SharePoint, al llamar a un método, se genera una consulta. Las consultas se acumulan y no se envían al servidor hasta ExecuteQuery que se llama a .

En el siguiente ejemplo se muestra el código necesario para mostrar el título del sitio web. También tiene que agregar una instrucción using de System.Linq. Además, agregue un alias a la instrucción using para el espacio de nombres Microsoft.SharePoint.Client para que pueda hacer referencia a sus clases de forma inequívoca. Por ejemplo, using SP = Microsoft.SharePoint.Client;.

// Starting with ClientContext, the constructor requires a URL to the
// server running SharePoint.
ClientContext context = new ClientContext("https://{site_url}");

Web web = context.Web;

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

context.ExecuteQuery();

label1.Text = web.Title;

Las diferencias son la adición de estas líneas; la primera línea crea una consulta para la propiedad Title de la web. La segunda línea ejecuta la consulta.

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

No use objetos de valor devueltos por métodos o propiedades en la misma consulta

Cuando se devuelve un objeto de valor de un método o propiedad, no se puede usar ese objeto hasta después de ejecutar la consulta. Por ejemplo, el siguiente código intenta crear una lista de SharePoint que tenga el mismo título que el sitio web principal, pero se genera una excepción.

// Starting with ClientContext, the constructor requires a URL to the
// server running SharePoint.
ClientContext context = new ClientContext("https://{site_url}");

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);

Se produce una excepción porque la propiedad no está disponible antes de ejecutar la consulta. En SQL, se declararía una variable local que contenga el valor web.Title y se usaría la variable local para la creación de la web. En la biblioteca de cliente no se puede crear una variable local. Debe dividir la funcionalidad en dos consultas distintas tal y como se muestra en el ejemplo siguiente. También tiene que agregar una instrucción using de System.Linq. Además, agregue un alias a la instrucción "using" en el espacio de nombres Microsoft.SharePoint.Client para poder hacer referencia a sus clases de forma inequívoca. Por ejemplo, using SP = Microsoft.SharePoint.Client;.

// Starting with ClientContext, the constructor requires a URL to the
// server running SharePoint.
ClientContext context = new ClientContext("https://{site_url}");

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();

La diferencia está en las tres líneas siguientes:

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

Usar métodos o propiedades que devuelven objetos de cliente en la llamada a otro método en la misma consulta

A diferencia de un objeto de valor, un objeto de cliente se puede usar en otra llamada de método en la misma consulta.

En.NET en remoto, el objeto de valor es una clase o estructura cuyas referencias se calculan por valor, mientras que un objeto de cliente es una clase o estructura cuyas referencias se calculan por referencia. Por ejemplo, ListItem es un objeto de cliente, mientras que UrlFieldValue y otros valores de campo son objetos de valor.

En la biblioteca de cliente, el objeto de servidor correspondiente tiene el atributo [ClientCallable(ValueObject = true)]. Estos valores solo podrían tener propiedades y no métodos. Los tipos primitivos, como cadenas y enteros, se tratan como objetos de valor. Todos los valores se serializan entre el cliente y el servidor. El valor predeterminado de ValueObject es false.

El equivalente al objeto de valor es el objeto de cliente. Si el objeto de servidor correspondiente tiene el atributo [ClientCallable(ValueObject = false)], el objeto es un objeto de cliente. En objetos de cliente, se hace un seguimiento de cómo se crea el objeto; esto se denomina ObjectPath en la implementación de la biblioteca de cliente. Por ejemplo, si se tiene código como el siguiente:

ClientContext context = new ClientContext("https://{site_url}");
Web web = context.Web;
SP.List list = web.Lists.GetByTitle("Announcements");

Sabemos que la lista se crea al:

obtener la propiedad Web del contexto actual
obtener la propiedad Lists del resultado anterior
invocar el método GetByTitle con el parámetro Announcements del resultado anterior

Cuando el CSOM de .NET Framework de SharePoint pasa esta información al servidor, se puede volver a crear el objeto en el servidor. En la biblioteca de cliente, puede realizar un seguimiento de la propiedad ObjectPath que creó el objeto de cliente. Dado que sabe cómo se crea el objeto, podría usar el objeto como parámetro para llamar a otros métodos en la misma consulta.

Agrupar la recuperación de datos en el mismo objeto para mejorar el rendimiento

Al leer varios fragmentos de datos del mismo objeto, debe intentar obtener todos ellos en una sola consulta; es decir, una sola llamada al Load<T>(T, []) método . El código siguiente muestra dos formas de recuperar el título y la descripción de un sitio web y la descripción de la lista Announcements. Para compilar el código, tiene que agregar una instrucción using para System.Linq. Además, agregue un alias a la instrucción using para el espacio de nombres Microsoft.SharePoint.Client para que pueda hacer referencia a sus clases de forma inequívoca. Por ejemplo, using SP = Microsoft.SharePoint.Client;.

static void Method1()
{
  ClientContext context = new ClientContext("https://{site_url}");
  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("https://{site_url}");
  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();
}

No son igualmente eficaces. En Method1, el código para recuperar el título y la descripción de la web está agrupado. En Method2, el código para recuperar el título y la descripción de la web está separado por otras acciones. Esto significa que Method2 desencadena dos consultas distintas en el mismo objeto web y hay dos conjuntos de resultados para la misma web. Dado que la biblioteca de cliente intenta devolver datos coherentes, el segundo conjunto de resultados incluye el título y la descripción. El código anterior sería como el siguiente.

// 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 …

Especificar las propiedades de los objetos que quiere devolver

En el modelo de objetos de servidor de SharePoint, si obtiene un objeto SPWeb, puede inspeccionar todas sus propiedades. En SQL, para obtener todas las columnas de una tabla puede ejecutar:

SELECT * FROM Webs

En la biblioteca de cliente, ni Load<T> ni cualquier otro método devuelve todas las propiedades, por lo que tiene que especificar explícitamente lo que quiere. Por ejemplo, el código siguiente recupera el objeto de sitio web sin especificar las propiedades que se devolverán. Luego trata de leer dos propiedades y una de ellas no está entre las propiedades que Load devuelve automáticamente. Este código genera una excepción.

// Starting with ClientContext, the constructor requires a URL to the
// server running SharePoint.
ClientContext context = new ClientContext("https://{site_url}");

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

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

Para que el código se compile correctamente, actualícelo a la siguiente versión. Para compilar el código, tiene que agregar una instrucción using para System.Linq. Además, agregue un alias a la instrucción using para el espacio de nombres Microsoft.SharePoint.Client para que pueda hacer referencia a sus clases de forma inequívoca. Por ejemplo, using SP = Microsoft.SharePoint.Client;.

// Starting with ClientContext, the constructor requires a URL to the
// server running SharePoint.
ClientContext context = new ClientContext("https://{site_url}");

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

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

Usar ámbito condicional para probar condiciones previas antes de cargar datos

Para ejecutar el código de forma condicional, establezca un ámbito condicional mediante un objeto ConditionalScope. Por ejemplo, recupere la propiedad de lista cuando la lista no sea nula. También tiene que agregar instrucciones using para System.Collections.Generic y System.Linq. Además, agregue un alias a la instrucción using para el espacio de nombres Microsoft.SharePoint.Client para que pueda hacer referencia a sus clases de forma inequívoca. Por ejemplo, using SP = Microsoft.SharePoint.Client;.

Nota:

No se permite llamar al método y establecer las propiedades dentro de un ámbito condicional, porque la biblioteca de cliente no realiza el seguimiento de los efectos secundarios de las llamadas a métodos y valores de la propiedad. Dentro del ámbito condicional solo debería usar Load.

// Starting with ClientContext, the constructor requires a URL to the
// server running SharePoint.
ClientContext context = new ClientContext("https://{site_url}");

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;
}

Usar un ámbito de control de excepciones para capturar excepciones

En este ejemplo se muestra cómo crear y usar un ámbito de control de excepciones con un objeto ExceptionHandlingScope. La finalidad del escenario es actualizar la descripción de una lista, así como habilitar la creación de carpetas. Es posible que la lista no exista.

// Starting with ClientContext, the constructor requires a URL to the
// server running SharePoint.
ClientContext context = new ClientContext("https://{site_url}");

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();

Realizar operaciones básicas con código de biblioteca de cliente de SharePoint

Operaciones básicas con el modelo de objetos de cliente .NET de SharePoint

Tareas de sitio web de SharePoint

Recuperar las propiedades de un sitio web

Recuperar solo las propiedades seleccionadas de un sitio web

Escribir en las propiedades de un sitio web

Crear un sitio web de SharePoint

Tareas de lista de SharePoint

Recuperar todas las listas de SharePoint en una web

Crear y actualizar una lista de SharePoint

Eliminar una lista de SharePoint

Agregar un campo a una lista de SharePoint

Tareas de elemento de lista de SharePoint

Recuperar elementos de una lista de SharePoint

Crear un elemento de lista

Actualizar un elemento de lista

Eliminar un elemento de lista

Tareas de campo de SharePoint

Recuperar todos los campos de una lista

Recuperar un campo específico de la lista

Tareas de usuario de SharePoint

Agregar un usuario a un grupo de SharePoint

Recuperar todos los usuarios de un grupo de SharePoint

Crear un rol

Agregar un usuario a un rol

Reglas y procedimientos recomendados para el modelo de objetos de cliente de .NET de SharePoint

Llamar a ClientContext.ExecuteQuery antes de obtener acceso a las propiedades del valor

No use objetos de valor devueltos por métodos o propiedades en la misma consulta

Usar métodos o propiedades que devuelven objetos de cliente en la llamada a otro método en la misma consulta

Agrupar la recuperación de datos en el mismo objeto para mejorar el rendimiento

Especificar las propiedades de los objetos que quiere devolver

Usar ámbito condicional para probar condiciones previas antes de cargar datos

Usar un ámbito de control de excepciones para capturar excepciones

Consulte también

Recursos adicionales