I've been using Sandcastle Help File Builder for a while to generate documentation - I'm now trying to get it to be part of our build process. Our build is controlled using NAnt, and each time it's built the output gets sent to a different location (based on changeset numbers, so we can have concurrent builds without clashes) - ie the dlls are not in a fixed path relative to the source code.
I've added a target into the NAnt script to call SHFB, which invokes the msbuild task, pointing at the solution that contains the SHFB project:
<target name="GenerateDocumentation">
<msbuild
project="${SourceURL}\Documentation\API Documentation\APIs.sln"
verbosity="Detailed">
<property name="OutputPath" value="${OutputPath}Documentation" />
<property name="ReferencePath" value="${OutputPath}wwwroot\\bin\\" />
</msbuild>
</target>
I've specified the ReferencePath property, as on this page, it seems to indicate that this would allow SHFB to find the assemblies and use them, rather than relying on the information in the original project file:
If the ReferencePath property is defined, it will be passed to and used by GenerateRefInfo.proj when generating reflection information. This allows you to specify an alternate path in which to find reference assemblies that will override hint paths in the project file.
However when the build reaches this point, it fails with the following error:
SHFB: Error BE0040: Project assembly does not exist: D:\Build\Debug\wwwroot\bin\MyAssembly.dll
Which is the default output path specified in the original project.
What is the correct mechanism for passing the location of the assemblies into SHFB?
Turns out that using OutDir instead of ReferencePath is the way to go:
<target name="GenerateDocumentation">
<msbuild
project="${SourceURL}\Documentation\API Documentation\APIs.sln"
verbosity="Detailed">
<property name="OutputPath" value="${OutputPath}Documentation" />
<property name="OutDir" value="${OutputPath}wwwroot\bin\\" />
</msbuild>
</target>
Also note that the path specified in OutDir must end in a double slash, otherwise MSBuild attempts to concatenate it with the project path
Related
I'm using MSBuild SDK style projects with VS 2019. I'm trying to run a custom file generation tool which depends on the output of the build of the current project. The files should be treated as if it was regular content for which CopyToOutputDirectory is set. In dependent projects I expect the files to be part of the output directory as well. The solution I now have works, but not from clean builds, which is obviously not acceptable.
I currently have this in the project file:
<Target Name="Generation" AfterTargets="AfterBuild">
<Exec Command="GeneratedFiles" />
<ItemGroup>
<Content Include="$(TargetDir)\GeneratedFiles.*.xml">
<TargetPath>GeneratedFiles\%(Filename)%(Extension)</TargetPath>
<CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
</Content>
</ItemGroup>
</Target>
This works, but only for non-clean builds.
The reason the Generation target doesn't work is because the logic that performs the copies, based on the presence and value of the CopyToOutputDirectory metadata, runs as part of the 'CoreBuild'. The Generation target has AfterTargets="AfterBuild". It runs after the build (and the copying) has already been completed.
The Generation target doesn't work for the first build and it doesn't work for subsequent incremental builds either.
The question description says that the files are copied for an incremental build. While it may be true that the files are copied, they can't be getting copied because of the Generation target. Without seeing the complete project file, I assume there is another place in the project where the CopyToOutputDirectory metadata is being set for the files.
To have the Generation target run after compilation and before files are copied, the following can be used:
<Target Name="Generation" AfterTargets="AfterCompile" BeforeTargets="GetCopyFilesToOutputDirectoryItems">
The GetCopyFilesToOutputDirectoryItems is publicly documented and it runs before another publicly documented target named CopyFilesToOutputDirectory. The CopyFilesToOutputDirectory is defined with a DependsOnTargets attribute which runs a set of targets that perform the actually copying. This means that the file copies are completed before the CopyFilesToOutputDirectory target is completed.
To ensure the correct order, BeforeTargets="GetCopyFilesToOutputDirectoryItems" is used and not BeforeTargets="CopyFilesToOutputDirectory".
If the scenario were different and <Exec Command="GeneratedFiles" /> didn't depend on the compilation step, i.e. the GeneratedFiles command didn't use the assembly being created by the project, then the Generation target could occur even earlier, e.g.
<Target Name="Generation" BeforeTargets="BeforeBuild">
Update - Execute a Target if ProjectReference has a specific Project
This update is a response to discussion in the comments.
Let's say we have a FooApp project and a BarLib project and FooApp depends on BarLib and needs to copy arbitrary files from the BarLib project directory.
FooApp has a ProjectReference to BarLib, e.g.
<ItemGroup>
<ProjectReference Include="..\BarLib\BarLib.csproj" />
</ItemGroup>
ProjectReference is an ItemGroup and we can check if it includes BarLib.
<Target Name="CopyFilesFromBar" BeforeTargets="BeforeBuild">
<PropertyGroup>
<!-- The name of the project to look for -->
<BarProjectName>BarLib</BarProjectName>
<!-- Use batching to check the ItemGroup -->
<!-- Save the project's directory because we will need it later -->
<BarProjectDirectory Condition="'%(ProjectReference.Filename)' == '$(BarProjectName)'">%(ProjectReference.Directory)</BarProjectDirectory>
<!-- Set up a boolean that indicates if the project was found or not -->
<HasProjectRefToBar>false</HasProjectRefToBar>
<HasProjectRefToBar Condition="$(FooProjectDirectory) != ''">true</HasProjectRefToBar>
</PropertyGroup>
<!-- Copy if the project was found in ProjectReference -->
<Copy SourceFiles="$(TargetDir)$(BarProjectDirectory)\bin\GeneratedFiles\*.*" DestinationFolder="$(OutputPath)GeneratedFiles" Condition="$(HasProjectRefToBar)" />
</Target>
This target could be defined once in a Directory.Build.targets file and shared across a solution.
If the generated files (in BarLib in the example scenario) don't change based on Configuration and Platform, consider using an output path location that doesn't change as in the example - 'bin\GeneratedFiles'. This makes it much easier for consuming projects. Otherwise keep all the projects in sync with regards to using the same Configuration and Platform values and the same $(OutputPath).
I need project to be built into folder:
\bin\Debug 1.0.3.4
Where 1.0.3.4 is a current building assembly version specified in assembly: AssemblyVersion attribute.
I tried using different variables like $(AssemblyVersion), GetAssemblyIdentity task but had no luck.. I'm not so good at using MSBuild.
A quick and dirty solution to this is to, after the build, use GetAssemblyIdentity to extract the version info and then move the $(TargetFile) to the appropriate directory.
This assumes you don't have any dependencies going on. Otherwise, you'll need to modify the $(TargetPath), $(TargetName), and $(TargetExt) or go with the "proper" way of doing it - modifying $(OutputPath) dynamically.
<Target Name="AfterBuild" AfterTargets="Build">
<GetAssemblyIdentity AssemblyFiles="$(TargetPath)">
<Output TaskParameter="Assemblies" ItemName="AssemblyIdentity"/>
</GetAssemblyIdentity>
<PropertyGroup>
<Version>#(AssemblyIdentity->'%(Version)')</Version>
</PropertyGroup>
<Copy SourceFiles="$(TargetPath)" DestinationFolder="$(OutDir)$(Version)" />
</Target>
The proper way would be to modify $(OutDir) aka $(OutputPath), but that would involve things like modifying the AssemblyVersion.cs file (or more complexly, a copy of it injected automatically into the build chain).
You could also instead parse the version from the AssemblyVersion.cs file.
Solution1.sln contains two projects:
ProjectA.csproj
ProjectB.csproj
ProjectB has a custom target called "Foo". I want to run:
msbuild Solution1.sln /t:Foo
This will fail because ProjectA doesn't define the "Foo" target.
Is there a way to make the solution ignore the missing target? (E.g., do nothing if the target doesn't exist for a specific project) without modifying the SLN or project files?
There is a two-part solution if you don't want to edit the solution or project files and you're happy for it to work from MSBuild command-line but not from Visual Studio.
Firstly, the error you get when you run:
MSBuild Solution1.sln /t:Foo
Is not that ProjectA does not contain a Foo target but that the solution itself does not contain a Foo target. As #Jaykul suggests, setting the MSBuildEmitSolution environment variable will reveal the default targets contained within the solution metaproj.
Using the metaproj as inspiration you can introduce a new file "before.Solution1.sln.targets" next to the solution file (the file name pattern is important) with contents like this:
<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
<Target Name="Foo">
<MSBuild Projects="#(ProjectReference)" Targets="Foo" BuildInParallel="True" Properties="CurrentSolutionConfigurationContents=$(CurrentSolutionConfigurationContents); SolutionDir=$(SolutionDir); SolutionExt=$(SolutionExt); SolutionFileName=$(SolutionFileName); SolutionName=$(SolutionName); SolutionPath=$(SolutionPath)" SkipNonexistentProjects="%(ProjectReference.SkipNonexistentProjects)" />
</Target>
</Project>
The MSBuild element is mostly just copied from the solution metaproj's Publish target. Adjust the target name and any other details to suit your scenario.
With this file in place, you'll now get the error that ProjectA does not contain the Foo target. ProjectB may or may not build anyway depending on inter-project dependencies.
So, secondly, to solve this problem we need to give every project an empty Foo target which is then overridden in projects that actually already contain one.
We do this by introducing another file, eg "EmptyFoo.targets" (name not important) that looks like this:
<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
<Target Name="Foo" />
</Project>
And then we get every project to automatically import this targets file either by running MSBuild with an extra property, eg:
MSBuild Solution1.sln /t:Foo /p:CustomBeforeMicrosoftCommonTargets=c:\full_path_to\EmptyFoo.targets
Or include the CustomerBeforeMicrosoftCommonTargets property in the Properties attribute on the MSBuild element in the first targets file where you could optionally specify the full path relative to the $(SolutionDir) property.
However, if you're willing to run Foo in conjunction with any of the default solution targets (ie Build, Rebuild, Clean, or Publish) you could take some inspiration for how the Web Publishing Pipeline in MSBuild uses the DeployOnBuild property to call the Publish target on Web projects in a solution containing other project types that don't support publishing.
More info on the before.Solution1.sln.targets file here:
http://sedodream.com/2010/10/22/MSBuildExtendingTheSolutionBuild.aspx
You can target those by project name, like /t:project:target (might need quotes, I can't remember).
You can find all the generated targets by setting the environment variable MSBuildEmitSolution = 1 ... which causes msbuild to save to disk the temp .metaproj file which it generates for your solution. That file has all those targets defined in it, just open it up and take a look ;)
Maybe not the best answer but a reasonable hack.
msbuild ProjectA.csproj
msbuild ProjectB.csproj /t:Foo
When msbuild building solution - msbuild emits only limited set of targets into it's .metaproj file, and afaik - you can't build custom target through building sln file, you have to use original project1.csproj or custom build script.
Just for reference:
Use ContinueOnError when using MSBuildTask or -p:ContinueOnError=ErrorAndContinue when using (dotnet) msbuild
It may be in limited scenarios helpful: For example you have a list of .csproj files and want attach metadata only to specific project file items then you could write something like this:
<Target Name="UniqueTargetName" Condition="'$(PackAsExecutable)' == 'Package' Or '$(PackAsExecutable)' == 'Publish'" Outputs="#(_Hello)">
<ItemGroup>
<_Hello Include="$(MSBuildProjectFullPath)" />
</ItemGroup>
</Target>
<Target Name="BuildEachTargetFramework" DependsOnTargets="_GetTargetFrameworksOutput;AssignProjectConfiguration;_SplitProjectReferencesByFileExistence"
Condition="$(ExecutableProjectFullPath) != ''">
<Message Text="[$(MSBuildThisFilename)] Target BuildEachTargetFramework %(_MSBuildProjectReferenceExistent.Identity)" Importance="high" />
<MSBuild
Projects="%(ProjectReferenceWithConfiguration.Identity)"
Targets="UniqueTargetName"
ContinueOnError="true">
<Output TaskParameter="TargetOutputs" ItemName="_Hallo2" />
</MSBuild>
<Message Text="[$(MSBuildThisFilename)] ########### HELLO %(_Hallo2.Identity)" Importance="high" />
</Target>
I want to profile and tweak our build hoping to save few seconds here and there. I was able to create a task that derives from ResolveAssemblyReferences and use it instead, but I'm having problems in understanding the following (from Microsoft.Common.targets):
<!--
============================================================
ResolveProjectReferences
Build referenced projects:
[IN]
#(NonVCProjectReference) - The list of non-VC project references.
[OUT]
#(_ResolvedProjectReferencePaths) - Paths to referenced projects.
============================================================
-->
<Target
Name="ResolveProjectReferences"
DependsOnTargets="SplitProjectReferencesByType;_SplitProjectReferencesByFileExistence">
<!--
When building this project from the IDE or when building a .SLN from the command-line,
just gather the referenced build outputs. The code that builds the .SLN will already have
built the project, so there's no need to do it again here.
The ContinueOnError setting is here so that, during project load, as
much information as possible will be passed to the compilers.
-->
<MSBuild
Projects="#(_MSBuildProjectReferenceExistent)"
Targets="GetTargetPath"
BuildInParallel="$(BuildInParallel)"
UnloadProjectsOnCompletion="$(UnloadProjectsOnCompletion)"
Properties="%(_MSBuildProjectReferenceExistent.SetConfiguration); %(_MSBuildProjectReferenceExistent.SetPlatform)"
Condition="'#(NonVCProjectReference)'!='' and ('$(BuildingSolutionFile)' == 'true' or '$(BuildingInsideVisualStudio)' == 'true' or '$(BuildProjectReferences)' != 'true') and '#(_MSBuildProjectReferenceExistent)' != ''"
ContinueOnError="!$(BuildingProject)">
<Output TaskParameter="TargetOutputs" ItemName="_ResolvedProjectReferencePaths"/>
</MSBuild>
<!--
Build referenced projects when building from the command line.
The $(ProjectReferenceBuildTargets) will normally be blank so that the project's default
target is used during a P2P reference. However if a custom build process requires that
the referenced project has a different target to build it can be specified.
-->
<MSBuild
Projects="#(_MSBuildProjectReferenceExistent)"
Targets="$(ProjectReferenceBuildTargets)"
BuildInParallel="$(BuildInParallel)"
UnloadProjectsOnCompletion="$(UnloadProjectsOnCompletion)"
Condition="'#(NonVCProjectReference)'!='' and '$(BuildingInsideVisualStudio)' != 'true' and '$(BuildingSolutionFile)' != 'true' and '$(BuildProjectReferences)' == 'true' and '#(_MSBuildProjectReferenceExistent)' != ''">
<Output TaskParameter="TargetOutputs" ItemName="_ResolvedProjectReferencePaths"/>
</MSBuild>
<!--
Get manifest items from the (non-exe) built project references (to feed them into ResolveNativeReference).
-->
<MSBuild
Projects="#(_MSBuildProjectReferenceExistent)"
Targets="GetNativeManifest"
BuildInParallel="$(BuildInParallel)"
UnloadProjectsOnCompletion="$(UnloadProjectsOnCompletion)"
Properties="%(_MSBuildProjectReferenceExistent.SetConfiguration); %(_MSBuildProjectReferenceExistent.SetPlatform)"
Condition="'#(NonVCProjectReference)'!='' and '$(BuildingProject)'=='true' and '#(_MSBuildProjectReferenceExistent)'!=''">
<Output TaskParameter="TargetOutputs" ItemName="NativeReference"/>
</MSBuild>
<!-- Issue a warning for each non-existent project. -->
<Warning
Text="The referenced project '%(_MSBuildProjectReferenceNonexistent.Identity)' does not exist."
Condition="'#(NonVCProjectReference)'!='' and '#(_MSBuildProjectReferenceNonexistent)'!=''"/>
</Target>
Some parameters are passed and some are returned, but where does the actual work happen? There isn't much on msdn - I've found Microsoft.Build.Tasks.ResolveProjectBase, but it's of not much use.
ResolveProjectReferences (at least the one you're pointing to) is a target that is used to resolve inter-project references by building them using the <MSBuild> task. This task takes a project file to build, as well as the names of one or more targets in the project that should be invoked as part of the build (it also takes other parameters, but you can ignore those for now).
Consider the following target:
<Target
Name="Build"
Returns="#(BuildOutput)">
<ItemGroup>
<BuildOutput Include="bin\Debug\Foo.exe" />
</ItemGroup>
</Target>
If you referenced a project containing this target, and wanted to resolve the "Foo" target's outputs, you would have a <ProjectReference> element in your project like so:
<ItemGroup>
<ProjectReference Include="..\SomeProject\SomeProject.proj">
<Targets>Build</Targets>
</ProjectReference>
</ItemGroup>
Note that, if "Build" is the default target for the referenced project, you could leave the "Targets" metadata off entirely. You can also specify multiple targets in the Targets metadata (a semicolon-delimited list).
So your ResolveProjectReferences target will come along and call the <MSBuild> task, passing it "..\SomeProject\SomeProject.proj" and asking it to build the "Build" target. Now, since the "Build" target specifies outputs via its Returns attribute (but the Outputs attribute will be used if the Returns attribute is not specified), these outputs will be harvested during the build, and returned at the <MSBuild> tasks's TargetOutputs parameter. They have several additional pieces of metadata added which enable you to segregate them by originating target. These include:
MSBuildSourceProjectFile - the referenced project whose build generated the output
MSBuildSourceTargetName - the name of the target whose build generated the output
If you're working inside a C# project, there are a bunch of other stages of reference resolution (including assembly resolution). Drop me a line if you want to know about these.
I have an MVC application which I have got working on Azure apart from getting the published .cspkg file to include css/jscript that is created in an afterbuild process (this works if I publish to a normal server which isn't using Azure).
In the afterbuild process I minify and merge files then add them to a deploy zip:
<PackageLocation>..\Deploy\Website.zip</PackageLocation>
<PropertyGroup>
<CopyAllFilesToSingleFolderForPackageDependsOn>
CustomCollectFiles;
$(CopyAllFilesToSingleFolderForPackageDependsOn);
</CopyAllFilesToSingleFolderForPackageDependsOn>
</PropertyGroup>
What MSBuild code do I need to change in order to do the same task but adding to the cspkg instead?
Here is how I just did it. In this example I have a .csproj file that is part of an Azure solution and the dll produced by my C# project needs a particular Xml file to live right next to it in the deployment. Here are some msbuild fragments from my .csproj file that show the technique. You can place all of this code below the import of Microsoft.CSharp.targets in your .csproj file.
<!-- Identify the Xml input file that must be deployed next to our dll. -->
<ItemGroup>
<SpecialXmlFileItem Include="c:\temp\MySpecialFile.xml" />
</ItemGroup>
<PropertyGroup>
<!-- In my case I needed the as-deployed Xml filename to be fixed and yet I wanted it to be possible
to provide any filename at all to be provided as the source. Here we are defining the fixed,
as-deployed filename. -->
<AsDeployedXmlFilename>MyServiceStorageConfig.xml</AsDeployedXmlFilename>
<!-- Wire our own AddFilesToProjectDeployment target into the GetCopyToOutputDirectoryItems
target. That target is evaluated not only as part of normal .csproj evaluation, but also as part
of .ccproj evaluation. It is how the .ccproj manages to interrogate your dll producing projects
about all of the project files that need to be packaged. -->
<GetCopyToOutputDirectoryItemsDependsOn>
AddFilesToProjectDeployment;
$(GetCopyToOutputDirectoryItemsDependsOn)
</GetCopyToOutputDirectoryItemsDependsOn>
</PropertyGroup>
<Target Name="AddFilesToProjectDeployment">
<Error Condition="!Exists('#(SpecialXmlFileItem)')"
Text="The all important and very special XML file is not found: %(SpecialXmlFileItem.ItemSpec)" />
<ItemGroup>
<ContentWithTargetPath Include="#(SpecialXmlFileItem->'%(FullPath)')">
<!-- In my case I wanted to deploy my xml file right next to my .dll, so I included no relative
path information in the below value of TargetPath, just the simple filename. But, I think if you
included relative path information in the below value that it would be preserved in the deployment. -->
<TargetPath>$(AsDeployedXmlFilename)</TargetPath>
<CopyToOutputDirectory>Always</CopyToOutputDirectory>
</ContentWithTargetPath>
</ItemGroup>
</Target>
-Bern McCarty
I think this is just a question of timing... make sure the files get combined, minified, and placed into build before the publishing (packaging) step happens.
Sorry I don't have more details; I've never tried to do this sort of thing.