Пошаговое руководство. Разработка сборки настраиваемого правила статического анализа кода SQL

Статья
08/15/2011

Этот пошаговый раздел описывает этапы создания правила анализа кода SQL. Правило, создаваемое в этом пошаговом руководстве, применяется для того, чтобы избежать использования инструкций WAITFOR DELAY в хранимых процедурах, триггерах и функциях.

В этом пошаговом руководстве будет создано настраиваемое правило для статического анализа кода Transact-SQL с помощью следующих процессов.

Создание библиотеки классов, разрешение подписывать проект и добавление необходимых ссылок.
Создание двух вспомогательных классов C#.
Создание класса настраиваемого правила C#.
Создание XML-файла, который используется для регистрации сборки.
Копирование итогового DLL-файла и созданного XML-файла в каталог Extensions для регистрации.
Проверка готовности нового правила анализа кода.

Обязательные компоненты

Для выполнения инструкций данного пошагового руководства потребуется установить Visual Studio Premium или Visual Studio Ultimate.

Создание настраиваемых правил анализа кода SQL

Сначала необходимо создать библиотеку классов.

Создание библиотеки классов

В меню Файл последовательно выберите пункты Создать и Проект.
В диалоговом окне Создание проекта в области Установленные шаблоны щелкните Visual C#.
В области сведений выберите пункт Библиотека классов.
В текстовом поле Имя введите SampleRules и нажмите кнопку ОК.

Следующий шаг — подписывание проекта.

Включение подписывания проекта.

После выбора узла проекта SampleRules в обозревателе решений в меню Проект выберите пункт Свойства (или щелкните в обозревателе решений правой кнопкой мыши узел проекта и выберите команду Свойства).
Выберите вкладку Подпись.
Установите флажок Подписать сборку.
Укажите новый файл ключа. Выберите в раскрывающемся списке Выберите файл ключей строгого имени вариант <Новый>.

Появится диалоговое окно Создание ключа строгого имени. Дополнительные сведения см. в разделе Диалоговое окно "Создание ключа строгого имени".
В диалоговом окне Создание ключа строгого имени в текстовом поле Имя введите значение нового файла ключа. В этом пошаговом руководстве пароль не потребуется. Дополнительные сведения см. в разделе Управление сборками и подписывание манифестов.

Следующий шаг — добавление необходимых ссылок в проект.

Добавление ссылок в проект

Выберите проект SampleRules в обозревателе решений.
В меню Проект щелкните команду Добавить ссылку.

Откроется диалоговое окно Добавить ссылку. Дополнительные сведения см. в разделе Практическое руководство. Добавление и удаление ссылок в Visual Studio.
Выберите вкладку .NET.
В столбце Имя компонента найдите расположение следующих компонентов:
Примечание

Для выбора нескольких компонентов щелкните по ним, удерживая клавишу CTRL.
Нажмите кнопку OK после завершения выбора всех нужных компонентов.

Выбранные ссылки будут отображаться в обозревателе решений в узле Ссылки.

Создание вспомогательных пользовательских классов правил анализа кода

Перед созданием класса для правила в проект будут добавлены посетительский класс и вспомогательный класс.

Совет

Эти классы могут быть полезны при создании дополнительных пользовательских правил.

Первым необходимо определить класс WaitForDelayVisitor, производный от TSqlConcreteFragmentVisitor. Этот класс предоставляет доступ к операторам WAITFOR DELAY в модели.

Определение класса WaitForDelayVisitor

Выберите проект SampleRules в обозревателе решений.
В меню Проект выберите пункт Добавить класс.

Откроется диалоговое окно Добавление нового элемента.
В текстовом поле Имя введите WaitForDelayVisitor.cs и нажмите кнопку Добавить.

Файл WaitForDelayVisitor.cs добавляется в проект в обозревателе решений.
Откройте файл WaitForDelayVisitor.cs и обновите его содержимое в соответствии со следующим кодом:
```
using System.Collections.Generic;
using Microsoft.Data.Schema.ScriptDom.Sql;

namespace SampleRules
{
    class WaitForDelayVistor
    {
    }
}
```
В объявлении класса замените модификатор доступа на внутренний и выведите класс из TSqlConcreteFragmentVisitor:
```
    internal class WaitForDelayVisitor : TSqlConcreteFragmentVisitor
    {
    }
```
Добавьте следующий код для определения списка переменных-членов:
```
        private List<WaitForStatement> _waitForDelayStatments;
```

Определите конструктор класса, добавив следующий код:

        #region ctor
        public WaitForDelayVisitor()
        {
            _waitForDelayStatments = new List<WaitForStatement>();
        }
        #endregion

Определите свойство только для чтения WaitForDelayStatements, добавив следующий код:

        #region properties
        public List<WaitForStatement> WaitForDelayStatements
        {
            get
            {
                return _waitForDelayStatments;
            }
        }
        #endregion

Переопределите метод ExplicitVisit, добавив следующий код:
```
        #region overrides
        public override void ExplicitVisit(WaitForStatement node)
        {
            // We are only interested in WAITFOR DELAY occurrences
            if (node.WaitForOption == WaitForOption.Delay)
            {
                _waitForDelayStatments.Add(node);
            }
        }
        #endregion
```
Этот метод считывает операторы WAITFOR в модели и добавляет те, которые имеют параметр DELAY, указанный в списке операторов WAITFOR DELAY. Указанный здесь ключевой класс — WaitForStatement.
В меню Файл выберите пункт Сохранить.

Второй класс — SqlRuleUtils.cs. Он содержит несколько служебных методов, используемых пользовательским классом правил анализа кода, который будет создан в разделе Создание пользовательских классов правил анализа кода этого обзора. Эти методы перечислены ниже.

GetElementName — используется для получения полного имени элемента модели без специальных знаков.
UpdateProblemPosition — используется для получения сведений о номере строки и номере столбца.
ReadFileContent — используется для считывания содержимого файла.
GetElementSourceFile — используется для получения исходного файла.
ComputeLineColumn — используется для преобразования смещения из ScriptDom в номер строки и номер столбца в файлах сценариев.

Добавление файла SqlRuleUtils.cs в проект

Выберите проект SampleRules в обозревателе решений.
В меню Проект выберите пункт Добавить класс.

Откроется диалоговое окно Добавление нового элемента.
В текстовом поле Имя введите SqlRuleUtils.cs и нажмите кнопку Добавить.

Файл SqlRuleUtils.cs добавляется в проект в обозревателе решений.

Откройте файл SqlRuleUtils.cs и добавьте в него следующие операторы using:

using System;
using System.Diagnostics;
using System.IO;
using Microsoft.Data.Schema.SchemaModel;
using Microsoft.Data.Schema.Sql.SchemaModel;
using Microsoft.Data.Schema.StaticCodeAnalysis;
using Microsoft.Data.Schema;


namespace SampleRules
{
}

В объявлении класса SqlRuleUtils замените модификатор доступа на public static:
```
    public static class SqlRuleUtils
    {
    }
```

Добавьте следующий код для создания метода GetElementName, который использует в качестве входных параметров SqlSchemaModel и ISqlModelElement:

        /// <summary>
        /// Get escaped fully qualified name of a model element 
        /// </summary>
        /// <param name="sm">schema model</param>
        /// <param name="element">model element</param>
        /// <returns>name of the element</returns>
        public static string GetElementName(SqlSchemaModel sm, ISqlModelElement element)
        {
            return sm.DatabaseSchemaProvider.UserInteractionServices.GetElementName(element, ElementNameStyle.EscapedFullyQualifiedName);
        }

Добавьте следующий код для создания метода ReadFileContent:

        /// <summary>
        /// Read file content from a file.
        /// </summary>
        /// <param name="filePath"> file path </param>
        /// <returns> file content in a string </returns>
        public static string ReadFileContent(string filePath)
        {
            //  Verify that the file exists first.
            if (!File.Exists(filePath))
            {
                Debug.WriteLine(string.Format("Cannot find the file: '{0}'", filePath));
                return string.Empty;
            }

            string content;
            using (StreamReader reader = new StreamReader(filePath))
            {
                content = reader.ReadToEnd();
                reader.Close();
            }
            return content;
        }

Добавьте следующий код для создания метода GetElementSourceFile, который использует IModelElement в качестве входного параметра и String для получения имени файла. Метод использует приведение типа IModelElement к типу IScriptSourcedModelElement, а затем использует ISourceInformation для определения пути к файлу сценария по элементу модели.

        /// <summary>
        /// Get the corresponding script file path from a model element.
        /// </summary>
        /// <param name="element">model element</param>
        /// <param name="fileName">file path of the scripts corresponding to the model element</param>
        /// <returns></returns>
        private static Boolean GetElementSourceFile(IModelElement element, out String fileName)
        {
            fileName = null;

            IScriptSourcedModelElement scriptSourcedElement = element as IScriptSourcedModelElement;
            if (scriptSourcedElement != null)
            {
                ISourceInformation elementSource = scriptSourcedElement.PrimarySource;
                if (elementSource != null)
                {
                    fileName = elementSource.SourceName;
                }
            }

            return String.IsNullOrEmpty(fileName) == false;
        }

Добавьте следующий код для создания метода ComputeLineColumn:

        /// This method converts offset from ScriptDom to line\column in script files.
        /// A line is defined as a sequence of characters followed by a carriage return ("\r"), 
        /// a line feed ("\n"), or a carriage return immediately followed by a line feed. 
        public static bool ComputeLineColumn(string text, Int32 offset, Int32 length,
                                            out Int32 startLine, out Int32 startColumn, out Int32 endLine, out Int32 endColumn)
        {
            const char LF = '\n';
            const char CR = '\r';

            // Setting the initial value of line and column to 0 since VS auto-increments by 1.
            startLine = 0;
            startColumn = 0;
            endLine = 0;
            endColumn = 0;

            int textLength = text.Length;

            if (offset < 0 || length < 0 || offset + length > textLength)
            {
                return false;
            }

            for (int charIndex = 0; charIndex < length + offset; ++charIndex)
            {
                char currentChar = text[charIndex];
                Boolean afterOffset = charIndex >= offset;
                if (currentChar == LF)
                {
                    ++endLine;
                    endColumn = 0;
                    if (afterOffset == false)
                    {
                        ++startLine;
                        startColumn = 0;
                    }
                }
                else if (currentChar == CR)
                {
                    // CR/LF combination, consuming LF.
                    if ((charIndex + 1 < textLength) && (text[charIndex + 1] == LF))
                    {
                        ++charIndex;
                    }

                    ++endLine;
                    endColumn = 0;
                    if (afterOffset == false)
                    {
                        ++startLine;
                        startColumn = 0;
                    }
                }
                else
                {
                    ++endColumn;
                    if (afterOffset == false)
                    {
                        ++startColumn;
                    }
                }
            }

            return true;
        }

Добавьте следующий код для создания метода UpdateProblemPosition, который использует в качестве входного параметра DataRuleProblem:

        /// <summary>
        /// Compute the start Line/Col and the end Line/Col to update problem info
        /// </summary>
        /// <param name="problem">problem found</param>
        /// <param name="offset">offset of the fragment having problem</param>
        /// <param name="length">length of the fragment having problem</param>
        public static void UpdateProblemPosition(DataRuleProblem problem, int offset, int length)
        {
            if (problem.ModelElement != null)
            {
                String fileName = null;
                int startLine = 0;
                int startColumn = 0;
                int endLine = 0;
                int endColumn = 0;

                bool ret = GetElementSourceFile(problem.ModelElement, out fileName);
                if (ret)
                {
                    string fullScript = ReadFileContent(fileName);

                    if (fullScript != null)
                    {
                        if (ComputeLineColumn(fullScript, offset, length, out startLine, out startColumn, out endLine, out endColumn))
                        {
                            problem.FileName = fileName;
                            problem.StartLine = startLine + 1;
                            problem.StartColumn = startColumn + 1;
                            problem.EndLine = endLine + 1;
                            problem.EndColumn = endColumn + 1;
                        }
                        else
                        {
                            Debug.WriteLine("Could not compute line and column");
                        }
                    }
                }
            }
        }

В меню Файл выберите пункт Сохранить.

Затем добавьте файл ресурсов, который определит имя правила, описание правила и категорию интерфейса конфигурации правила, в которой появится правило.

Добавление файла ресурсов и трех ресурсных строк

Выберите проект SampleRules в обозревателе решений.
В меню Проект выберите команду Добавить новый элемент.

Откроется диалоговое окно Добавление нового элемента.
В списке Установленные шаблоны щелкните Общие.
В области сведений щелкните Файл ресурсов.
В поле Имя введите SampleRuleResource.resx.

Появится редактор ресурсов с еще не определенными ресурсами.

Определите следующие три ресурсные строки:

Имя	Значение
AvoidWaitForDelay_ProblemDescription	Оператор WAITFOR DELAY найден в {0}.
AvoidWaitForDelay_RuleName	Не рекомендуется использовать операторы WaitFor Delay в хранимых процедурах, функциях и триггерах.
CategorySamples	SamplesCategory

В меню Файл выберите Сохранить WinFormStrings.resx.

Затем определите класс, который ссылается на ресурсы в файле ресурсов, используемые в Visual Studio для отображения сведений о правиле в пользовательском интерфейсе.

Определение класса SampleConstants

Выберите проект SampleRules в обозревателе решений.
В меню Проект выберите пункт Добавить класс.

Откроется диалоговое окно Добавление нового элемента.
В текстовом поле Имя введите SampleRuleConstants.cs и нажмите кнопку Добавить.

Файл SampleRuleConstants.cs добавляется в проект в обозревателе решений.

Откройте файл SampleRuleConstants.cs и добавьте в него следующие операторы using:

namespace SampleRules
{
    internal class SampleConstants
    {
        public const string NameSpace = "SamplesRules";
        public const string ResourceBaseName = "SampleRules.SampleRuleResource";
        public const string CategorySamples = "CategorySamples";

        public const string AvoidWaitForDelayRuleId = "SR1004";
        public const string AvoidWaitForDelay_RuleName = "AvoidWaitForDelay_RuleName";
        public const string AvoidWaitForDelay_ProblemDescription = "AvoidWaitForDelay_ProblemDescription";
    }
}

В меню Файл выберите пункт Сохранить.

Создание пользовательских классов правил анализа кода

После добавления вспомогательных классов, используемых пользовательским правилом анализа кода, будет создан пользовательский класс правил с именем AvoidWaitForDelayRule. Пользовательское правило AvoidWaitForDelayRule поможет разработчикам баз данных избежать использования операторов WAITFOR DELAY в хранимых процедурах, триггерах и функциях.

Создание класса AvoidWaitForDelayRule

Выберите проект SampleRules в обозревателе решений.
В меню Проект выберите команду Создать папку.
В обозревателе решений создается новая папка. Присвойте папке имя AvoidWaitForDelayRule.
В обозревателе решений проверьте, выбрана ли папка AvoidWaitForDelayRule.
В меню Проект выберите пункт Добавить класс.

Откроется диалоговое окно Добавление нового элемента.
В текстовом поле Имя введите AvoidWaitForDelayRule.cs и нажмите кнопку Добавить.

Файл AvoidWaitForDelayRule.cs добавляется в папку проекта AvoidWaitForDelayRule в обозревателе решений.

Откройте файл AvoidWaitForDelayRule.cs и добавьте в него следующие операторы using:

using System;
using System.Collections.Generic;
using System.Diagnostics;
using System.Globalization;
using Microsoft.Data.Schema.Extensibility;
using Microsoft.Data.Schema.SchemaModel;
using Microsoft.Data.Schema.ScriptDom.Sql;
using Microsoft.Data.Schema.Sql.SchemaModel;
using Microsoft.Data.Schema.Sql;
using Microsoft.Data.Schema.StaticCodeAnalysis;
namespace SampleRules
{
    public class AvoidWaitForDelayRule
    {
    }
}

Примечание

Необходимо изменить имя пространства имен с SampleRules.AvoidWaitForDelayRule на SampleRules.

В объявлении класса AvoidWaitForDelayRule замените модификатор доступа на public:

    /// <summary>
    /// This is a SQL rule which returns a warning message 
    /// whenever there is a WAITFOR DELAY statement appears inside a subroutine body. 
    /// This rule only applies to SQL stored procedures, functions and triggers.
    /// </summary>
    public class AvoidWaitForDelayRule

Класс AvoidWaitForDelayRule является производными от базового класса StaticCodeAnalysisRule:
```
    public class AvoidWaitForDelayRule : StaticCodeAnalysisRule
```
Добавьте DatabaseSchemaProviderCompatibilityAttribute, DataRuleAttribute и SupportedElementTypeAttribute в класс. Дополнительные сведения о компоненте совместимости расширений см. в разделе Расширение функций баз данных в Visual Studio.
```
    [DatabaseSchemaProviderCompatibility(typeof(SqlDatabaseSchemaProvider))]
    [DataRuleAttribute(
        SampleConstants.NameSpace,
        SampleConstants.AvoidWaitForDelayRuleId,
        SampleConstants.ResourceBaseName,
        SampleConstants.AvoidWaitForDelay_RuleName,
        SampleConstants.CategorySamples,
        DescriptionResourceId = SampleConstants.AvoidWaitForDelay_ProblemDescription)]
    [SupportedElementType(typeof(ISqlProcedure))]
    [SupportedElementType(typeof(ISqlTrigger))]
    [SupportedElementType(typeof(ISqlFunction))]
    public class AvoidWaitForDelayRule : StaticCodeAnalysisRule
```
DataRuleAttribute указывает сведения, которые появляются в Visual Studio при настройке правил анализа кода базы данных. SupportedElementTypeAttribute определяет типы элементов, к которым данное правило будет применено. В этом случае правило будет применяться к хранимым процедурам, триггерам и функциям.

Добавьте переопределение для метода Analyze, который использует в качестве входных параметров DataRuleSetting и DataRuleExecutionContext. Этот метод возвращает список потенциальных трудностей.

Данный метод получает IModelElement и TSqlFragment из параметра контекста. SqlSchemaModel и ISqlModelElement получаются из элемента модели. Класс WaitForDelayVisitor используется для получения списка всех операторов WAITFOR DELAY в модели.

Для каждого WaitForStatement в этом списке создан DataRuleProblem.

        #region Overrides
        /// <summary>
        /// Analyze the model element
        /// </summary>
        public override IList<DataRuleProblem> Analyze(DataRuleSetting ruleSetting, DataRuleExecutionContext context)
        {
            List<DataRuleProblem> problems = new List<DataRuleProblem>();

            IModelElement modelElement = context.ModelElement;

            // this rule does not apply to inline table-valued function
            // we simply do not return any problem
            if (modelElement is ISqlInlineTableValuedFunction)
            {
                return problems;
            }

            // casting to SQL specific 
            SqlSchemaModel sqlSchemaModel = modelElement.Model as SqlSchemaModel;
            Debug.Assert(sqlSchemaModel!=null, "SqlSchemaModel is expected");

            ISqlModelElement sqlElement = modelElement as ISqlModelElement;
            Debug.Assert(sqlElement != null, "ISqlModelElement is expected");

            // Get ScriptDom for this model element
            TSqlFragment sqlFragment = context.ScriptFragment as TSqlFragment;
            Debug.Assert(sqlFragment != null, "TSqlFragment is expected");

            // visitor to get the ocurrences of WAITFOR DELAY statements
            WaitForDelayVisitor visitor = new WaitForDelayVisitor();
            sqlFragment.Accept(visitor);
            List<WaitForStatement> waitforDelayStatements = visitor.WaitForDelayStatements;

            // Create problems for each WAITFOR DELAY statement found 
            foreach (WaitForStatement waitForStatement in waitforDelayStatements)
            {
                DataRuleProblem problem = new DataRuleProblem(this,
                                            String.Format(CultureInfo.CurrentCulture, this.RuleProperties.Description, SqlRuleUtils.GetElementName(sqlSchemaModel, sqlElement)),
                                            sqlElement);

                SqlRuleUtils.UpdateProblemPosition(problem, waitForStatement.StartOffset, waitForStatement.FragmentLength);
                problems.Add(problem);
            }

            return problems;
        }

        #endregion

В меню Файл выберите пункт Сохранить.

Следующий шаг — построение проекта.

Построение проекта

В меню Построение выберите команду Построить решение.

На следующем этапе необходимо собрать сведения о сборке, содержащиеся в проекте, включая сведения о версии, языке и региональных параметрах и PublicKeyToken.

Сбор сведений о сборке

В меню Вид выберите пункт Другие окна, а затем — Окно команд, чтобы открыть командное окно.
В окне Команда введите следующий код. Вместо FilePath подставьте путь и имя откомпилированного DLL-файла. Заключите путь и имя файла в кавычки.

Примечание

По умолчанию для FilePath установлено значение Projects\SampleRules\SampleRules\bin\Debug\YourDLL или Projects\SampleRules\SampleRules\bin\Release\YourDLL.
```
? System.Reflection.Assembly.LoadFrom(@"FilePath")
```
Нажмите клавишу ВВОД. Строка должна иметь следующий вид (с учетом конкретного значения PublicKeyToken):
```
"SampleRules, Version=1.0.0.0, Culture=neutral, PublicKeyToken=nnnnnnnnnnnnnnnn"
```
Добавьте примечания к сведениям о сборке или скопируйте их; они будут использоваться в следующей процедуре.

После этого будет создан XML-файл с использованием сведений о сборке, собранных в предыдущей процедуре.

Создание XML-файла

Выберите проект SampleRules в обозревателе решений.
В меню Проект выберите команду Добавить новый элемент.
В панели Шаблоны найдите и выберите пункт XML-файл.
В текстовом поле Имя введите SampleRules.Extensions.xml и нажмите кнопку Добавить.

Файл SampleRules.Extensions.xml будет добавлен в проект и отобразится в окне обозревателя решений.

Откройте файл SampleRules.Extensions.xml и обновите его в соответствии со следующим XML-файлом. Замените сведения о версии, языке и региональных параметрах, а также PublicKeyToken на значения, которые были получены в предыдущей процедуре.

<?xml version="1.0" encoding="utf-8"?>
<extensions assembly=""
            version="1" xmlns="urn:Microsoft.Data.Schema.Extensions"
            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xsi:schemaLocation="urn:Microsoft.Data.Schema.Extensions Microsoft.Data.Schema.Extensions.xsd">

  <extension type="SampleRules.AvoidWaitForDelayRule" assembly="SampleRules, Version=1.0.0.0, Culture=neutral, PublicKeyToken=b4deb9b383d021b0" enabled="true"/>
</extensions>

В меню Файл щелкните Сохранить.

Далее необходимо скопировать сведения о сборке и XML-файл в каталог Extensions. При запуске Visual Studio будет идентифицировать все расширения в каталоге Microsoft Visual Studio 10.0\VSTSDB\Extensions и вложенных каталогах, регистрируя их для использования в сеансе.

Копирование сведений о сборке и XML-файла в каталог Extensions

В каталоге Microsoft Visual Studio 10.0\VSTSDB\Extensions\ создайте папку с именем CustomRules.
Скопируйте файл сборки SampleRules.dll из каталога Projects\SampleRules\SampleRules\bin\Debug\ в созданный каталог Microsoft Visual Studio 10.0\VSTSDB\Extensions\CustomRules.
Скопируйте файл SampleRules.Extensions.xmll из каталога Projects\SampleRules\SampleRules\ в созданный каталог Microsoft Visual Studio 10.0\VSTSDB\Extensions\CustomRules.

Примечание

Рекомендуется помещать сборки расширения во вложенную папку каталога Microsoft Visual Studio 10.0\VSTSDB\Extensions.Это облегчит определение того, какие расширения изначально входили в продукт, а какие были созданы пользователем.Кроме того, с помощью папок можно группировать расширения по категориям.

Следующий шаг — запуск нового сеанса Visual Studio и создание проекта базы данных.

Запуск нового сеанса Visual Studio и создание проекта базы данных

Запустите второй сеанс Visual Studio.
В меню Файл последовательно выберите пункты Создать и Проект.
В диалоговом окне Новый проект в списке Установленные шаблоны разверните узел Проекты базы данных и щелкните SQL Server.
В области сведений выберите Проект базы данных SQL Server 2008.
В текстовом поле Имя введите SampleRulesDB и нажмите кнопку ОК.

После завершения процедуры новое правило отобразится в проекте SQL Server.

Просмотр нового правила анализа кода AvoidWaitForRule

Выберите проект SampleRulesDB в обозревателе решений.
В меню Проект выберите пункт Свойства.

Отобразится страница свойств проекта SampleRulesDB.
Выберите пункт Анализ кода.

Должна появиться новая категория CategorySamples.
Разверните CategorySamples.

Должно появиться сообщение SR1004: Не рекомендуется использовать оператор WAITFOR DELAY в хранимых процедурах, триггерах и функциях.

См. также

Поделиться через