Инструкции по разработке командлетов SharePoint Foundation
Дата последнего изменения: 24 марта 2010 г.
Применимо к: SharePoint Foundation 2010
При написании командлетов Windows PowerShell для SharePoint, т. е. пользовательских командлетов, производных от базового класса SPCmdlet, используйте инструкции по разработке для SharePoint, чтобы обеспечить совместимость командлетов с основными командлетами в библиотеке SharePoint, предоставляемой SharePoint. Кроме того, SharePoint Foundation рекомендует использовать шаблоны проектирования, которые обеспечивают полное взаимодействие с развертыванием SharePoint.
Методология создания командлетов SharePoint
При разработке командлетов для SharePoint всегда выполняйте следующие действия.
Определите существительные командлетов.
Определите свойства существительных командлетов.
Определите глаголы и параметры командлетов.
Определите ошибки, ход выполнения и конвейер командлетов.
Если следовать этому процессу, результатом будет полное определение набора командлетов для развертываемого компонента или возможности.
Определение существительных командлетов
При определении существительного командлета нужно четко представлять, чем будет управлять возможность. Думайте о существительных, как об элементах, которыми управляет системный администратор. Это могут быть объекты SharePoint, такие как SPSite и SPWeb, или это могут быть установленные возможности, такие как объекты SPFeature, шаблоны форм и веб-части.
Как правило, лучше иметь больше существительных с меньшим количеством свойств, чем иметь мало существительных со многими свойствами. Любое существительное с более чем 15 свойствами будет перегружено.
Определите несохраняемые сведения о состоянии времени выполнения, доступ к которым нужно предоставить системным администраторам. Также определите сведения о состоянии, которые могут не сохраняться, но при этом возвращаются системным администраторам (например, состояние работы службы).
Оцените, следует ли разделить новое существительное на два или более существительных. Создайте отдельные существительные для элементов, которые семантически отличаются. Используйте спецификации возможности или компонента, чтобы определить, охватывает ли существительное несколько концепций или возможностей.
Если существительное охватывает несколько источников данных (физических или логических), разделите его по границам источников данных. Определите логически независимое подмножество свойств, которое сохраняется в одной базе данных или одном объекте SharePoint. В большинстве случаев это подмножество должно стать отдельным существительным, но только если полученные существительные логически независимы и только если они понимаются как отдельные сущности (т. е. легко разделяются), не вводя при этом системных администраторов в заблуждение.
Для каждого сохраняемого объекта источника данных, который используется несколькими существительными, следует объединить эти существительные в одно. Также нужно объединить существительные, основное отличие которых состоит в том, что у них разные сроки жизни, так как их созданием и удалением можно управлять по отдельности.
Определение свойств существительных командлетов
Определите свойство Identity. У всех существительных должно быть свойство Identity, значение которого уникально и постоянно, например идентификатор GUID.
Создайте конвейерную привязку для существительного. Конвейерная привязка должна объединять все свойства, которые могут уникально определить объект.
Определите полный набор общих свойств существительного. Обращайтесь с определением существительного как с открытым интерфейсом API. Все связанные общие свойства открыты в командной строке при возврате экземпляра существительного.
Определите тип данных каждого свойства. Свойства должны быть строго типизированы, чтобы код проверки формата можно было присоединить к типу свойства, а не к существительному. Например, свойство, представляющее адрес электронной почты, должно быть типа EmailAddress, а не String.
Определите слишком большие свойства. Убедитесь, что необычно большие свойства (больше 10 КБ) разделены на два или более свойств.
Определите коллекции свойств с большим количеством элементов (например, коллекции с более чем 100 элементами). Удалите такие коллекции и разделите элементы в отдельные существительные. Затем определите глаголы New, Remove, Get и Set для новых существительных.
Например, рассмотрим случай, где Users — это свойство объекта SPWeb, в котором может быть большое количество элементов. Чтобы избежать проблем, создайте отдельное существительное с именем SPUser, которое представляет один элемент в списке, затем добавьте связанные с ним глаголы New, Remove, Get и Set.
Определение глаголов и параметров командлетов
Определите, какие из базовых глаголов (Get, Set, New, Remove) следует применить к существительному. Как минимум системные администраторы должны иметь возможность получать параметры и изменять (или Set) их. Кроме того администраторам также может потребоваться создавать новые экземпляры (New) и удалять существующие (Remove).
Определите поведение командлета Get.
Глагол Get должен получать все экземпляры, если параметры не указаны, и это происходит за счет записи экземпляров в конвейер Windows PowerShell. Однако любая операция, которая может вернуть очень большой набор результатов, должна включать параметр Limit, который определяет предел по умолчанию. Конечно, при определении предела таким образом следует предупредить пользователей, что дополнительные результаты могут быть исключены из ограниченного набора результатов.
Глагол Get должен содержать параметр Identity. Если он указан, соответствующий командлет возвращает только экземпляр, связанный с этим удостоверением. Если указанное удостоверение не уникально, командлет должен вернуть все экземпляры с заданным значением удостоверения.
Глагол Get может содержать дополнительные параметры фильтрования. Например, командлет Get-SPSite может использовать параметр ContentDatabase, который ограничивает набор результатов для семейств сайтов, размещенных в определенной базе данных контента. Кроме того, глагол Get должен содержать параметр Server, если командлет возвращает локальные (для определенного компьютера) сведения о конфигурации.
Определите поведение командлета Set.
Глагол Set должен использовать параметр Identity для определения изменяемого экземпляра. Этот параметр должен принимать удостоверение (например, идентификатор GUID) или имя. Если указано имя и оно совпадает с несколькими экземплярами, командлет должен возвращать ошибку.
Параметр Identity командлета Set должен принимать входные данные конвейера.
Глагол Set должен предоставлять доступ ко всем свойствам существительного, которые доступны для записи и получены при использовании соответствующего командлета Get, за исключением тех, которые могут вызвать отрицательные результаты.
Глагол Setдолжен содержать дополнительный параметр Instance, представляющий весь экземпляр этого типа существительных. Параметр Instance должен принимать входные данные конвейера (по значению).
Определите поведение командлета New.
Глагол New должен принимать ограниченное подмножество свойств существительного, доступных для записи, как параметры. Оставшиеся свойства должны иметь значения по умолчанию. Кроме того, командлет New должен возвращать созданный объект экземпляра в конвейер, чтобы последующие командлеты могли воздействовать на новый экземпляр.
Определите поведение командлета Remove.
Командлет Remove должен использовать параметр Identity, который может принимать значение удостоверения или имя. Если указано имя и оно совпадает с несколькими экземплярами, командлет должен возвращать ошибку.
Параметр Identity должен принимать входные данные конвейера. Кроме того, любая операция удаления должна поддерживать параметры Confirm и WhaIf. Это не очень сложно, так как Windows PowerShell и базовые классы SharePoint Foundation 2010 обеспечивают поддержку этих параметров.
Выявите и определите дополнительные глаголы для существительного.
Например, глаголу SPContentDatabase может потребоваться глагол Mount для поддержки подключения определенной базы данных. Используйте проверенные сценарии администрирования для поддержки выбора соответствующих глаголов.
Помните, что все дополнительные командлеты должны содержать параметр Identity, который принимает входные данные конвейера. Параметр Identity также должен принимать удостоверение (PipeBind) объекта. Кроме того, любая операция удаления должна поддерживать параметры Confirm и WhaIf.
Определите свойства с потенциальными нежелательными побочными действиями.
При применении свойств с потенциальными нежелательными побочными действиями могут потребоваться дополнительные операции для устранения этих действий. Эти дополнительные командлеты должны содержать параметр Identity, который принимает входные данные конвейера.
Для каждого определяемого командлета выполните следующие действия.
Определите список необходимых компонентов для командлета. Например, если командлет выполняется только при определенном состоянии системы, он должен проверять все необходимые условия перед своим выполнением.
Определите список операций. Укажите полный список операций, которые может выполнить командлет. Командлет должен выполнять и проверять эти операции. Данный список операций составляет функциональную структуру командлета.
Определение ошибок, хода выполнения и конвейера командлета
Определите все ошибочные условия и поведение в случае ошибки. Т. е. список всех условий, при которых командлет вызывает ошибку. Затем для каждого условия опишите ожидаемое поведение. Командлеты должны обеспечивать базовые функции управления ошибками.
Командлеты должны отменять частичные изменения при возникновении ошибки и должны возвращать значимое (и локализованное, если это возможно) сообщение об ошибке. Кроме того командлеты должны определять и указывать, как системный администратор может исправить любое ошибочное состояние.
Отличайте прерывающие и непрерывающие ошибки.
Определите длительные операции. Если ожидается, что командлет будет выполняться в среднем более двадцати секунд, он должен предоставлять сведения о ходе выполнения, чтобы избежать видимости прерванной операции.
Убедитесь, что командлеты записывают возвращаемые объекты напрямую в конвейер. Избегайте буферизации полученных объектов во внешнем массиве. Запись в конвейер позволяет подчиненным командлетам работать с объектами в конвейере без задержки.
Группируйте схожие параметры. Ограничивайте число параметров до 16 (не включая параметры Identity и Name). Если методы объекта вызываются редко и при этом существует метод объектной модели, параметры командлета не требуются. Если можно сгруппировать большое количество параметров, напишите один параметр, принимающий групповой объект.