Отладка текстового шаблона T4
Точки останова можно задать в текстовых шаблонах. Чтобы выполнить отладку текстового шаблона во время разработки, сохраните текстовый файл шаблона и выберите "Отладка шаблона T4" в контекстном меню файла в Обозреватель решений. Чтобы выполнить отладку текстового шаблона во время выполнения, просто отладите приложение, к которому он принадлежит.
Чтобы выполнить отладку текстового шаблона, необходимо понять шаги процесса преобразования шаблона. На каждом шаге могут возникать различные виды ошибок. Ниже приведены шаги.
| Этап | Шаблон времени разработки: когда это происходит | Шаблон времени выполнения: когда это происходит |
|---|---|---|
| Код создается из текстового шаблона. Ошибки в директивах или несоответствие <#...#> или нарушение тегов. |
При сохранении шаблона или вызове преобразования текста. | При сохранении шаблона или вызове преобразования текста. |
| Созданный код компилируется. Ошибки компиляции в коде шаблона. |
Сразу после предыдущего шага. | Вместе с кодом приложения. |
| Выполняется код. Ошибки во время выполнения в коде шаблона. |
Сразу после предыдущего шага. | При запуске приложения и вызове кода шаблона. |
В большинстве случаев номера строк в коде шаблона задаются в отчете об ошибке. Если отчет об ошибке ссылается на временное имя файла, обычно это несогласованная скобка в коде текстового шаблона.
Точки останова можно задать в текстовых шаблонах и отладить обычным образом.
Распространенные ошибки и исправления
В следующей таблице перечислены наиболее распространенные ошибки и их исправления.
| Сообщение об ошибке | Описание | Решение |
|---|---|---|
| Не удалось загрузить базовый класс "{0}" из которого наследует класс преобразования. | Происходит, если базовый класс, указанный в параметре inherits , не указан в директиве шаблона. Сообщение предоставляет номер строки директивы шаблона. |
Убедитесь, что указанный класс существует, и что сборка, в которую она существует, указана в директиве сборки. |
| Не удалось разрешить включение текста для файла:{0} | Происходит, когда не удается найти включенный шаблон. В сообщении указано имя запрошенного файла включения. | Убедитесь, что путь к файлу относительно исходного пути шаблона или файл находится в расположении, зарегистрированном в узле, или что имеется полный путь к файлу. |
| Ошибки были созданы при инициализации объекта преобразования. Преобразование не будет выполняться. | Происходит, когда метод Initialize()класса преобразования завершился ошибкой или возвращает значение false. | Код функции Initialize() поступает из базового класса преобразования, указанного в <директиве #@template#> и от процессоров директив. Ошибка, которая вызвала сбой инициализации, вероятно, находится в списке ошибок. Изучите причину сбоя. Вы можете просмотреть фактически созданный код для Initialize(), выполнив процедуры отладки шаблона. |
| Сборка "{0}" для обработчика директив "{1}" не была предоставлена набор разрешений FullTrust. Только доверенные сборки могут предоставлять процессоры директив. Этот обработчик директив не будет загружен. | Происходит, когда система не предоставляет разрешения FullTrust сборке, содержащей обработчик директив. Сообщение содержит имя сборки и имя обработчика директив. | Убедитесь, что на локальном компьютере используются только доверенные сборки. |
| Путь "{0}" должен быть локальным для этого компьютера или частью доверенной зоны. | Происходит, когда директива или директива сборки ссылается на файл, который не находится на локальном компьютере или в доверенной зоне сети. | Убедитесь, что каталог, в котором находятся директивы или директивы сборки, находится в доверенной зоне. Вы можете добавить сетевой каталог в надежную зону через Интернет Обозреватель. |
| Несколько синтаксической ошибок, таких как "Недопустимый маркер catch" или "Пространство имен не может напрямую содержать элементы". | Слишком много закрывающих фигурных скобок в коде шаблона. Компилятор запутает его с кодом стандартного поколения. | Проверьте количество закрывающих фигурных скобок и квадратных скобок внутри разделителей кода. |
Циклы или условные условия не компилируются или не выполняются правильно. Например: <#if (i>10)#> Number is: <#= i #>.Этот код всегда выводит значение i. Только "Число равно:" является условным. |
В C#всегда используйте фигурные скобки для окружности текстовых блоков, внедренных в операторы управления. | Добавьте фигурные скобки: <#if (i>10) { #> Number is: <#= i #><# } #>. |
| Выражение слишком сложное при обработке шаблона времени разработки или компиляции шаблона среды выполнения (предварительно обработанного). Visual Studio перестает работать при попытке проверить код, созданный шаблоном среды выполнения. |
Блок текста слишком длинный. T4 преобразует текстовые блоки в выражение объединения строк с одной строкой для каждой строки шаблона. Очень длинные текстовые блоки могут преодолеть ограничения размера компилятора. | Разбиите длинный текстовый блок с блоком выражений, например:<#= "" #> |
Описания предупреждений и исправления
В следующей таблице перечислены наиболее распространенные предупреждения вместе с исправлениями, если они доступны.
| Предупреждающее сообщение | Описание | Решение |
|---|---|---|
| Загрузка файла include '{0}' возвращает пустую или пустую строку. | Происходит, если включенный текстовый файл шаблона пуст. Сообщение предоставляет имя файла включенного файла. | Удалите директиву include или убедитесь, что файл содержит некоторое содержимое. |
| Преобразование компиляции: | Добавляет эту строку ко всем ошибкам или предупреждениям, исходящим от компилятора при компиляции преобразования. Эта строка означает, что компилятор вызвал ошибку или предупреждение. | Если у вас возникла проблема с поиском библиотеки DLL, возможно, потребуется указать полный путь или полное строгое имя, если библиотека DLL находится в GAC. |
| Параметр '{0}' уже существует в директиве. Повторяющийся параметр будет игнорироваться. | Происходит при указании параметра более одного раза в директиве. Сообщение содержит имя параметра и номер строки директивы. | Удалите спецификацию повторяющихся параметров. |
| Произошла ошибка при загрузке файла включаемого файла .{0} Директива include будет игнорироваться. | Происходит, если файл, указанный в директиве include , не удается найти. Сообщение содержит имя файла и номер строки директивы. |
Убедитесь, что файл включения существует либо в том же каталоге, что и исходный текстовый файл шаблона, либо в одном из каталогов включения, зарегистрированных в узле. |
| Недопустимый базовый класс был указан для класса Преобразования. Базовый класс должен быть производным от Microsoft.VisualStudio.TextTemplating.TextTransformation. | Происходит, когда inherits параметр в директиве шаблона указывает класс, от который не наследуется TextTransformation. Сообщение предоставляет номер строки директивы шаблона. |
Укажите класс, производный от TextTransformation. |
| Недопустимый язык и региональные параметры был указан в директиве template. Язык и региональные параметры должны находиться в формате XX-XX. Будет использоваться инвариантный язык и региональные параметры. | Происходит, когда параметр языка и региональных параметров в директиве шаблона указан неправильно. Сообщение предоставляет номер строки директивы шаблона. | Измените параметр языка и региональных параметров на допустимый язык и региональные параметры в формате xx-XX. |
| Недопустимое значение отладки было{0} указано в директиве шаблона. Значение отладки должно иметь значение true или false. Будет использоваться значение по умолчанию false. | Происходит при debug неправильном указании параметра в директиве шаблона. Сообщение предоставляет номер строки директивы шаблона. |
Задайте для параметра отладки значение true или false. |
| Недопустимое значение{0} HostSpecific было указано в директиве шаблона. Значение HostSpecific должно иметь значение true или false. Будет использоваться значение по умолчанию false. | Происходит, когда параметр для конкретного узла в директиве template указан неправильно. Сообщение предоставляет номер строки директивы шаблона. |
Задайте для параметра, зависящем от узла, значение true или false. |
| Недопустимый язык "{0}" был указан в директиве "template". Язык должен быть "C#" или "VB". Будет использоваться значение по умолчанию "C#". | Происходит, когда неподдерживаемый язык указан в директиве template . Разрешены только "C#" или "VB" (не учитывается регистр). Сообщение предоставляет номер строки директивы шаблона. |
language Задайте параметр в директиве шаблона значение "C#" или "VB". |
| В шаблоне найдено несколько директив выходных данных. Все, кроме первого, будут игнорироваться. | Происходит при указании нескольких output директив в файле шаблона. Сообщение предоставляет номер строки повторяющегося выходного директивы. |
Удалите повторяющиеся output директивы. |
| В шаблоне найдено несколько директив шаблона. Все, кроме первого, будут игнорироваться. В одной директиве шаблона необходимо указать несколько параметров директивы шаблона. | Происходит при указании нескольких template директив в текстовом файле шаблона (включая включенные файлы). Сообщение предоставляет номер строки повторяющегося директивы шаблона. |
Объединяйте разные template директивы в одну template директиву. |
| Для директивы с именем '{0}' не указан обработчик. Директива будет игнорироваться. | Происходит, если указать директиву custom , но не указать processor атрибут. Сообщение содержит имя директивы и номер строки. |
processor Укажите атрибут с именем directive процессора для директивы. |
| Не удалось найти обработчик с именем '{0}' для директивы с именем '{1}'. Директива будет игнорироваться. | Происходит, когда система не может найти процессор, указанный directive в директиве custom . Сообщение содержит имя директивы, имя процессора и номер строки директивы. |
processor Задайте атрибут в директиве именем обработчика директив. |
| Обязательный параметр '{0}' для директивы '{1}' не найден. Директива будет игнорироваться. | Происходит, когда система не предоставляет обязательный параметр директивы. Сообщение содержит имя отсутствующих параметров, имя директивы и номер строки. | Укажите отсутствующий параметр. |
| Обработчик с именем '{0}' не поддерживает директиву с именем '{1}'. Директива будет игнорироваться. | Происходит, когда обработчик директив не поддерживает директиву. Сообщение предоставляет имя и номер строки директивы, а также имя обработчика директив. | Исправьте имя директивы. |
| Директива include для файла '{0}' вызывает бесконечный цикл. | Отображается, если указаны директивы циклического включения (например, файл A включает файл B, который включает файл A). | Не указывайте директивы циклического включения. |
| Выполнение преобразования: | Добавляет эту строку ко всем ошибкам или предупреждениям, созданным при выполнении преобразования. | Неприменимо. |
| Непредвиденный тег начала или конца был найден в блоке. Убедитесь, что вы не ввели неправильный тег начального или конечного тега, и что в шаблоне нет вложенных блоков. | Отображается при непредвиденном <# или #>. То есть, если у вас есть <# после другого открытого тега, который не был закрыт, или у вас есть #> , если перед ним нет незакрытого открытого тега. Сообщение предоставляет номер строки несовпадения тега. | Удалите несогласованный тег начала или конца или используйте escape-символ. |
Директива была указана в неправильном формате. Директива будет игнорироваться. Укажите директиву в формате <#@ name [parametername="parametervalue"]* #> |
Отображается средство синтаксического анализа, если директива не указана в правильном формате. Сообщение предоставляет номер строки неправильной директивы. | Убедитесь, что все директивы находятся в форме <#@ name [parametername="parametervalue"]* #>. Дополнительные сведения см. в директивах шаблона текста T4. |
| Не удалось загрузить сборку "{0}" для зарегистрированного обработчика директив "{1}" {2} |
Происходит, когда обработчик директив не может быть загружен узлом. Сообщение определяет сборку, указанную для обработчика директив, и имя обработчика директив. | Убедитесь, что обработчик директив зарегистрирован правильно и что сборка существует. |
| Не удалось найти тип '{0}' в сборке '{1}' для зарегистрированного обработчика директив '{2}' {3} |
Происходит, когда не удалось загрузить тип обработчика директив из сборки. В сообщении указано имя типа, сборки и обработчика директив. | Vshost находит сведения о обработчике директив (имя, сборка и тип) в реестре. Убедитесь, что обработчик директив зарегистрирован правильно, и что тип существует в сборке. |
| Возникла проблема с загрузкой сборки '{0}' | Возникает, когда возникает проблема с загрузкой сборки. Сообщение содержит имя сборки. | Сборки можно загружать в <директивы @#assembly#> и процессорами директив. Сообщение об ошибке, следующее за этой строкой, должно предоставить дополнительные данные о том, почему сбой загрузки сборки. |
| Возникла проблема при создании и инициализации процессора для директивы с именем '{1}'. Тип процессора .{0} Директива будет игнорироваться. | Происходит, когда система не могла создать или инициализировать обработчик директив. Сообщение содержит имя и номер строки директивы и тип процессора. | Убедитесь, что используется правильный процессор директив и что обработчик директив имеет общедоступный конструктор по умолчанию. В противном случае используйте параметры отладки, чтобы узнать, почему метод Initialize() обработчика директив завершается сбоем. Дополнительные сведения см. в разделе "Устранение неполадок с текстовыми шаблонами". |
| Исключение было создано при обработке директивы с именем '{0}'. | Происходит, когда обработчик директив создает исключение при обработке директивы. | Убедитесь, что параметры обработчика директив верны. |
| Узел вызвал исключение при попытке разрешить ссылку на сборку "{0}". | Возникает, когда узел создает исключение при попытке устранить ссылку на сборку. Сообщение предоставляет строку ссылки на сборку. | Ссылки на сборки приходят из директив @#assembly#> и из <процессоров директив. Убедитесь, что параметр name, указанный в параметре сборки, является правильным. |
| Попытка указать неподдерживаемое {1} значение '{0}' для директивы {2} | Происходит с помощью RequiresProvidesDirectiveProcessor (все созданные процессоры директив наследуются от него), когда вы предоставляете неподдерживаемый аргумент или предоставляет аргумент. | Убедитесь, что имена пар name='value', указанные в необходимых параметрах, и предоставляет правильные параметры. |