Introducción a la creación de complementos de SharePoint hospedados por el proveedorGet started creating provider-hosted SharePoint Add-ins

Los complementos hospedados por el proveedor son uno de los dos tipos principales de complementos de SharePoint. Para obtener información general sobre los complementos de SharePoint y los dos tipos distintos, vea Complementos de SharePoint.Provider-hosted add-ins are one of the two major types of SharePoint Add-ins. For an overview of SharePoint Add-ins and the two different types, see SharePoint Add-ins.

Aquí tiene un resumen de complementos hospedados por el proveedor:Here's a summary of provider-hosted add-ins:

  • Ofrecen una aplicación web, un servicio o una base de datos que non están hospedados en la granja de servidores de SharePoint ni en la suscripción a SharePoint Online.They include a web application, service, or database that is hosted externally from the SharePoint farm or SharePoint Online subscription. También pueden incluir los componentes de SharePoint.They may also include SharePoint components. Los componentes externos pueden hospedarse en cualquier pila de hospedaje web, incluidas las pilas LAMP (Linux, Apache, MySQL y PHP).You can host the external components on any web-hosting stack, including the LAMP (Linux, Apache, MySQL, and PHP) stack.
  • La lógica empresarial personalizada en el complemento tiene que ejecutarse en componentes externos, o en bien con JavaScript en páginas de SharePoint personalizadas.The custom business logic in the add-in has to run on either the external components or in JavaScript on custom SharePoint pages.

En este artículo, completará los pasos siguientes:In this article, you'll complete the following steps:

  • Configurar el entorno de desarrolloSet up your dev environment
  • Crear el proyecto de complementoCreate the add-in project
  • Código del complementoCode your add-in

Configurar el entorno de desarrolloSet up your dev environment

Hay muchas maneras de configurar un entorno de desarrollo para Complementos de SharePoint. En esta sección se explica la forma más sencilla.There are many ways to set up a development environment for SharePoint Add-ins. This section explains the simplest way. Si busca otras alternativas, como la configuración de un entorno “completamente local”, vea Herramientas.For alternatives, such as setting up an "all on-premises" environment, see Tools.

Obtener las herramientasGet the tools

Consulte las versiones anteriores de Visual Studio u otra documentación de Visual Studio.Reference earlier versions of Visual Studio or other Visual Studio documentation.

Registrarse para obtener una suscripción de Office 365 DeveloperSign up for an Office 365 developer subscription

Nota

Podría tener ya acceso a una suscripción de Office 365 Developer:You might already have access to an Office 365 developer subscription:

Para obtener un plan de Office 365:To get an Office 365 plan:

Abrir el sitio para desarrolladoresOpen your developer site

Seleccione el vínculo Compilar complementos en la esquina superior izquierda de la página para abrir el sitio para desarrolladores.Select the Build Add-ins link in the upper-left corner of the page to open your developer site. Debería ver un sitio que se parece al de la figura siguiente.You should see a site that looks like the one in the following figure. La lista Add-ins in Testing (Complementos de pruebas) en la página confirma que el sitio web se ha realizado con la plantilla del sitio de SharePoint Developer.The Add-ins in Testing list on the page confirms that the website was made with the SharePoint Developer Site template. Si ve un sitio de grupo normal en su lugar, espere unos minutos y, después, reinicie el sitio.If you see a regular team site instead, wait a few minutes and then restart your site.

Nota

Anote la dirección URL del sitio (se usa al crear proyectos de complementos de SharePoint en Visual Studio).Make a note of the site's URL; it's used when you create SharePoint Add-in projects in Visual Studio.

Página principal del sitio para desarrolladores con la lista Complementos en fase de pruebaYour developer site home page with the Add-ins in Testing list

Captura de pantalla donde se muestra la página principal del sitio para desarrolladores.

Crear el proyecto de complementoCreate the add-in project

  1. Inicie Visual Studio con la opción Ejecutar como administrador.Start Visual Studio by using the Run as administrator option.

  2. En Visual Studio, seleccione Archivo > Nuevo > Proyecto.In Visual Studio, select File > New > New Project.

  3. En el cuadro de diálogo Nuevo proyecto, expanda el nodo Visual C#, expanda el nodo Office/SharePoint y, después, seleccione Complementos > Complemento de SharePoint.In the New Project dialog box, expand the Visual C# node, expand the Office/SharePoint node, and then select Add-ins > SharePoint Add-in.

  4. Asigne el nombre SampleAddIn al proyecto y, después, seleccione Aceptar.Name the project SampleAddIn, and then select OK.

  5. En el cuadro de diálogo Especificar configuración para el complemento de SharePoint, siga este procedimiento:In the Specify the SharePoint Add-in Settings dialog box, do the following:

    • Especifique la dirección URL completa del sitio de SharePoint que quiera usar para la depuración de su complemento.Provide the full URL of the SharePoint site that you want to use to debug your add-in. Esta es la dirección URL del sitio para desarrolladores.This is the URL of the developer site. Use HTTPS en lugar de HTTP en la dirección URL.Use HTTPS, not HTTP in the URL. En algún momento durante este procedimiento o poco después de que finalice, se le pedirá que inicie sesión en este sitio.At some point during this procedure, or shortly after it completes, you will be prompted to sign in to this site. Los intervalos para pedir confirmación varían.The timing of the prompt varies. Use las credenciales de administrador (en el dominio *.onmicrosoft.com) que haya creado al registrarse en su sitio para desarrolladores, por ejemplo, MiNombre@contoso.onmicrosoft.com.Use the administrator credentials (in the *.onmicrosoft.com domain) that you created when you signed up for your developer site; for example MyName@contoso.onmicrosoft.com.

    • En ¿Cómo desea hospedar el complemento de SharePoint?, seleccione Hospedado por el proveedor.Under How do you want to host your SharePoint Add-in, select Provider-hosted.

    • Seleccione Siguiente.Select Next.

  6. En la página Especifique la versión de destino de SharePoint, seleccione SharePoint Online y, después, seleccione Siguiente.On the Specify the target SharePoint version page, select SharePoint Online, and then select Next.

  7. En ¿Qué tipo de proyecto de aplicación web desea crear?, seleccione Aplicación de formularios Web Forms ASP.NET y, a continuación, seleccione Siguiente.Under Which type of web application project do you want to create?, select ASP.NET Web Forms Application, and then select Next.

  8. En ¿Cómo desea que se autentique su complemento?, seleccione Usar Microsoft Azure Access Control Service.Under How do you want your add-in to authenticate?, select Use Windows Azure Access Control Service.

  9. En el asistente, seleccione Finalizar.In the wizard, select Finish.

    Gran parte de la configuración se realiza cuando se abre la solución.Much of the configuration is done when the solution opens. Se crean dos proyectos en la solución Visual Studio, uno para la Complemento de SharePoint y el otro para la aplicación web de ASP.NET.Two projects are created in the Visual Studio solution: one for the SharePoint Add-in and the other for the ASP.NET web application.

Código del complementoCode your add-in

  1. Abra el archivo AppManifest.xml. En la pestaña Permisos, especifique el ámbito Colección de sitios y el nivel de permiso Leer.Open the AppManifest.xml file. On the Permissions tab, specify the Site Collection scope and the Read permission level.

  2. Elimine cualquier marca dentro de la etiqueta <body> del archivo Pages/Default.aspx de su aplicación web y, a continuación, agregue el HTML siguiente y los controles de ASP.NET dentro de <body>.Delete any markup inside the <body> tag of the Pages/Default.aspx file of your web application, and then add the following HTML and ASP.NET controls inside the <body>. En este ejemplo se usa el control UpdatePanel para habilitar la representación parcial de la página.This sample uses the UpdatePanel control to enable partial page rendering.

     <form id="form1" runat="server">
       <div>
         <asp:ScriptManager ID="ScriptManager1" runat="server"
                 EnablePartialRendering="true" />
         <asp:UpdatePanel ID="PopulateData" runat="server" UpdateMode="Conditional">
           <ContentTemplate>      
             <table border="1" cellpadding="10">
              <tr><th><asp:LinkButton ID="CSOM" runat="server" Text="Populate Data" 
                                    OnClick="CSOM_Click" /></th></tr>
              <tr><td>
    
             <h2>SharePoint Site</h2>
             <asp:Label runat="server" ID="WebTitleLabel"/>
    
             <h2>Current User:</h2>
             <asp:Label runat="server" ID="CurrentUserLabel" />
    
             <h2>Site Users</h2>
             <asp:ListView ID="UserList" runat="server">     
                 <ItemTemplate >
                   <asp:Label ID="UserItem" runat="server" 
                                     Text="<%# Container.DataItem.ToString()  %>">
                   </asp:Label><br />
                </ItemTemplate>
             </asp:ListView>
    
             <h2>Site Lists</h2>
                    <asp:ListView ID="ListList" runat="server">
                        <ItemTemplate >
                          <asp:Label ID="ListItem" runat="server" 
                                     Text="<%# Container.DataItem.ToString()  %>">
                         </asp:Label><br />
                       </ItemTemplate>
                   </asp:ListView>
                 </td>              
               </tr>
              </table>
            </ContentTemplate>
          </asp:UpdatePanel>
       </div>
     </form>
    
  3. Agregue las siguientes declaraciones al archivo Default.aspx.cs de la aplicación web.Add the following declarations to the Default.aspx.cs file of your web application.

       using Microsoft.SharePoint.Client;
       using Microsoft.IdentityModel.S2S.Tokens;
       using System.Net;
       using System.IO;
       using System.Xml;
    
  4. En el archivo Default.aspx.cs de la aplicación web, agregue estas variables dentro de la clase Page.In the Default.aspx.cs file of your web application, add these variables inside the Page class.

      SharePointContextToken contextToken;
      string accessToken;
      Uri sharepointUrl;
      string siteName;
      string currentUser;
      List<string> listOfUsers = new List<string>();
      List<string> listOfLists = new List<string>();
    
  5. Agregue el método RetrieveWithCSOM dentro de la clase Página.Add the RetrieveWithCSOM method inside the Page class. Este método usa el CSOM de SharePoint para recuperar información sobre su sitio y mostrarlo en la página.This method uses the SharePoint CSOM to retrieve information about your site and display it on the page.

        // This method retrieves information about the host web by using the CSOM.
      private void RetrieveWithCSOM(string accessToken)
      {
    
          if (IsPostBack)
          {
              sharepointUrl = new Uri(Request.QueryString["SPHostUrl"]);
          }            
    
          ClientContext clientContext =
                          TokenHelper.GetClientContextWithAccessToken(
                              sharepointUrl.ToString(), accessToken);
    
          // Load the properties for the web object.
          Web web = clientContext.Web;
          clientContext.Load(web);
          clientContext.ExecuteQuery();
    
          // Get the site name.
          siteName = web.Title;
    
          // Get the current user.
          clientContext.Load(web.CurrentUser);
          clientContext.ExecuteQuery();
          currentUser = clientContext.Web.CurrentUser.LoginName;
    
          // Load the lists from the Web object.
          ListCollection lists = web.Lists;
          clientContext.Load<ListCollection>(lists);
          clientContext.ExecuteQuery();
    
          // Load the current users from the Web object.
          UserCollection users = web.SiteUsers;
          clientContext.Load<UserCollection>(users);
          clientContext.ExecuteQuery();
    
          foreach (User siteUser in users)
          {
              listOfUsers.Add(siteUser.LoginName);
          }
    
          foreach (List list in lists)
          {
              listOfLists.Add(list.Title);
          }
      }
    
  6. Agregue el método CSOM_Click dentro de la clase Página.Add the CSOM_Click method inside the Page class. Este método desencadena el evento que se produce cuando el usuario hace clic en el vínculo Rellenar datos.This method triggers the event that occurs when the user clicks the Populate Data link.

      protected void CSOM_Click(object sender, EventArgs e)
    {
        string commandAccessToken = ((LinkButton)sender).CommandArgument;
        RetrieveWithCSOM(commandAccessToken);
        WebTitleLabel.Text = siteName;
        CurrentUserLabel.Text = currentUser;
        UserList.DataSource = listOfUsers;
        UserList.DataBind();
        ListList.DataSource = listOfLists;
        ListList.DataBind();    
     }
    
  7. En primer lugar, reemplace el método Page_Load existente con este.Replace the existing Page_Load method with this one. El método Page_Load usa métodos del archivo TokenHelper.cs para recuperar el contexto del objeto Request y obtener un token de acceso desde Servicio de control de acceso (ACS) de Microsoft Azure.The Page_Load method uses methods in the TokenHelper.cs file to retrieve the context from the Request object and get an access token from Microsoft Azure Access Control Service (ACS).

      // The Page_load method fetches the context token and the access token. 
    // The access token is used by all of the data retrieval methods.
    protected void Page_Load(object sender, EventArgs e)
    {
         string contextTokenString = TokenHelper.GetContextTokenFromRequest(Request);
    
        if (contextTokenString != null)
        {
            contextToken =
                TokenHelper.ReadAndValidateContextToken(contextTokenString, Request.Url.Authority);
    
            sharepointUrl = new Uri(Request.QueryString["SPHostUrl"]);
            accessToken =
                        TokenHelper.GetAccessToken(contextToken, sharepointUrl.Authority)
                        .AccessToken;
    
             // For simplicity, this sample assigns the access token to the button's CommandArgument property. 
             // In a production add-in, this would not be secure. The access token should be cached on the server-side.
            CSOM.CommandArgument = accessToken;
        }
        else if (!IsPostBack)
        {
            Response.Write("Could not find a context token.");
            return;
        }
    }
    
  8. El archivo Default.aspx.cs necesita tener este aspecto cuando termine.The Default.aspx.cs file should look like this when you're finished.

      using System;
      using System.Collections.Generic;
      using System.Linq;
      using System.Web;
      using System.Web.UI;
      using System.Web.UI.WebControls;
    
      using Microsoft.SharePoint.Client;
      using Microsoft.IdentityModel.S2S.Tokens;
      using System.Net;
      using System.IO;
      using System.Xml;
    
      namespace SampleAddInWeb
      {
          public partial class Default : System.Web.UI.Page
          {
              SharePointContextToken contextToken;
              string accessToken;
              Uri sharepointUrl;
              string siteName;
              string currentUser;
              List<string> listOfUsers = new List<string>();
              List<string> listOfLists = new List<string>();
    
              protected void Page_PreInit(object sender, EventArgs e)
              {
                  Uri redirectUrl;
                  switch (SharePointContextProvider.CheckRedirectionStatus(Context, out redirectUrl))
                  {
                      case RedirectionStatus.Ok:
                          return;
                      case RedirectionStatus.ShouldRedirect:
                          Response.Redirect(redirectUrl.AbsoluteUri, endResponse: true);
                          break;
                      case RedirectionStatus.CanNotRedirect:
                          Response.Write("An error occurred while processing your request.");
                          Response.End();
                          break;
                  }
              }
    
              protected void CSOM_Click(object sender, EventArgs e)
              {
                  string commandAccessToken = ((LinkButton)sender).CommandArgument;
                  RetrieveWithCSOM(commandAccessToken);
                  WebTitleLabel.Text = siteName;
                  CurrentUserLabel.Text = currentUser;
                  UserList.DataSource = listOfUsers;
                  UserList.DataBind();
                  ListList.DataSource = listOfLists;
                  ListList.DataBind();
              }
    
              // This method retrieves information about the host web by using the CSOM.
              private void RetrieveWithCSOM(string accessToken)
              {
    
                  if (IsPostBack)
                  {
                      sharepointUrl = new Uri(Request.QueryString["SPHostUrl"]);
                  }
    
                  ClientContext clientContext =
                          TokenHelper.GetClientContextWithAccessToken(
                              sharepointUrl.ToString(), accessToken);
    
                  // Load the properties for the web object.
                  Web web = clientContext.Web;
                  clientContext.Load(web);
                  clientContext.ExecuteQuery();
    
                  // Get the site name.
                  siteName = web.Title;
    
                  // Get the current user.
                  clientContext.Load(web.CurrentUser);
                  clientContext.ExecuteQuery();
                  currentUser = clientContext.Web.CurrentUser.LoginName;
    
                  // Load the lists from the Web object.
                  ListCollection lists = web.Lists;
                  clientContext.Load<ListCollection>(lists);
                  clientContext.ExecuteQuery();
    
                  // Load the current users from the Web object.
                  UserCollection users = web.SiteUsers;
                  clientContext.Load<UserCollection>(users);
                  clientContext.ExecuteQuery();
    
                  foreach (User siteUser in users)
                  {
                      listOfUsers.Add(siteUser.LoginName);
                  }
    
                  foreach (List list in lists)
                  {
                      listOfLists.Add(list.Title);
                  }
              }
    
              protected void Page_Load(object sender, EventArgs e)
              {
                  string contextTokenString = 
                       TokenHelper.GetContextTokenFromRequest(Request);
    
                  if (contextTokenString != null)
                  {
                      contextToken =
                          TokenHelper.ReadAndValidateContextToken(contextTokenString, Request.Url.Authority);
    
                      sharepointUrl = new Uri(Request.QueryString["SPHostUrl"]);
                      accessToken =
                          TokenHelper.GetAccessToken(contextToken, sharepointUrl.Authority)
                                     .AccessToken;
                      CSOM.CommandArgument = accessToken;
                  }
                  else if (!IsPostBack)
                  {
                      Response.Write("Could not find a context token.");
                      return;
                  }
              }
          }
      }
    
    
  9. Use la tecla F5 para implementar y ejecutar el complemento.Use the F5 key to deploy and run your add-in. Si ve una ventana de Alerta de seguridad que le pide que confíe en el certificado autofirmado de Localhost, seleccione .If you see a Security Alert window that asks you to trust the self-signed Localhost certificate, select Yes.

  10. Seleccione Confiar en la página de consentimiento para conceder permisos al complemento.Select Trust It on the consent page to grant permissions to the add-in. Visual Studio instalará la aplicación web para IIS Express y, a continuación, instalará el complemento en su sitio de SharePoint de prueba y lo iniciará.Visual Studio will install the web application to IIS Express and then install the add-in to your test SharePoint site and launch it. Verá una página que muestra la tabla en la siguiente captura de pantalla.You'll see a page that has the table shown in the following screen shot. Para ver información resumida sobre el sitio de SharePoint, seleccione Rellenar datos.To see summary information about your SharePoint site, select Populate Data.

Página de inicio de aplicación autohospedada básica

Pasos siguientesNext steps

Para crear los complementos, siga los pasos siguientes en este orden:To create your add-ins, walk through the following steps in this order:

  1. Dar al complemento hospedado por el proveedor la apariencia de SharePointGive your provider-hosted add-in the SharePoint look-and-feel
  2. Incluir un botón personalizado en el complemento hospedado por el proveedorInclude a custom button in the provider-hosted add-in
  3. Obtener información general rápida sobre el modelo de objetos de SharePointGet a quick overview of the SharePoint object model
  4. Agregar operaciones de escritura de SharePoint en el complemento hospedado por el proveedorAdd SharePoint write operations to the provider-hosted add-in
  5. Incluir un elemento de complemento en el complemento hospedado por el proveedorInclude an add-in part in the provider-hosted add-in
  6. Controlar eventos de complemento en el complemento hospedado por el proveedorHandle add-in events in the provider-hosted add-in
  7. Agregar lógica de primera vista al complemento hospedado por el proveedorAdd first-run logic to the provider-hosted add-in
  8. Implementar con programación un botón personalizado en el complemento hospedado por el proveedorProgrammatically deploy a custom button in the provider-hosted add-in
  9. Controlar eventos de elementos de lista en el complemento hospedado por el proveedorHandle list item events in the provider-hosted add-in