Запуск скриптов Windows PowerShell из файлов проекта MSBuild Running Windows PowerShell Scripts from MSBuild Project Files

В этом разделе описывается, как запустить сценарий Windows PowerShell как часть процесса сборки и развертывания. This topic describes how to run a Windows PowerShell script as part of a build and deployment process. Скрипт можно запустить локально (иными словами, на сервере сборки) или удаленно, например на целевом веб-сервере или сервере базы данных. You can run a script locally (in other words, on the build server) or remotely, like on a destination web server or database server.

Существует множество причин, по которым может потребоваться выполнить сценарий Windows PowerShell, выполняемый после развертывания. There are lots of reasons why you might want to run a post-deployment Windows PowerShell script. Например, может понадобиться: For example, you might want to:

• Добавьте в реестр пользовательский источник событий. Add a custom event source to the registry.
• Создает каталог файловой системы для отправки. Generate a file system directory for uploads.
• Очистка каталогов сборки. Clean up build directories.
• Запись записей в пользовательский файл журнала. Write entries to a custom log file.
• Отправка сообщений электронной почты, приглашающих пользователей в недавно подготовленное веб-приложение. Send emails inviting users to a newly provisioned web application.
• Создайте учетные записи пользователей с соответствующими разрешениями. Create user accounts with the appropriate permissions.
• Настройте репликацию между экземплярами SQL Server. Configure replication between SQL Server instances.

В этом разделе показано, как запускать сценарии Windows PowerShell как локально, так и удаленно из пользовательского целевого объекта в файле проекта Microsoft Build Engine (MSBuild). This topic will show you how to run Windows PowerShell scripts both locally and remotely from a custom target in a Microsoft Build Engine (MSBuild) project file.

Этот раздел является частью серии руководств, основанных на требованиях Enterprise к развертыванию вымышленной компании Fabrikam, Inc. В этой серии руководств используется пример решения— диспетчера контактов—для представления веб-приложения с реалистичным уровнем сложности, включая приложение ASP.NET MVC 3, службу Windows Communication Foundation (WCF) и проект базы данных. This topic forms part of a series of tutorials based around the enterprise deployment requirements of a fictional company named Fabrikam, Inc. This tutorial series uses a sample solution—the Contact Manager solution—to represent a web application with a realistic level of complexity, including an ASP.NET MVC 3 application, a Windows Communication Foundation (WCF) service, and a database project.

Метод развертывания в сердце этих учебников основан на подходе к файлам проекта Split, описанному в разделе понимание файла проекта, в котором процесс сборки управляется двумя файлами—проекта, содержащими инструкции по сборке, которые применяются к каждой целевой среде, и одна содержит параметры сборки и развертывания, относящиеся к конкретной среде. The deployment method at the heart of these tutorials is based on the split project file approach described in Understanding the Project File, in which the build process is controlled by two project files—one containing build instructions that apply to every destination environment, and one containing environment-specific build and deployment settings. Во время сборки файл проекта, зависящий от среды, объединяется в файл проекта независимо от среды, чтобы сформировать полный набор инструкций по сборке. At build time, the environment-specific project file is merged into the environment-agnostic project file to form a complete set of build instructions.

Обзор задач Task Overview

Чтобы запустить сценарий Windows PowerShell в рамках автоматизированного или одноэтапного развертывания, необходимо выполнить следующие задачи высокого уровня: To run a Windows PowerShell script as part of an automated or single-step deployment process, you’ll need to complete these high-level tasks:

• Добавьте сценарий Windows PowerShell в решение и в систему управления версиями. Add the Windows PowerShell script to your solution and to source control.
• Создайте команду, вызывающую скрипт Windows PowerShell. Create a command that invokes your Windows PowerShell script.
• Экранирование всех зарезервированных символов XML в команде. Escape any reserved XML characters in your command.
• Создайте целевой объект в пользовательском файле проекта MSBuild и используйте задачу exec для выполнения команды. Create a target in your custom MSBuild project file and use the Exec task to run your command.

В этом разделе будет показано, как выполнять эти процедуры. This topic will show you how to perform these procedures. В задачах и пошаговых руководствах этого раздела предполагается, что вы уже знакомы с целями и свойствами MSBuild и знаете, как использовать пользовательский файл проекта MSBuild для создания процесса сборки и развертывания. The tasks and walkthroughs in this topic assume that you’re already familiar with MSBuild targets and properties, and that you understand how to use a custom MSBuild project file to drive a build and deployment process. Дополнительные сведения см. в разделе понимание файла проекта и понимание процесса сборки. For more information, see Understanding the Project File and Understanding the Build Process.

Создание и добавление сценариев Windows PowerShell Creating and Adding Windows PowerShell Scripts

В задачах этого раздела используется пример сценария Windows PowerShell с именем логдеплой. ps1 , иллюстрирующий запуск скриптов из MSBuild. The tasks in this topic use a sample Windows PowerShell script named LogDeploy.ps1 to illustrate how to run scripts from MSBuild. Сценарий логдеплой. ps1 содержит простую функцию, которая записывает однострочную запись в файл журнала: The LogDeploy.ps1 script contains a simple function that writes a single-line entry to a log file:

Сценарий логдеплой. ps1 принимает два параметра. The LogDeploy.ps1 script accepts two parameters. Первый параметр представляет полный путь к файлу журнала, в который необходимо добавить запись, а второй параметр представляет целевое место развертывания, которое необходимо записать в файл журнала. The first parameter represents the full path to the log file to which you want to add an entry, and the second parameter represents the deployment destination that you want to record in the log file. При выполнении скрипта в файл журнала добавляется строка в следующем формате: When you run the script, it adds a line to the log file in this format:

Чтобы сделать скрипт логдеплой. ps1 доступным для MSBuild, необходимо выполнить следующие действия: To make the LogDeploy.ps1 script available to MSBuild, you need to:

• Добавьте скрипт в систему управления версиями. Add the script to source control.
• Добавьте скрипт в решение в Visual Studio 2010. Add the script to your solution in Visual Studio 2010.

Вам не нужно развертывать скрипт вместе с содержимым решения независимо от того, планируется ли запускать сценарий на сервере сборки или на удаленном компьютере. You don’t need to deploy the script with your solution content, regardless of whether you plan to run the script on the build server or on a remote computer. Один из вариантов — добавить скрипт в папку решения. One option is to add the script to a solution folder. В примере диспетчера контактов, поскольку вы хотите использовать сценарий Windows PowerShell в рамках процесса развертывания, имеет смысл добавить скрипт в папку публикации решения. In the Contact Manager example, because you want to use the Windows PowerShell script as part of the deployment process, it makes sense to add the script to the Publish solution folder.

Содержимое папок решений копируется на серверы сборки в качестве исходных материалов. The contents of solution folders are copied to build servers as source material. Однако они не являются частью выходных данных проекта. However, they form no part of any project output.

Выполнение скрипта Windows PowerShell на сервере сборки Executing a Windows PowerShell Script on the Build Server

В некоторых сценариях может потребоваться запустить сценарии Windows PowerShell на компьютере, который выполняет сборку проектов. In some scenarios, you may want to run Windows PowerShell scripts on the computer that builds your projects. Например, сценарий Windows PowerShell можно использовать для очистки папок сборки или записи в пользовательский файл журнала. For example, you might use a Windows PowerShell script to clean up build folders or write entries to a custom log file.

С точки зрения синтаксиса запуск скрипта Windows PowerShell из файла проекта MSBuild аналогичен запуску сценария Windows PowerShell из обычной командной строки. In terms of syntax, running a Windows PowerShell script from an MSBuild project file is the same as running a Windows PowerShell script from a regular command prompt. Необходимо вызвать исполняемый файл PowerShell. exe и использовать параметр – Command для предоставления команд, которые должны запускаться с помощью Windows PowerShell. You need to invoke the powershell.exe executable and use the –command switch to provide the commands you want Windows PowerShell to run. (В Windows PowerShell версии 2 можно также использовать параметр – File ). (In Windows PowerShell v2, you can also use the –file switch). Команда должна иметь следующий формат: The command should take this format:

Пример: For example:

Если путь к скрипту содержит пробелы, необходимо заключить путь к файлу в одинарные кавычки перед амперсандом. If the path to your script includes spaces, you need to enclose the file path in single quotes preceded by an ampersand. Нельзя использовать двойные кавычки, так как они уже используются для заключения команды: You can’t use double quotes, because you’ve already used them to enclose the command:

При вызове этой команды из MSBuild необходимо учитывать несколько дополнительных вопросов. There are a few additional considerations when you invoke this command from MSBuild. Во-первых, следует включить флаг – Неинтерактивный , чтобы обеспечить беззвучное выполнение скрипта. First, you should include the –NonInteractive flag to ensure that the script executes quietly. Далее следует включить флаг – ExecutionPolicy с соответствующим значением аргумента. Next, you should include the –ExecutionPolicy flag with an appropriate argument value. Это указывает политику выполнения, которую Windows PowerShell будет применять к сценарию, и позволяет переопределить политику выполнения по умолчанию, которая может препятствовать выполнению скрипта. This specifies the execution policy that Windows PowerShell will apply to your script and allows you to override the default execution policy, which may prevent execution of your script. Можно выбрать одно из следующих значений аргумента: You can choose from these argument values:

• Неограниченное значение позволяет Windows PowerShell выполнять скрипт независимо от того, подписан ли сценарий. A value of Unrestricted will allow Windows PowerShell to execute your script, regardless of whether the script is signed.
• Значение RemoteSigned позволит Windows PowerShell выполнять неподписанные сценарии, созданные на локальном компьютере. A value of RemoteSigned will allow Windows PowerShell to execute unsigned scripts that were created on the local machine. Однако скрипты, созданные в других местах, должны быть подписаны. However, scripts that were created elsewhere must be signed. (На практике вы вряд ли создадите сценарий Windows PowerShell локально на сервере сборки). (In practice, you’re very unlikely to have created a Windows PowerShell script locally on a build server).
• Значение AllSigned позволит Windows PowerShell выполнять только подписанные сценарии. A value of AllSigned will allow Windows PowerShell to execute signed scripts only.

Политика выполнения по умолчанию ограничена, что запрещает Windows PowerShell выполнять какие-либо файлы скриптов. The default execution policy is Restricted, which prevents Windows PowerShell from running any script files.

Наконец, необходимо экранировать все зарезервированные символы XML, которые происходят в команде Windows PowerShell: Finally, you need to escape any reserved XML characters that occur in your Windows PowerShell command:

Замените одинарные кавычки на ‘ Replace single quotes with ‘

Замените двойные кавычки на « Replace double quotes with «

Замена амперсандов на & Replace ampersands with &

При внесении этих изменений команда будет выглядеть примерно так: When you make these changes, your command will resemble this:

В файле пользовательского проекта MSBuild можно создать новый целевой объект и выполнить следующую команду с помощью задачи exec : Within your custom MSBuild project file, you can create a new target and use the Exec task to run this command:

В этом примере обратите внимание на следующее: In this example, note that:

• Любые переменные, такие как значения параметров и расположение исполняемого файла Windows PowerShell, объявляются как свойства MSBuild. Any variables, like parameter values and the location of the Windows PowerShell executable, are declared as MSBuild properties.
• Условия включены, чтобы разрешить пользователям переопределять эти значения из командной строки. Conditions are included to enable users to override these values from the command line.
• Свойство мсдеплойкомпутернаме объявлено в любом расположении файла проекта. The MSDeployComputerName property is declared elsewhere in the project file.

При выполнении этого целевого объекта в рамках процесса сборки Windows PowerShell выполнит команду и запишет запись журнала в указанный файл. When you execute this target as part of your build process, Windows PowerShell will run your command and write a log entry to the file you specified.

Выполнение сценария Windows PowerShell на удаленном компьютере Executing a Windows PowerShell Script on a Remote Computer

Windows PowerShell может выполнять сценарии на удаленных компьютерах с помощью Служба удаленного управления Windows (WinRM). Windows PowerShell is capable of running scripts on remote computers through Windows Remote Management (WinRM). Для этого необходимо использовать командлет Invoke-Command . To do this, you need to use the Invoke-Command cmdlet. Это позволяет выполнить сценарий на одном или нескольких удаленных компьютерах без копирования сценария на удаленные компьютеры. This lets you execute your script against one or more remote computers without copying the script to the remote computers. Все результаты возвращаются на локальный компьютер, с которого был выполнен сценарий. Any results are returned to the local computer from which you ran the script.

Перед использованием командлета Invoke-Command для выполнения сценариев Windows PowerShell на удаленном компьютере необходимо настроить прослушиватель WinRM для приема удаленных сообщений. Before you use the Invoke-Command cmdlet to execute Windows PowerShell scripts on a remote computer, you need to configure a WinRM listener to accept remote messages. Это можно сделать, выполнив команду winrm quickconfig на удаленном компьютере. You can do this by running the command winrm quickconfig on the remote computer. Дополнительные сведения см. в разделе Установка и настройка для служба удаленного управления Windows. For more information, see Installation and Configuration for Windows Remote Management.

В окне Windows PowerShell этот синтаксис используется для запуска сценария логдеплой. ps1 на удаленном компьютере: From a Windows PowerShell window, you’d use this syntax to run the LogDeploy.ps1 script on a remote computer:

Существует несколько других способов использования командлета Invoke-Command для запуска файла скрипта, но этот подход является наиболее простым, если необходимо указать значения параметров и управлять путями с пробелами. There are various other ways of using Invoke-Command to run a script file, but this approach is the most straightforward when you need to provide parameter values and manage paths with spaces.

При запуске из командной строки необходимо вызвать исполняемый файл Windows PowerShell и использовать параметр – Command для указания инструкций: When you run this from a command prompt, you need to invoke the Windows PowerShell executable and use the –command parameter to provide your instructions:

Как и ранее, при выполнении команды из MSBuild необходимо указать некоторые дополнительные параметры и экранировать все зарезервированные символы XML: As before, you need to provide some additional switches and escape any reserved XML characters when you run the command from MSBuild:

Наконец, как и раньше, можно использовать задачу exec в настраиваемом целевом объекте MSBuild для выполнения команды: Finally, as before, you can use the Exec task within a custom MSBuild target to execute your command:

При выполнении этого целевого объекта в рамках процесса сборки Windows PowerShell запустит сценарий на компьютере, указанном в аргументе – ComputerName . When you execute this target as part of your build process, Windows PowerShell will run your script on the computer you specified in the –computername argument.

Заключение Conclusion

В этом разделе описано, как запустить сценарий Windows PowerShell из файла проекта MSBuild. This topic described how to run a Windows PowerShell script from an MSBuild project file. Этот подход можно использовать для запуска сценария Windows PowerShell либо локально, либо на удаленном компьютере в рамках автоматизированного или одноэтапного процесса сборки и развертывания. You can use this approach to run a Windows PowerShell script, either locally or on a remote computer, as part of an automated or single-step build and deployment process.

Дополнительные материалы Further Reading

Рекомендации по подписыванию сценариев Windows PowerShell и управлению политиками выполнения см. в разделе выполнение сценариев Windows PowerShell. For guidance on signing Windows PowerShell scripts and managing execution policies, see Running Windows PowerShell Scripts. Рекомендации по запуску команд Windows PowerShell с удаленного компьютера см. в разделе выполнение удаленных команд. For guidance on running Windows PowerShell commands from a remote computer, see Running Remote Commands.

Дополнительные сведения об использовании пользовательских файлов проекта MSBuild для управления процессом развертывания см. в разделе Основные сведения о файле проекта и понимании процесса сборки. For more information on using custom MSBuild project files to control the deployment process, see Understanding the Project File and Understanding the Build Process.