I'm building the doc of a VS 2010 C# project with the Sandcastle Help File Builder. I've added the .xml documentation generated by the compiler and the Visual Studio solution .sln file of the project to the Documentation Sources. I have also added the project's executable .exe to References. However, It is not building. I get these warnings and errors:
SHFB: Warning BE0006: Unable to locate any documentation sources for 'C:\Users\user\Music\Documents\Visual Studio 2010\Projects\SFML_Platformer\SFML_Platformer.sln' (Configuration: Debug Platform: AnyCPU)
SHFB: Error BE0042: You must specify at least one documentation source in the form of an assembly or a Visual Studio solution/project file
What's the problem?
You should only add the XML documentation files as Document Source. The DLLs are added automatically after you add the XML files.
Here the answer from Eric a.k.a EWoodruff the developer of Sandcastle Help File Builder.
BE0006 means it couldn't find the documentation source based on the
project. BE0042 is a secondary result of that meaning it found
nothing at all to document. What type of projects are in the
solution? If it's a website project, bear in mind that they do not
typically produce any assemblies that are listed as output in the
project nor any XML comments files. In that case, you'd need to add
the web code providers to your project to get the XML comments and
manually add the website's .\bin folder as a documentation source in
the SHFB project. There's a topic on documenting websites in the
Getting Started section if that is the case.
All other project types should work. If all else fails, try adding
the assembly and XML comments files directly. I suppose it's possible
the Express editions use diffent project type IDs. If you can send me
the solution file and project file, I can take a look at them and see
why it isn't finding the targets. My e-mail address is in the About
box in the standalone GUI and in the footer of the pages in the help
file.
One other thing, make sure the Configuration and Platform settings
selected in the SHFB toolbar match the Configuration and Platform
settings used to build your project (i.e. Debug/AnyCPU,
Release/AnyCPU, Debug/x86, etc). If not, that will cause it to not
find the proper output targets.
Eric
source
I had this issue occur when I switched the project's build in VS.NET on my main application from Debug to Release. I assume it could not longer find the .dll I had specified to create the documentation. I could have fixed the mapping, but going back to Debug worked just fine for me to remove this error.
Don't forget to rebuild your solution after cleaning before running Build in Sandcastle.
Related
If there is a code library in a single file, is it possible for Visual Studio to "include" it remotely?
Consider a library I wrote -- Nemmet. Basically, the entire thing exists in a single file, by design. It's a very limited library, with barely any dependencies.
For people to include the source (even myself, in other projects), they would have to do one of the following:
Download the repo and add the project to their solution
Create the file, and copy and paste Nemmet.cs into it
Yes, they could install a Nuget package, but then you get the compiled DLL in your project, not the source. Nuget is really about functionality, not source code. Additionally, it requires me as the library owner to create and maintain the package, which I'm really not that interested in doing.
What I'm looking for is a more "casual" way of including raw source code into a project.
What would be nice is if Visual Studio could do a "remote include" or something. I'd love to be able to bind a source file to a URL (the "raw" URL at Github) and have VS update the contents of the file every once in a while, or on-demand (right click > "Update from URL").
(Yes, this assumes you trust the source. Let's assume you do. You'd have the same issue with any included library.)
Is there anything like this available in some way? Should I just WGet it? Am I not thinking of a more obvious way to achieve the same end?
You can use Paket which is a dependency manager for .NET projects. Many of us in the F# community use it quite a lot but there is no reason it isn't equally applicable to the rest of the .NET world.
Basically, you create a paket.dependencies file for your project to list your dependenies. It supports:
Nuget dependencies:
nuget EntityFramework
git repositories
git https://github.com/fsprojects/Paket.git
Single files
http http://www.fssnip.net/raw/1M/test1.fs
Github dependencies
github forki/FsUnit FsUnit.fs
Here is the getting started guide.
This is not quite the same thing, but I found a way to "Add as Link" in a Visual Studio project. You can add a source code file without actually adding it to your project.
When adding an "existing item," dropped the "Add" button down to "Add as Link." It will add a placeholder to the file to your project, and compile it in, but leave the file where it is. This means you could have a central project on your file system, and use that code in all sorts of projects without having multiple copies of the file sitting around. Changing the file in your central project would change it in all the other projects.
Again, not the same thing, but still helpful.
I have installed the most current version of Sandcastle from NuGet (EWSoftware.SHFB version 2015.10.10.0), and the needed Reflection package (EWSoftware.SHFB.NETFramework version 4.6).
I read #Frank-Rem answer to Numid's question How to generate documentation using Sandcastle NuGet package (EWSoftware.SHFB)? and tried to add a new project to my solution. However, when I try to add a Sandcastle Documentation project I do not have the Documentation project type as an option.
I uninstalled the NuGet package and reinstalled it, thinking it may have been a buggy install. But the documentation project type is still not an option, even after shutting Visual Studio down and relaunching it.
I read through the readme.txt file and saw that I will need to add some property tags to the .shfbproj file when it gets generated. Beyond that, I don't see any other steps that I need to perform or packages to install in order to get the project type to show up. I have also gone to the GitHub project page and checked the Issues tab to make sure this isn’t a known issue they are working on.
I am using Visual Studio Ultimate 2013.
Are there additional steps I need to take to get the Sandcastle project type to show up in the Add New Project list?
Thank you for any ideas!
I was able to resolve the issue by running the Sandcastle Help File Builder Guided Installer. This identified missing components and installed them.
I was then able to follow the instructions from #frank-rem on adding the documentation project and documentation source to the new project.
Assuming that you already have a solution with a project, add a new project of type 'Documentation' to your solution.
Right-click Documentation Sources and add a source by selecting the csproj you wish to document.
Then just build.
Additional steps I took to get a finalized help doc: I found that Sandcastle had added several TODO items, which didn't show up in the Visual Studio task list. So I did a search on the solution for TODO and resolved them that way.
After that I followed the instructions on adding the namespace summaries provided by #davy-landman (in a comment to Davy Landman's answer) to clear up some missing flags.
This has actually changed in the latest version (currently 1.9.3.0) to Project Properties > Summaries > NameSpaceSummaries. – Ant Swift Jan 6 '12 at 9:44
Me and my team just started using GitHub for our development.
Our project is written within Visual Studio (C#).
In our project files we have external references of .dll files that are saved in specific folder for each user for example (c:\users\$user\dlls\data.dll).
When one user is commiting it's changes - it's also including the .csproj files who contain the links for those .dlls but when another using is pulling from the tree the .csproj contains links from the other user's .dll file and he have to change manually the references in order for it to work.
We tried solving it by putting the .csproj files into .gtignore - though that back fired once our project development expended and each branch has different files.
During the writing of this post I thought of another solution - removing the .csproj from the .gtignore and moving all the external .dlls into folder with an agreed file path such as (c:\dlls) and that might solve our problem.
My question is this:
Is there another solution for our issue?
I haven't tested my suggested my solution I will give it a try next version - What do you think of it? Is that the way to go?
Thanks ahead for your replies,
H.
Why aren't you "sharing" those external DLLs in a folder in your project? What I do is add a folder named "External" in my solution which contains these DLLs (and PDBs and XMLs etc) and make sure it is also checked in. That way whenever someone adds a DLL, all other developers simply need to get the latest files from Git and it is on their machines.
Of course, only do this for DLLs that aren't available from NuGet.
It looks like you need a dependency manager such as NuGet or an alternative one.
I'm looking for a way to detect problems with assembly references in a large Visual Studio solution:
Binary references to bad locations, like a path not in source control or in the output of another project
Binary references to multiple versions of the same assembly across projects in the solution
Binary references without a path, that may be redirected to the GAC
Binary references that should have been project references
The whole story
I work on a large C# project with almost at 200 projects.
One of the problems that is creeping in over time is that references to assemblies are added but not always to the same version or to the correct location.
For example, a project may get a reference to System.Web.Mvc without a hint path, making it reference what ever version is in the GAC. Visual Studio (and Resharper) will also offer to add a missing reference but may do so by adding a reference to the output folder of another project.
Now the recent Windows Update catastrophy left some team members dead in the water, unable to build the solution. As you can imagine, this bumped up the priority of assembly reference management for us.
To detect some of the most obvious problems I've already setup an msbuild file that can be included in every csproj file and will detect bad references.
However, new project files will need to be edited manually to include that script. So that will inevitably be forgotten.
What I would really like is to check all project files in a solution for 'bad' references during the continuous build, so that all projects will be checked always.
I've been googling for a solution like this for some time and found lots of static analysis and code analysis tools but nothing to analyze project files in a solution.
So, before I go off and roll my own solution, is there a way to do this already?
Update
In order to clean up the code base I've created a bit of ScriptCS code that'll scan all csproj files for referenced to assemblies in Nuget packages and fix them. It's up on GitHub.
You can create a NuGet package where the sole purpose is incorporating a custom .targets file into a project. I recently used this strategy to solve another problem (error messages for missing .snk files).
Testing strong names of NuGet-distributed assemblies
Rackspace.KeyReporting source code
If you create a similar package, it's easy to right click on your solution node and verify that it is installed in all of your C# projects.
If your analysis is more complicated and requires the use of an assembly (custom build tasks) in addition to the .targets file, you can use an approach like I use for the Antlr4 NuGet package, which contains build tasks, resources, and custom .props and .targets files, but no actual assemblies that are referenced by the project it gets installed in.
ANTLR 4 C# Target source code (includes the Antlr4 package source and build scripts)
Instead of adding it to all projects in your solution, why not create some kind of test (unit test, build file, whatever) that can take a project file as input, parse it, and throw an error if OE or more references are incorrect. Much easier than adding (and checking out, committing etc) custom build steps to project files.
Even if you would use a nuget package as proposed earlier, you'd still have to check manually whether all your projects (200 projects? Really?) Reference the package.
during development of our application we use a branching structure and while we are developing another team is using earlier builds of our software to create content with it.
To facilitate easy swapping between builds and teams I was hoping to use empty Hintpaths in the content projects' csproj files so that they can use our GAC installed assemblies to build against and in the meantime add a reference path to the projects for our use during development and test cycles where we don't want any assemblies installed in the GAC.
However, it seems reference paths are not stored in the csproj file and thus don't get sourcecontrolled. Since there will be extensive branching it would be less than ideal to have to set all reference paths again when a developer pulls another branch from sourcecontrol.
I've been searching for a bit now and can't seem to find ways to do this. Anybody know of a way to force the reference path in and out of sourcecontrol?
We're talking Visual Studio 2008 and TFS 2008 here.
Cheers,
Anton.
Ok, I seem to be a little clearer in the head after a good night's sleep, took the logical step, namely investigate where exactly the information was stored and how. It turned out the information was stored in the .user file for the project in the project's folder and as it turens out this file contains mbsuild xml.
I then did what I wanted as follows:
Create the Reference path as I required it to facilitate both scenarios without any work.
Browse to the Project's .user file
Copy the PropertyGroup containing the ReferencePath
Paste the PropertyGroup in all the necessary Projects' .csproj xml.
Reload and build.
Done.
The references are stored in the *.csproj file. The nodes are ItemGroup/Reference...
Thomas
This is pretty simple--we do this in our shop.
First, in the Workspace (using Windows Explorer, browse to the Solution folder), create a folder. We name it "Referenced Assemblies". In here, drop all your DLLs.
Now, in the Solution, add a new folder to match the one created in Windows Explorer. Into that folder, add all the DLLs you just dropped in.
Finally, in each project, set up your references to use the DLLs that were added to the solution.
Now your project references DLLs that are part of the solution, so that when the build runs, it will grab the DLL from Source Control to generate the build.
Also, I'd recommend not using the GAC at all if you can avoid it. In my experience, reference behavior is strange. It seems references go first to the GAC, then to the DLL in the local folder, meaning that if the DLL is updated, the one in the GAC is used instead of the DLL in the local folder (which is likely the updated one).