$Id: DevelopersGuide.txt 279 2006-12-11 22:43:40Z iko $ Developer's Guide for http://msbuildtasks.tigris.org/ ===================================================== Build Environment Prerequisites ------------------------------ - .NET2.0 - MSBuild; typically already installed as part of .NET2.0, for example in C:\WINDOWS\Microsoft.NET\Framework\v2.0.50727\MSBuild.exe - NUnit 2.2.X (http://www.nunit.org/); necessary to run the tests - Microsoft Visual SourceSafe(R) 2005; the library Microsoft.VisualStudio.SourceSafe.Interop gets referenced - NDoc 1.3 (http://ndoc.sourceforge.net/) additionally configure NDoc to use .NET2; see http://ndoc.sourceforge.net/wiki/dotNet_2.0_Support - Microsoft Visual Studio 2005 as IDE Optional Services ----------------- - Subversion client (http://subversion.tigris.org/); typically in C:\Program Files\Subversion - IIS - Email - ILMerge (http://research.microsoft.com/~mbarnett/ILMerge.aspx) - FxCop (http://www.gotdotnet.com/Team/FxCop/) Before writing your own task ---------------------------- 1. Checkout/Update the svn repository http://msbuildtasks.tigris.org/svn/msbuildtasks/trunk with your tigris user/password to a local working copy of your choice. 2. Check that you can build the project on the command line: ** Important ** You must run the build from the command line before attempting to open the Visual Studio solution file, in order to create some required files. - Add the directory of MSBuild.exe to your PATH environment variable, e.g. C:\WINDOWS\Microsoft.NET\Framework\v2.0.50727. - Open cmd.exe in the top directory of the local working copy where MSBuildTasks.proj is located. - Run "msbuild MSBuildTasks.proj"; the default target "build" is executed and should yield "Build succeeded". - Run "msbuild MSBuildTasks.proj /p:devel=true /p:nunitpath=c:\tools\nunit\bin /t:test" to run the NUnit test suite; "Build succeeded." indicates that the tests have been executed successfully. /p:devel=true is necessary when you want to work with the assemblies of your own build, for example because you did not run the installer of MSBuildCommunityTasks yet. /p:nunitpath must point to the bin folder of your local installation of NUnit 2.2.x - Open \Debug\test\TestReport.html and check the test results. Tests must be either successful or ignored because an optional service such as FTP server or Email server is missing on your machine. 3. Check that you can build the project in VS2005: - Open \Source\MSBuild.Community.Tasks.sln. - Set MSBuild.Community.Tasks.Tests as startup project. - Open the properties of MSBuild.Community.Tasks.Tests; in Debug/Start Action, set the external program to NUnit, e.g. "C:\Program Files\NUnit 2.2.5\bin\nunit-gui.exe"; in Debug/Start Options, set command line arguments to "MSBuild.Community.Tasks.Tests.dll". - If you work with another version of NUnit, it may be necessary to the NUnit library from your NUnit's installation folder to \Libaries\NUnit\\nunit.framework.dll and to re-import it to the test project. - Run the project in debugging mode (F5); NUnit starts up with the test suite; Tests can be executed in interaction with the debugger (breakpoints etc.) Writing your own task ---------------------- 1. Add a folder \Source\MSBuild.Community.Task\ and place .cs and related files in there; always add a folder, even if you want to add just one file. 2. Add third party libraries that you are allowed to redistribute to \Libraries\\\ (e.g. \Libraries\NUnit\2.2.5\nunit.framework.dll). 3. For third party libraries that you are not allowed to redistribute, add an entry in the prerequisits section of this document together with information where to get it. 4. Implement your task - Insert the character sequence '$', 'Id', '$' (not concatenated here to avoid expansion by svn in this text itself) somewhere in the fileheader comment. - When adding source files to the repository, set the metadata "svn:keywords" to "Id". From the command line: svn ps svn:keywords "Id" myNewTask.cs With TortoiseSVN: Right-click the myNewTask.cs in Explorer, choose Properties, change to Subversion tab, choose svn-keywords from dropdown in Properties section, enter "Id" in the text box, and press the Set button. - Avoid Console.WriteLine, use Log.LogMessage instead. - For log messages in your task, use resource strings instead of hard coded strings, e.g. "Log.LogError(Properties.Resources.XsltNoInputFiles);". - Recommended Tab width is 4. 5. For your NUnit tests, add a folder \Source\MSBuild.Community.Task.Test\ and place Test.cs, Test.proj and related files in there; always add a folder, even if you want to add just one file. 6. Implement NUnit tests for your task in Test.cs; this is important to have something for debugging. - Provide a description to every test, e.g. [Test(Description = "Test the weather forecast task in rainy season")]. - From within your NUnit test, check for the availability of an optional service that your task depends on (such as FTP, IIS, Email); when not available, it's good style to Assert.Ignore(" test needs to be executed") instead of having the test just fail. - Also for optional services that a test depends on, it's good style to have server access data such as URLs, logins and paths located in a config file rather than hard coded in the test code. 7. Add an entry to \Source\MSBuild.Community.Tasks\MSBuild.Community.Tasks.Targets 8. Implement Test.proj and add an entry in MSBuildTasks.proj so that it gets executed as part of the "test-proj" target there; this is important to test and demonstrate your task in action. - It's good style to have tests work only below \Build\\test\\ and to avoid having them creating any folders or files in the source tree below \Source\ - If your test depend on an optional service or tool, it's good style to have the test skipped by default and to provide an extra switch like "/p:withILMerge=true" to execute the test. 9. Test your task - Run NUnit test interactively. - Run NUnit test on the command line. - Run "msbuild MSBuildTasks.proj /p:devel=true /p:nunitpath=c:\tools\nunit\bin /t:test", which should include calling Test.proj 10. Document your task - Provide all xml code comments for your task (no need to do so for private members and for NUnit test code). - Provide an section in the xml code comment of your task class. - Make an entry for your task in \Documentation\Overview.html 11. Before commiting your task, - run "msbuild MSBuildTasks.proj /p:configuration=Release", which treats warnings as errors. - run "msbuild Master.proj" to validate the nightly build still works. You can also verify the documentation for your task was included correctly in Documentation\MSBuild.Community.Tasks.chm