Documenting external dll's with sandcastle - c#

I'm currently developing an application, which requires external dll's which I do not control. I'd like to add documentation for these classes, so that others can understand why I'm making certain calls I'm making to these external DLL files.
Adding the external DLL files to the documentation sources does indeed log the classes, but all the summaries and other information is unavailable. Is it possible to document these files (Preferably without having to decompile/recreate the assembly as a project), so I can generate the related HTML documentation with sandcastle?
I've tried to keep Sandcastles working directory enabled, to see if the .xml files (That I see were copied over from my other projects) were somehow generated and placed in this directory. This doesn't seem to be the case, no files were generated, and it goes straight to generating the html files.

As far as I understand your question about creating documentation for an external DLL use case I see two possible ways that you can go:
Add "missing" notes for all items of the external DLL that you might want to document or/and
add conceptual topics to your own program documentation.
My sample solution WindowsApplication2 project has a form to add two values using a simple PDUNZDLL. A Sandcastle help file builder project "Documentation1" was added and two Documentation Sources (at this stage without XML comment file, see first snapshot below). You know - a DLL without XML comments file is resulting in a red missing summary.
Proposed solution (1):
Create a blank XML comments file like the following and name it after the assembly with a .xml extension e.g. PDUNZDLL.xml
<?xml version="1.0"?>
<doc>
<assembly>
<name>PDUNZDLL</name>
</assembly>
<members>
</members>
</doc>
Save this file to the e.g Debug folder D:\Visual-Studio-2015\Projects\WindowsApplication2\WindowsApplication2\bin\Debug
Double-click the "Project Properties" (see second snapshot below)
In the Component Configurations dialog, add the "IntelliSense Component" to the project.
Select "Missing Tags" and set the project's Show Missing Tags properties to your liking. This will force the build to add "missing" notes for all items that you might want to document.
Build the project and you will find a new XML comments file named after the assembly in the project's output folder e.g. D:\Visual-Studio-2015\Projects\WindowsApplication2\Documentation1\Help
Edit the <member> elements in the XML comments file to add the comments that you want for each member as shown in the second snapshot.
When you are done, replace your original placeholder file e.g. D:\Visual-Studio-2015\Projects\WindowsApplication2\WindowsApplication2\bin\Debug\PDUNZDLL.xml with the one generated from the build with your edited comments. ReBuild your documentation project.
This is of course time consuming as any help authoring for applications. And it was actually the task of the DLL developer.
Proposed solution (2):
Reading between your lines "... so that others can understand why I'm making certain calls I'm making to these external DLL files." leads me to the suggestion to add a supplementary documentation to your own program.
So, what I mean is to add conceptual topics describing how you call the features of the external DLL files.
I removed the the DLL under "Documentation Sources",
added a new folder "ExternalDLL",
added a new item Conceptual and Walkthrough,
double-click ContentLayout.content in Solution explorer,
and did all the steps for content layout, ReBuild the documentation project resulting in a help file like shown in the third snapshot below (see background info too).
Happy help authoring!

Related

How to insert a code snippet from a visual studio extension

I am writing an extension for our group that creates a few folders and .cshtml files. This extension will also add a few dozen code snippets. I would really like to add some of the code snippets to the files when they are created so if a user changes their snippet it will also change in the generated code. Is there any way to access/insert code snippets from an extension?
The code snippet is usually added when developing/writing codes. Looks like you want to make this process automatically, like the newly created/inserted file has already included the related codes. And it seems you also want to make the snippet changeable.
I’m not sure if your requirements are more related to the project template or the more complex Visual Studio extension. I can share you a simple sample about how to insert a normal code snippet from a normal VS extension to the developed project/file, but it is manually. So perhaps it’s not what you want but I hope this could give you some references or a little help.
Sample
1). Install related VS SDK, and workload for creating Visual Studio Extension project. Create a VSIX project in VS.
2). Right-click the project in Solution Explorer and add one new folder(named it for example Snippets), after that add a subfolder named like My snippets(you can add other subfolders to classify), in this subfolder add some .snippet files.
3). Edit the .snippet files and add some related XML codes in it. Refer to this document: Snippet template.
4). Create a new file named XXXX.pkgdef and save it in project root folder, edit it and add related codes in it for registering. For example(for C#)
[$RootKey$\Languages\CodeExpansions\CSharp\Paths]
"MySnippets"="$PackageFolder$\Snippets\XXXXXXXX"
5). Right-click the source.extension.vsixmanaifest file > View Designer > Asserts > if there is a source, select it and click Edit > Choose related things:
6). (Optional) Edit the source.extension.vsixmanaifest file > Metadata to fill the related information that you want to set, such as Description, License Tags…
7). Hit F5 to debug and an Experimental instance of VS will launch, check the code snippet feature there.
Related documents threads/blog: Shipping Visual Studio snippets in an extension.

How to manually add a library to a visual studio 2017 project?

My apologies for this very basic question that has assuredly been asked and answered before, also for my very dated terminology. I searched for an answer, but failed to find anything helpful. I am using the latest update of VS 2017 Community, and I'm trying to manually add what I used to call a "function library" to a project, which sits under a "solution".
The project is simply a C++ or C# console application. What I have is a .h (header) file, a .lib (static library) file, and a .dll (dynamic library) file. I intend to make "function calls" to this library. I'm aware that I need to have my dll in the debug folder where the executable resides, but I'm not sure how to "add dependencies" in VS 2017. I know how to manage and install NuGet packages, but these files aren't a handy-dandy NuGet package.
I hope to get advice on doing this the right (VS 2017) way.
What I do in a situation like this is to create a folder, I use C:\Etc\SDKs\<name_of_library> and then within that folder create an include subfolder, and a lib subfolder. Note that the top level folder choice is completely arbitrary, place it where it makes the most sense to you.
In the C/C++ section of project properties on the General tab, or the corresponding section for C# projects, there's an entry for Additional include directories. Add the path to your newly created include folder there. That'll let you include the header file and have it work right.
In the Linker section of project properties, also on its General tab, there's a corresponding entry for Additional library directories. Add the path to your lib folder there. On the next tab down: Input there's an entry for Additional Dependencies. Add the actual name of the library file there.
Those steps should allow your project to be built using the .h, .lib and .dll files you have.
-- Edit to address comments --
The .lib file does go in the ...\lib folder, and the .h file in the ...\include, that's correct. However, you had the location of the .dll correct in your original question. That needs to be somewhere on the search path that the executable will find, so the easiest place is the same folder as the executable.
General tab is a poor choice of words on my part. General section might have been better here. When looking at the project properties, the left most pane is a tree view of the various property sections. With everything closed up, except the very top item open, you'll see
Configuration Properties
General
Debugging
VC Directories
> C/C++
> Linker
...
If you then double click on C/C++ it'll open up, and show the sections specific to the C/C++ compiler:
Configuration Properties
General
Debugging
VC Directories
V C/C++
General <<<<<
Optimization
Preprocessor
...
> Linker
...
If you click on the word `General that I've highlighted, that'll get you to the General section / tab I was talking about.
Likewise, double clicking the word Linker will open up that section, and under that you'll find the Linker General and Input sections.
Let me know if this still isn't clear, and I'll try to clarify.

application config file clean up

a c# application which I worked on in the past went through a couple of namespace changes and assembly name changes.
As a result of this my application's config file that is generated when I build is full of older stuff that is of no use to me anymore.
I've tried deleting these sections. I tried deleting the whole config file and forcing VS to build me a new one but it keeps building me a copy from a LONG time back.
How can I force my application to give me a new config file whenever I want to?
edit: question was unclear. I'll try to add more.
Let's say for example that my application was called "mytools". I then changed the assembly and namespace settings for the program and now it is called "mytoolsPLUS". When I build my application and view the mytoolsPLUS.exe.config file I see in the <configsections> node I have two <sectiongroup> nodes, usersettings and applicationsettings. Within the usersettings <sectiongroup> node I have an entry for <section name=mytools.properties.settings type=sys.config.clientsettingssection....> but I also have an entry for <section name=mytoolsPLUS.properties.settings type=sys.config.clientsettingssection...>
This same sort of duplication occurs under my <connectionstrings> node and thus is the main reason I am posting this thread today. One of my end users got confused as to which connection string they needed to adjust to point to a backup test server. I looked into it more and found that I have lots of "old fragments" left over in my config file. I like using the settings class over a full xml file for small apps like this so I would like to figure out what I have done wrong here. I hope my explanation is clear enough for those who are reading.
Thanks for reading my post!
In your project, tree open the properties node directly under the project.
In there you will see a "Settings.settings" and "Settings.Designer.cs" file. Right click each of the files and choose "Open With.." and pick "Source code editor".
You should be able to clean up anything old from here.
You can also use a standard text editor to edit these.
In your project, there should be a file called App.config. You can delete the extra sectionGroups and other extraneous stuff there to clean-up your config file.

Adding Mouse-Over summary from a dll

Our Organization is creating a global dll for all of our projects in the coming years. The dll is created, and implemented for use, but I'm having a problem getting the summary tags to work. When hovering over a specified method from the dll, I want to be able to display the summary for any developer, so they will not have to go into the dll itself.
I came here and found this question: How to add a mouse-over summary
The problem is, the summary is not displaying when the method is being called from outside the dll itself (however, from inside the dll the summary is displaying just fine).
Is there any way to "import" the summary from the dll so it will be displayed when any user hovers over the appropriate method?
I assume you're not adding this project to your various solutions, but instead are building it once and copying the .dll around, and browsing out to the .dll when you add references in your projects.
When you copy this .dll around, are you also copying the ProjectName.xml file? That's where the compiler writes all of these documentation comments when you build, and is where Visual Studio gets the information it displays in the Intellisense tooltips.
More info on MSDN: XML Documentation Comments (C# Programming Guide)
I believe you should look at putting your DLL into the GAC

What does MissingManifestResourceException mean and how to fix it?

The situation:
I have a class library, called RT.Servers, containing a few resources (of type byte[], but I don't think that's important)
The same class library contains a method which returns one of those resources
I have a simple program (with a reference to that library) that only calls that single method
I get a MissingManifestResourceException with the following message:
Could not find any resources
appropriate for the specified culture
or the neutral culture. Make sure
"Servers.Resources.resources" was
correctly embedded or linked into
assembly "RT.Servers" at compile time,
or that all the satellite assemblies
required are loadable and fully
signed.
I have never played around with cultures, or with assembly signing, so I don't know what's going on here. Also, this works in another project which uses the same library. Any ideas?
All I needed to do to fix this problem was to right-click the Resources.resx file in the Solution Explorer and click Run Custom Tool. This re-generates the auto-generated Resources.Designer.cs file.
If the .resx file was added to the project manually, the Custom Tool property of the file must be set to "ResXFileCodeGenerator".
The problem is due to a mismatch of namespaces, which occurs if you change the "default namespace" of the assembly in the project settings. (I changed it from (previously) "Servers" to (now) "RT.Servers".)
In the auto-generated code in Resources.Designer.cs, there is the following code:
internal static global::System.Resources.ResourceManager ResourceManager {
get {
if (object.ReferenceEquals(resourceMan, null)) {
global::System.Resources.ResourceManager temp = new global::System.Resources.ResourceManager("Servers.Resources", typeof(Resources).Assembly);
resourceMan = temp;
}
return resourceMan;
}
}
The literal string "Servers.Resources" had to be changed to "RT.Servers.Resources". I did this manually, but running the custom tool would have equally well done it.
I just came across this problem today, and I found this Microsoft Help and Support page that actually did work around the problem.
I had a couple delegates at the top of my file, in the global namespace, and all of a sudden I was getting a MissingManifestResourceException when running the program, on this line:
this.Icon = ((System.Drawing.Icon)(resources.GetObject("$this.Icon")));
Then I moved the delegates into the namespace, got the same error. Finally I put the delegates in the only class in that file, and the error went away, but I didn't want the delegates in that class or namespace.
Then I came across that link above, which said
To resolve this problem, move all of the other class definitions so that they appear after the form's class definition.
I put the delegates (which I would not consider "class definitions") at the bottom of that file, outside of the local namespace, and the program didn't get the MissingManifestResourceException anymore. What an irritating error. But, that seems like a more robust solution than modifying the auto-generated code :)
I've run into a similar issue and, although I know it isn't the cause the OP had, I'll post it here so that if someone else runs across this problem in the future, an answer will be available.
If you add a class before the designer class you will get a MissingManifestResourceException exception at runtime (no compile time error or warning) because
Visual Studio requires that designers use the first class in the file.
For (slightly) more information see this post.
I had the same problem, but using the Run Custom Tool command as suggested by Timwi did not help in my case.
However it lead me into the right direction, because I ended up in the Properties of the .resx file. Here I noticed a difference to another .resx file that caused no problems.
In my case I had to change the property "Build Action" from "Resource" to "Embedded Resource".
My best guess for the reason is, that I had the .resx in a library that was used from another application. My application did not have its own .resx file, so it had to use the one from the library - which is only available when it's embedded in the library and not "stand alone".
When I run in a similar issue, in Vs 2012, it turned out that the "Custom Tool Namespace" property of the resx file was wrong (in my case, actually, it was unset, so the generated code yeld this exception at runtime).
My final set of properties for the resx file was something like this:
Build action: Embedded Resource
Copy to Output Directory: Do not copy
Custom Tool: ResXFileCodeGenerator
Custom Tool Namespace: My.Project.S.Proper.Namespace
I ran into a different cause of this problem, which was unrelated to resx files. I had a class library where AssemblyInfo.cs contained the following:
[assembly: ThemeInfo(
ResourceDictionaryLocation.SourceAssembly,
ResourceDictionaryLocation.SourceAssembly)]
The assembly did not contain any WPF code, theme or Resource dictionaries. I got rid of the exception by removing the ThemeInfo attribute.
I did not get an actual exception, only
A first chance exception of type 'System.Resources.MissingManifestResourceException'.
Viewing exception details, the system was requesting MyAssembly.g.resources
Hope this might be of help to someone else.
Also see: MissingManifestResourceException when running tests after building with MSBuild (.mresource has path in manifest)
I repeat the answer here just for completeness:
It appears adding LogicalName to the project file fixes it:
<LogicalName>$(RootNamespace).Properties.Resources.resources</LogicalName>
i.e. so the embedded resource entry in the project file looks like this:
<ItemGroup>
<EmbeddedResource Include="Properties\Resources.resx">
<Generator>ResXFileCodeGenerator</Generator>
<LastGenOutput>Resources.Designer.cs</LastGenOutput>
<LogicalName>$(RootNamespace).Properties.Resources.resources</LogicalName>
</EmbeddedResource>
</ItemGroup>
This is detailed in: http://blogs.msdn.com/b/msbuild/archive/2007/10/19/manifest-resource-names-changed-for-resources-files.aspx
Note that we are using a .resx file, but the bug still appears to occur.
Update: The problem with resources (incl. XAML) appears to be related to output paths and the use of forward or backward slashes as detailed in:
Why does modifying project output directories cause: IOException was unhandled "Cannot locate resource 'app.xaml'."
Not sure it will help people but this one worked for me :
So the issue I had was that I was getting the following message:
Could not find any resources appropriate for the specified culture or the neutral culture. Make sure "My.Resources.Resources.resources" was correctly embedded or linked into assembly "X" at compile time, or that all the satellite assemblies required are loadable and fully signed"
I was trying to get the resources that were embedded in my project from another class library.
What I did to fix the problem was to set the Access Modifier in the tab Project->Properties->Resources from "Internal" (accessible only within the same class library) to "Public" (accessible from another class library)
Then run and voilà, no more error for me...
The solution given by BlaM worked for me too.
I am a VS 2013 User. After going through many fixes but no luck, I tried this:
Right-click the resource file, one-by-one, in case of multiple-files.
Make sure, the property "Build Action" is set to "Embedded Resource".
That's it! :)
I had the same issue, but in my case i places a class in a usercontrol which is related to the usercontrol like this
Public Class MyUserControlObject
end Class
Public Class MyUserCOntrol
end Class
The solution was to move the MyUserControlObject to the end of the Usercontrol class, like this
Public Class MyUserCOntrol
end Class
Public Class MyUserControlObject
end Class
I hope this helps
I was getting the MissingManifestResourceException error after I ported my project from VS2005 to VS2010. I didn't have any other classes defined in the file that contains my Form class. And I also had my resx Resource File Name set correctly. Didn't work.
So I deleted the resx files and regenerated them. All good now.
Recently ran into the same problem, struggled for a bit, found this topic but no answers were correct for me.
My issue was that when I removed main window from my WPF project (it does not have a main window), I forgot to remove StartupUri from App.xaml. I guess this exception can happen if you have a mistake in StartupUri, so in case if anybody is struggling with this - check your StartupUri in App.xaml.
Recently stumbled upon this issue, in my case I did a few things:
Make sure the namespaces are consistent in the Designer.cs file of the resx file
Make sure the default namespace of the Assembly(right click the project and choose Properties) is set the same to the namespace the resources file is in.
Once I did step 2, the exception went away.
I had this problem when I added another class in the file just before the class which derived from Form. Adding it after fixed the problem.
Also the same error may occur when you put a new class into the source code of a designer created form's class.
This new class may be removed, and placed in a different cs file.
(At least in my case this was the problem...)
Because I am pre-compiling my web application (using VS2012 publish feature). I was getting the error above. I tried all the suggestions, but weirdly changing 'Build Action' to 'Content' did the trick!
In my case, I have a web api with resources and I create a nuget package from that. When I use this nuget in other projects, I realise that when I request a api with resources, I am getting MissingManifestResourceException after a bit reasearch, I learn nuget packager is not packing resources automatically. If you want to use resources files, you have to do that manually. So you need to add below lines to your .nuspec file:
(Visit https://github.com/NuGet/Home/issues/1482)
<package>
<metadata>
</metadata>
<files>
<file src="bin\Debug\en\MyAssembly.resource.dll" target="lib\net40\en\MyAssembly.resource.dll" />
<file src="bin\Debug\es\MyAssembly.resource.dll" target="lib\net40\es\MyAssembly.resource.dll" />
</files>
</package>
But, before adding files, you need to be sure which version of .net you are using.
I had the with a newly created F# project.
The solution was to uncheck "Use standard resource names" in the project properties -> Application -> Resources / Specify how application resources will be managed.
If you do not see the checkbox then update your Visual Studio! I have 15.6.7 installed. In 15.3.2 this checkbox is not there.
Just to mention. If you use a constant or literal, make sure it refers to a resource of the form ProjectName.Resources, and does not cpntain Resources.resx.
It could save you an hour or two .
I've encountered this issue with managed C++ project based on WinForms after renaming global namespace (not manually, but with Rename tool of VS2017).
The solution is simple, but isn't mentioned elsewhere.
You have to change RootNamespace entry in vcxproj-file to match the C++ namespace.
In my case it was a typo in the Xaml of a window opened from Winforms Form:
Incorrect: <Image Source="/Resources/WorkGreen.gif"/>
Correct: <Image Source="../Resources/WorkGreen.gif"/>
It may help someone
In my case I have changed my project namespace and hence my solution was throwing "missingmanifestresourceexception" exception. Instead of right clicking the .resx file in the solution explorer and clicking on "Run Custom Tool" option, I have replaced the
rootnamespace to new namespace in .csproj file(RootNamespace) and rebuilded the solution again. All Resources.Designer.cs files namespaces got automatically changed with new namespace.
I hope my answer will help someone.
If you're getting this while generating a C# project using CMake, the solution I found may help you.
Your CMakeLists.txt file needs
set_property(TARGET yourTargetName PROPERTY VS_GLOBAL_RootNamespace yourRootNamespace)
Substitute your own values for yourTargetName and yourRootNamespace, obviously.
Then the resources will get embedded in your assembly!
One more reason to get this error is- '.resx' file excluded from project.
In my case, '.resx' file was excluded from project.
Select 'show all files' option in solution explorer.
Right click on '.resx' file(s) and click include in project.
Rebuild the project/solution.
I read all the answers and nothing worked for me. Most likely my situation is different, but same error. My issue was that I had two projects. Second project had a lot of forms added to it from the first one as "Add as link".
For WinForms, there are 3 required files: the code, the designer, and the resource files. If you add all 3 files at the same time as "Add as link", Visual Studio does not link them together as same form. It will compile, and run, but it will blow up with the same MissingManifestResourceException error.
Fix: You have to do them individually, in order: code file --> designer file --> resource file. Then they are grouped and no more error, at least for me.
From the Microsoft support page:
This problem occurs if you use a localized resource that exists in a satellite assembly that you created by using a .resources file that has an inappropriate file name. This problem typically occurs if you manually create a satellite assembly.
To work around this problem, specify the file name of the .resources file when you run Resgen.exe. While you specify the file name of the .resources file, make sure that the file name starts with the namespace name of your application. For example, run the following command at the Microsoft Visual Studio .NET command prompt to create a .resources file that has the namespace name of your application at the beginning of the file name:
Resgen strings.CultureIdentifier.resx
MyApp.strings.CultureIdentifier.resources

Categories

Resources