Procedimiento para crear un proveedor de aplicaciones externas personalizado

  • Artículo

En este tema se proporciona una introducción al proceso de creación de un proveedor de la aplicación externa (EAP) personalizado.

Última modificación: jueves, 08 de abril de 2010

Hace referencia a: SharePoint Foundation 2010

La creación de un EAP personalizado requiere que se deriven nuevas clases de una o ambas clases abstractas:

  • SPExternalApplicationRequestResult: son dos los escenarios en los que se debe implementar una clase derivada de SPExternalApplicationRequestResult:

    • El sitio y el reenviador de solicitudes donde se encuentra instalada la aplicación externa necesitan que todos los resultados que recibe de Microsoft SharePoint Foundation incluyan un hash de cliente que el reenviador de solicitudes pueda comprobar para garantizar que no se ha alterado el resultado.

    • Desea cambiar el modo en que SilverlightWebPart o algún elemento web personalizado que hospeda una aplicación que no es de SharePoint se representan; por ejemplo, desea representar un cromo personalizado para el elemento web.

  • SPExternalApplicationProvider: es necesario implementar esta clase en cualquiera de los siguientes escenarios:

    • Cualquier situación en la que implemente una clase derivada de la clase SPExternalApplicationRequestResult (vea lo anterior).

    • El XML de aplicación externa de un elemento web contiene marcado personalizado que debe leerse y procesarse.

    • Desea que se ejecute lógica especial cuando se crea el control secundario del elemento web.

    • Desea personalizar la interfaz de usuario de SilverlightToolPart o cambiar la página de registro de la aplicación que se abre al hacer clic en el botón Configurar del control ToolPart.

Nota importanteImportante

Al considerar la posibilidad de crear un EAP personalizado, tenga en cuenta que solo puede haber un EAP para todos los elementos web que hospedan aplicaciones en todas las aplicaciones web de SharePoint Foundation que son secundarias de un servicio web especificado.

Para implementar una clase de solicitud de resultados

  1. En Microsoft Visual Studio 2010, comience un proyecto de SharePoint vacío.

  2. Agregue al proyecto un elemento de clase.

  3. Establezca la clase para que herede desde SPExternalApplicationRequestResult.

  4. Si no desea un hash de cliente, implemente la propiedad ClientHash de modo que devuelva null. Si desea incluir un hash de cliente en los resultados enviados de vuelta a la aplicación externa, implemente la propiedad ClientHash como contenedor de un campo auxiliar privado que sea una matriz Byte.

    private Byte[] clientHash;
public override Byte[] ClientHash 
{
    get { return clientHash; } 
}

    Private clientHash_Renamed() As Byte
Public Overrides ReadOnly Property ClientHash() As Byte()
    Get
        Return clientHash_Renamed
    End Get
End Property

  5. Si usa un hash de cliente, cree un constructor que tome un parámetro de tipo SPExternalApplicationRequestProperties y otro que sea una matriz de bytes (que representa la sal de cliente). Este constructor debería usar la propiedad RequestTokenPrefix del objeto SPExternalApplicationRequestProperties y la matriz de bytes como una entrada al crear un valor hash de cliente. La matriz de bytes debe ser un valor proporcionado por el servidor que hospeda la aplicación externa y el algoritmo usado debe ser el mismo que usará la aplicación externa para crear la copia del hash de cliente. Considere la posibilidad de usar las clases del espacio de nombres System.Security.Cryptography, como HashAlgorithm o SHA512Managed. A continuación se muestra un ejemplo. Para usar la clase SHA512Managed como en este ejemplo, debe agregar una instrucción using (Imports en Visual Basic) para el espacio de nombres System.Security.Cryptography en el archivo de código.

    public CustomRequestResult() { }
public CustomRequestResult(SPExternalApplicationRequestProperties externalAppRequest, byte[] clientSalt)
{
    string prefix = externalAppRequest.RequestTokenPrefix;

    int nCount = Encoding.Unicode.GetByteCount(prefix);
    nCount += clientSalt.Length;
    byte[] bytes = new byte[nCount];
    nCount = Encoding.Unicode.GetBytes(prefix, 0, prefix.Length, bytes, 0);
    for (int i = 0; i < clientSalt.Length; i++)
    {
        bytes[nCount + i] = clientSalt[i];
    }
    // Compute the hash value
    SHA512Managed sha512 = new SHA512Managed();
    clientHash = sha512.ComputeHash(bytes);
}

    Public Sub New()
End Sub

Public Sub New(ByVal externalAppRequest As SPExternalApplicationRequestProperties, ByVal clientSalt() As Byte)
    Dim prefix As String = externalAppRequest.RequestTokenPrefix

    Dim nCount As Integer = Encoding.Unicode.GetByteCount(prefix)
    nCount += clientSalt.Length
    Dim bytes(nCount - 1) As Byte
    nCount = Encoding.Unicode.GetBytes(prefix, 0, prefix.Length, bytes, 0)
    For i As Integer = 0 To clientSalt.Length - 1
        bytes(nCount + i) = clientSalt(i)
    Next i
    ' Compute the hash value
    Dim sha512 As New SHA512Managed()
    clientHash = sha512.ComputeHash(bytes)
End Sub

    Si la única parte de la clase SPExternalApplicationRequestProperties que usa la clase derivada es la propiedad RequestTokenPrefix, el constructor podría escribirse de modo que tome un objeto String como primer parámetro y, posteriormente, el código de llamada (que es el método OnApplicationWebPartCreateChildControls(SPExternalApplicationRequestProperties) descrito a continuación) simplemente le pasará la propiedad RequestTokenPrefix. Otra opción consiste en diseñar el código de llamada para que cree el hash de cliente antes de construir un objeto del tipo derivado. En ese caso, se puede diseñar el constructor del tipo para que tome el propio valor hash como un parámetro de matriz de bytes y para que escriba inmediatamente en el campo de respaldo clientHash.

  6. Si no desea personalizar el modo en que el elemento web de Silverlight se representa o el modo en que se representa algún elemento web personalizado que hospeda una aplicación que no es de SharePoint, implemente el método GetContentControl(String) de modo que devuelva null. De lo contrario, implemente el método de modo que devuelva un Control que sea el control secundario único del elemento web. Normalmente, este será un Literal que contenga formato HTML.

Para implementar una clase de EAP

  1. Agregue al proyecto un elemento de clase.

  2. Establezca la clase para que herede de SPExternalApplicationProvider.

  3. Si desea personalizar la interfaz de usuario de SilverlightToolPart, implemente el método GetRegistrationInformation(SPWeb). Puede cambiar cualquiera de las cinco propiedades del objeto SPExternalApplicationRegistrationInformation que devuelve el método. Por ejemplo, si desea sustituir una página de registro personalizada, asigne la dirección URL de la página personalizada a la propiedad HyperlinkUrl. Puede usar el código en línea o el código subyacente de la página personalizada para proporcionar otros servicios a los usuarios. Por ejemplo, el código puede leer el Application XML y determinar si especifica un nombre de entidad de seguridad de la aplicación. Si es así, el código comprobará si ese usuario de entidad de seguridad de la aplicación existe y, de no ser así, lo creará.

    En el siguiente ejemplo se cambia el nombre del botón de la página de "Configurar" a "Registrar", el texto informativo del botón y el tamaño del diálogo que abre. Por medio del botón también se abre una página de registro de la aplicación alternativa personalizada. (La página de registro predeterminada es newslwp.aspx.)

    public override SPExternalApplicationRegistrationInformation GetRegistrationInformation(SPWeb web)
{
    SPExternalApplicationRegistrationInformation info = new SPExternalApplicationRegistrationInformation();
    info.Description = "To register a Silverlight application (.xap), click Register";
    info.DialogHeight = 600;
    info.DialogWidth = 500;
    string url = web.ServerRelativeUrl;
    if (!url.EndsWith("/"))
    {
        url = url + "/";
    }
    url += "_layouts/alternateReg.aspx";
    info.HyperlinkText = "Register";
    info.HyperlinkUrl = url;

    return info;
}

    Public Overrides Function GetRegistrationInformation(ByVal web As SPWeb) As SPExternalApplicationRegistrationInformation
    Dim info As New SPExternalApplicationRegistrationInformation()
    info.Description = "To register a Silverlight application (.xap), click Register"
    info.DialogHeight = 600
    info.DialogWidth = 500
    Dim url As String = web.ServerRelativeUrl
    If Not url.EndsWith("/") Then
        url = url & "/"
    End If
    url &= "_layouts/alternateReg.aspx"
    info.HyperlinkText = "Register"
    info.HyperlinkUrl = url

    Return info
End Function

  4. Si no derivó una clase de SPExternalApplicationRequestResult, entonces puede implementar OnApplicationWebPartCreateChildControls(SPExternalApplicationRequestProperties) para que simplemente devuelva null. De lo contrario, debe proporcionar a este método una implementación sustancial de modo que la clase de solicitud de resultados se construya y se use.

    El método CreateChildControls del elemento web llama al método OnApplicationWebPartCreateChildControls(SPExternalApplicationRequestProperties). Concretamente, el método CreateChildControls realiza lo siguiente:

    1. Construye un objeto SPExternalApplicationRequestProperties a partir del XML de aplicación externa que se usó para registrar el elemento web y a partir de información acerca del sitio web actual.

    2. Pasa el objeto SPExternalApplicationRequestProperties al método OnApplicationWebPartCreateChildControls(SPExternalApplicationRequestProperties).

    3. Recibe un objeto derivado de SPExternalApplicationRequestResult que devuelve el método OnApplicationWebPartCreateChildControls(SPExternalApplicationRequestProperties).

    4. Usa el método GetContentControl(String) del objeto de solicitud de resultados para obtener el control secundario único del elemento web.

    Figura 1: Llamadas realizadas por el método CreateChildControls.

    Elemento web CreateChildControls de Silverlight

    Si, por alguna razón, el método OnApplicationWebPartCreateChildControls(SPExternalApplicationRequestProperties) devuelve null, como ocurre en el EAP predeterminado creado en SharePoint Foundation, el método CreateChildControls necesitará representar un control secundario predeterminado. Esto es lo que hace el método CreateChildControls() de la clase SilverlightWebPart integrada.

    Por lo tanto, la tarea principal de la implementación del método OnApplicationWebPartCreateChildControls(SPExternalApplicationRequestProperties) es llamar al constructor de la clase derivada de SPExternalApplicationRequestResult y devolver el objeto construido. Tenga en cuenta estos puntos al desarrollar la invalidación del método OnApplicationWebPartCreateChildControls(SPExternalApplicationRequestProperties):

    En el siguiente ejemplo, el OnApplicationWebPartCreateChildControls(SPExternalApplicationRequestProperties) invalidado llama al constructor no predeterminado de una clase derivada de SPExternalApplicationRequestResult, denominada CustomRequestResult. Para obtener más información acerca de este constructor no predeterminado, vea el procedimiento Para implementar una clase de solicitud de resultados anteriormente en este tema.

    public override SPExternalApplicationRequestResult OnApplicationWebPartCreateChildControls(
            SPExternalApplicationRequestProperties args)
{
    SPExternalApplicationRequestResult reqRes = CustomRequestResult(args, saltFromApplication);
    return reqRes;
}

    Public Overrides Function OnApplicationWebPartCreateChildControls(ByVal args As SPExternalApplicationRequestProperties) As SPExternalApplicationRequestResult
        Dim reqRes As SPExternalApplicationRequestResult = CustomRequestResult(args, saltFromApplication)
        Return reqRes
End Function

Identificación del EAP en el servicio web

El proceso para identificar el EAP personalizado en SharePoint Foundation es prácticamente el mismo que el que se emplea para habilitar un EAP, como se describe en el tema Procedimiento para habilitar un proveedor de la aplicación externa. La única diferencia consiste en que en lugar de habilitar simplemente un EAP, se construye un objeto del tipo de EAP y se asigna a la propiedad ExternalApplicationSettings.Provider. En el siguiente ejemplo, ContosoEAP es una clase derivada de SPExternalApplicationProvider.

ContosoEAP exAppProvider = new ContosoEAP();
SPWebService.ContentService.ExternalApplicationSettings.Provider = exAppProvider;
SPWebService.ContentService.ExternalApplicationSettings.Enabled = true;
SPWebService.ContentService.Update(); 

Dim exAppProvider As New ContosoEAP()
SPWebService.ContentService.ExternalApplicationSettings.Provider = exAppProvider
SPWebService.ContentService.ExternalApplicationSettings.Enabled = True
SPWebService.ContentService.Update()
SugerenciaSugerencia

La línea que establece la propiedad Enabled no es necesaria si ya se ha habilitado la administración de aplicaciones externas para el servicio web, pero tampoco molesta si se conserva. Si no se ha habilitado la administración previamente y se incluye, ya no será necesario realizar el procedimiento Procedimiento para habilitar un proveedor de la aplicación externa. Sin embargo, no ocurre lo contrario: aunque se use el EAP predeterminado, debe ejecutarse el código de habilitación de la administración.

Todos los métodos para ejecutar las líneas de código anteriores mencionadas en el tema Procedimiento para habilitar un proveedor de la aplicación externa están a su disposición. En el siguiente ejemplo se muestra cómo ejecutar el código con el cmdlet Add-Type de Windows PowerShell en un script de la interfaz de la línea de comandos de Windows PowerShell.

Para identificar el EAP en el servicio web

  1. Agregue lo siguiente a un archivo de texto.

    Add-type @"
using System;
using Microsoft.SharePoint.Administration;

namespace ContosoCmdlets

    public class EAPIdentifier
    {
        public static void IdentifyEAP()
        {
            ContosoEAP exAppProvider = new ContosoEAP();
            SPWebService.ContentService.ExternalApplicationSettings.Provider = exAppProvider;
            SPWebService.ContentService.ExternalApplicationSettings.Enabled = true;
            SPWebService.ContentService.Update(); 
        }
    }
"@ -Language CsharpVersion3
[ContosoCmdlets.EAPIdentifier]::IdentifyEAP()

  2. Guarde el archivo como EAPIdentify.ps.

  3. Ejecute el script en una ventana de Windows PowerShell.