Instrucciones de desarrollo para cmdlets de SharePoint Foundation
Última modificación: miércoles, 24 de marzo de 2010
Hace referencia a: SharePoint Foundation 2010
Al escribir cmdlets de Windows PowerShell para SharePoint (es decir, cmdlets personalizados que derivan de la clase base SPCmdlet), asegúrese de usar instrucciones de diseño específicas de SharePoint para garantizar que los cmdlets sean totalmente compatibles con los cmdlets de la biblioteca de cmdlets de SharePoint que se exponen en la Consola de administración de SharePoint. Además, en SharePoint Foundation también se recomiendan patrones de diseño que garanticen una interoperabilidad completa con la implementación de SharePoint.
Metodología para crear cmdlets de SharePoint
Al diseñar cmdlets específicos de SharePoint, siempre realice lo siguiente:
Defina los nombres de cmdlet.
Defina las propiedades de los nombres de cmdlet.
Defina los parámetros y los verbos de cmdlet.
Defina el progreso, la canalización y los errores de cmdlet.
Al seguir este proceso, el resultado será una definición exhaustiva del conjunto de cmdlets para el componente o la característica que va a desarrollar.
Definición de los nombres de cmdlet
Al definir un nombre de cmdlet, sea muy claro en cuanto a lo que administrará la característica. Piense en los nombres como elementos que administrará un administrador del sistema. Pueden ser objetos de SharePoint como objetos SPSite o SPWeb, o bien pueden ser características instaladas, como objetos SPFeature, plantillas de formulario o elementos web.
Como regla general, es mejor tener una gran cantidad de nombres que tengan menos propiedades que tener una pequeña cantidad de nombres con muchas propiedades. Todo nombre que tenga más de 15 propiedades estará sobrecargado.
Identifique la información del estado en tiempo de ejecución no persistente que desea exponer a los administradores del sistema. También identifique la información de estado que, si bien puede no ser persistente, debe devolverse a los administradores del sistema de todas maneras (por ejemplo, el estado en ejecución de un servicio).
Evalúe si un nombre recientemente definido debe dividirse en dos o varios nombres diferentes. Cree nombres independientes para elementos que sean semánticamente distintos. Use especificaciones de características o componentes para identificar si un nombre abarca varios conceptos o características.
Si un nombre abarca varios orígenes de datos (físicos o lógicos), divida el nombre según los límites de los orígenes de datos. Identifique un subconjunto de propiedades lógicamente independiente guardado en una sola base de datos u objeto de SharePoint. En la mayoría de los casos, este subconjunto debe convertirse en un nombre independiente, pero sólo si los nombres resultantes son lógicamente independientes y si pueden entenderse claramente como entidades distintas (es decir, separados fácilmente) sin confundir a los administradores del sistema.
Por cada objeto de origen de datos persistente usado por más de un nombre, unifique estos nombres en uno solo. Además, unifique los nombres cuya diferencia principal sea que tienen diferentes duraciones, ya que su creación y eliminación puede administrarse independientemente.
Definición de las propiedades de los nombres de cmdlet
Defina una propiedad Identity. Todos los nombres deben tener una propiedad Identity cuyo valor sea único e invariable, como un GUID.
Cree un enlace de canalización para el nombre. El enlace de canalización debe combinar todas las propiedades que pueden identificar exclusivamente al objeto.
Defina el conjunto completo de propiedades públicas para el nombre. Trate a la definición del nombre como si fuera una API pública. Todas las propiedades públicas relacionadas se exponen en la línea de comandos cuando se devuelve una instancia del nombre.
Defina un tipo de datos para cada propiedad. Las propiedades deben estar fuertemente tipadas, de modo que el código de validación del formato pueda adjuntarse al tipo de propiedad y no al nombre. Por ejemplo, una propiedad que representa una dirección de correo electrónico debe ser del tipo EmailAddress en lugar del tipo String.
Identifique las propiedades que son atípicamente grandes. Asegúrese de que las propiedades inusualmente grandes (mayores de 10 KB) se dividan en dos o varias propiedades.
Identifique las colecciones de propiedades que tengan una gran cantidad de elementos (por ejemplo, una colección con más de 100 elementos). Quite esas colecciones de propiedades de gran tamaño y divida los elementos en nombres independientes. A continuación, defina los verbos New, Remove, Get y Set para los nombres nuevos.
Por ejemplo, considere un escenario en el que Users es una propiedad de un objeto SPWeb, que puede tener una gran cantidad de elementos. Para evitar problemas, cree un nombre independiente denominado SPUser que represente un elemento de la lista y, a continuación, agregue los verbos New, Remove, Get y Set asociados.
Definición de los parámetros y los verbos de cmdlet
Determine cuál de los verbos base (Get, Set, New, Remove) se aplica al nombre. Como mínimo, los administradores del sistema deben poder obtener la configuración y cambiarla (o Set). Además, es posible que los administradores también necesiten crear nuevas instancias (New) y borrar instancias existentes (Remove).
Defina el comportamiento del cmdlet Get.
El verbo Get debe recuperar todas las instancias si no se especifica ningún parámetro y debe hacerlo mediante la escritura de las instancias en la canalización de Windows PowerShell. Sin embargo, toda operación que pueda devolver un conjunto de resultados muy grande debería incluir un parámetro Limit en el que se especifica un límite predeterminado. Desde luego, al limitar un conjunto de resultados de este modo, debe alertar a los usuarios que pueden excluirse resultados adicionales del conjunto de resultados limitado.
El verbo Get debe tener un parámetro Identity. Cuando se especifique, el cmdlet correspondiente sólo debe devolver la instancia asociada con esa identidad. Si la identidad especificada no es única, el cmdlet debe devolver todas las instancias con el valor de identidad especificado.
El verbo Get puede tener parámetros de filtrado opcionales adicionales. Por ejemplo, es posible que el cmdlet Get-SPSite tenga un parámetro ContentDatabase que restrinja el conjunto de resultados a las colecciones de sitios ubicadas en una base de datos de contenido especificada. Además, el verbo Get debe tener un parámetro Server si el cmdlet devuelve información de configuración local (es decir, específica del equipo).
Defina el comportamiento del cmdlet Set.
El verbo Set debe tener un parámetro Identity para identificar la instancia que se está cambiando. El parámetro debe poder tomar una identidad (por ejemplo, un GUID) o un nombre. Si se especifica un nombre que coincide con más de una instancia, el cmdlet debe devolver un error.
El parámetro Identity del cmdlet Set debe aceptar la entrada de canalización.
El verbo Set debe exponer todas las propiedades de escritura del nombre que se reciben mediante el cmdlet Get correspondiente, excepto aquellas que causan efectos negativos cuando se establecen.
El verbo Set debe tener un parámetro Instance opcional que represente una instancia completa de este tipo de nombre. El parámetro Instance debe aceptar la entrada de canalización (por valor).
Defina el comportamiento del cmdlet New.
El verbo New debe tomar un subconjunto limitado de propiedades de escritura del nombre como parámetros. Las propiedades restantes deben establecerse en valores predeterminados. Además, el cmdlet New debe devolver el objeto de la instancia recientemente creada a la canalización para que otros cmdlets de la canalización puedan actuar en la nueva instancia.
Defina el comportamiento del cmdlet Remove.
El cmdlet Remove debe tener un parámetro Identity que pueda tomar un valor de identidad o un nombre. Si se especifica un nombre que coincide con más de una instancia, el cmdlet debe devolver un error.
El parámetro Identity debe aceptar la entrada de canalización. Además, toda operación destructiva debe admitir los parámetros Confirm y WhaIf. Esto no requiere mucho esfuerzo, ya que Windows PowerShell y las clases base de SharePoint Foundation 2010 proporcionan medios para admitir estos parámetros.
Identifique y defina verbos adicionales para el nombre.
Por ejemplo, es posible que un nombre SPContentDatabase necesite un verbo Mount para admitir el montaje de la base de datos especificada. Use casos y escenarios administrativos probados adecuadamente para admitir la selección de verbos apropiados.
Recuerde que todos los cmdlets adicionales deben tener un parámetro Identity que acepte la entrada de canalización. El parámetro Identity debe aceptar la identidad (PipeBind) del objeto. Además, toda operación destructiva debe admitir los parámetros Confirm y WhaIf.
Identifique las propiedades que tienen posibles efectos negativos.
Es posible que las propiedades que tienen posibles efectos negativos necesiten operaciones adicionales para mitigar estos efectos. Estos cmdlets mitigadores adicionales deben tener un parámetro Identity que acepte la entrada de canalización.
Para cada cmdlet que defina, realice lo siguiente:
(a) Identifique la lista de requisitos previos para el cmdlet. Por ejemplo, en un caso en el que un cmdlet puede ejecutarse sólo en un cierto estado del sistema, el cmdlet debe comprobar que todos los requisitos previos de estado se cumplan antes de la ejecución.
(b) Identifique la lista de operaciones. Especifique la lista completa de las operaciones que puede llevar a cabo el cmdlet. El cmdlet debe llevar a cabo estas operaciones y, a continuación, validarlas. Esta lista de operaciones comprende el desglose funcional del cmdlet.
Definición del progreso, la canalización y los errores de cmdlet
Identifique todas las condiciones de error y comportamientos de estado de error. Es decir, enumere todas las condiciones en las que un cmdlet puede producir un error. A continuación, para cada condición, describa el comportamiento esperado. Los cmdlets deben proporcionar una administración de errores básica.
Los cmdlets deben limpiar los cambios parciales cuando se produce un error y deben devolver un mensaje de error significativo (y localizado, si corresponde). Además, los cmdlets deben determinar y revelar el modo en que un administrador del sistema puede recuperarse de cualquier condición de error.
Diferencie los errores de terminación y de no terminación.
Identifique las operaciones de larga ejecución. Si se espera que un cmdlet tarde un promedio de más de 20 segundos aproximadamente para completar una operación, el cmdlet debe proporcionar información de progreso para evitar que se suspenda la operación.
Asegúrese de que los cmdlets escriban los objetos de devolución directamente en la canalización. Evite el almacenaje de objetos recuperados en una matriz interna. La escritura en las canalizaciones permite a los cmdlets de canal de bajada actuar en objetos precedentes de la canalización sin retraso.
Agrupe los parámetros similares. Limite los cmdlets a 16 parámetros (no se incluyen los parámetros Identity y Name). En casos en que se llama a métodos de objeto con poca frecuencia y en que existe un método de modelo de objetos, no se necesita ningún parámetro de cmdlet. En casos en que se puede agrupar una gran cantidad de parámetros, escriba un solo parámetro que acepte el objeto de grupo.
Vea también
Conceptos
Control de errores para cmdlets de SharePoint Foundation
Introducción a los cmdlets de la Consola de administración de SharePoint