Adding external sources

Topics: DocSites, General Questions
Jan 24, 2008 at 11:45 AM
Hello

I've a problem with DocProject for VS2008 and Sandcastle October (as i remember, i had the same problems on visual studio 2005)

My Problem is as follows;

- I created a project, added external sources, did a API Topic Management Design (exlucded some constructors), did a successfull build.
- Then i added additional external sources, but now, if i open the Topic Manager, it only shows the Namespaces/Types from my "first" external source, not from the new one I've linked.

Can you tell me what to so? (I deleted the section from the MrefBuilder File, then my deselections are lost (as expected), but the other external sources are still not viewable in the TopicManagement.

Greetings.
Jan 24, 2008 at 11:59 AM
Uhoh, sorry for this post, i find it out, "Clean Solution" was the solution...

Shame on the Codemonkey

Greetings Cis
Coordinator
Jan 24, 2008 at 3:43 PM
This discussion has been copied to a work item. Click here to go to the work item and continue the discussion.
Coordinator
Jan 24, 2008 at 3:45 PM
Hey Cis,

Thanks for reporting this issue. It's a bug and it will be fixed in 1.10.0 RC.

- Dave
Jan 24, 2008 at 4:01 PM
Hello Dave

I thought this is not a bug.

@Little off topic
If you are working on the mechanism maybe you can fix another "bug" --> if it is a bug. I think it should be at the same place.

If I do a "fresh/complete" build, and then cancel this build, in the nextbuild, it does only "Step 1" because it thinks that there was a previous build.
To solve this, a clean solution is not enough, i have to close Visual Studio and reopen it.

Greetings

davedev wrote:
Hey Cis,

Thanks for reporting this issue. It's a bug and it will be fixed in 1.10.0 RC.

- Dave

Coordinator
Jan 24, 2008 at 5:39 PM
Hi Cis,

I'm just considering it a bug because I feel that the current behavior is inappropriate.

The Topic Management dialog will build a reflection file if it needs to but it will try to use one that already exists if possible. So if a reflection file currently exists and you add new sources, then that should cause a Full build, which will cause the dialog to rebuild the reflection file in the background the next time that it's opened.

Note that the new Topic Explorer tool window will not be updated automatically when you add new sources; however, there's a Refresh button (looks exactly like the button in Solution Explorer) that you can click yourself after you add external sources and the entire TOC will be rebuilt if necessary.

The other bug that you mentioned was actually fixed already, sort of, but thanks for reporting it.

One problem was that the rebuild command didn't work because the build type was being set on the BuildContext, not the BuildEngine, and the BuildEngine's value had precedence. That's not the case anymore - whichever build type has precedence (i.e., full over partial, partial over skip) will be used regardless of whether it's set on the BuildContext or the BuildEngine. i.e., instead of having to close Visual Studio you can just use the rebuild command. Clean will not work however because clean only deletes the compiled help file but does not change the build type to full.

The real issue though is that DocProject determines whether a full build must be executed based on the state of the sources and the presence of required build items. If you cancel the build after the required build items have been generated then the next build will automatically be a partial build since the only thing missing are the compiled help files (.chm, .HxS). Also, at this point, the source timestamps are up-to-date so DocProject will not have to perform a full build for that reason either.

I guess I could just have the BuildEngine's build type set to full when a full build is canceled, regardless of how far it got. That would do the trick. I'll try it out and see if it works.

- Dave
Jan 28, 2008 at 9:40 AM
Hello Dave

You wrote

"The real issue though is that DocProject determines whether a full build must be executed based on the state of the sources and the presence of required build items. If you cancel the build after the required build items have been generated then the next build will automatically be a partial build since the only thing missing are the compiled help files (.chm, .HxS). Also, at this point, the source timestamps are up-to-date so DocProject will not have to perform a full build for that reason either.

I guess I could just have the BuildEngine's build type set to full when a full build is canceled, regardless of how far it got. That would do the trick. I'll try it out and see if it works."

It think this is a behavior which is best fitting for most the users. But, as i remember, if you cancel the rebuild (lets say on step 2) next time he does not continue on step 3, he continues on the "last step" (maybe sending the prepared stuff to the sandcastle help builder?) and this buildstep failes because there are severeal unexecuted buildsteps.

In my case, i have no need for a forced "fullbuild" if I cancel, if Docsite/Sandcastle would continue with the last unsuccessfull step, that would be fine. (So the buildprocess can finish the rebuild task, continuing with the last unsuccessfull step.)

You wrote
" instead of having to close Visual Studio you can just use the rebuild command."

Thats something that i don't understand, i think this is my problem, that if i do a rebuild all, on a previous canceled build, he can not continue?

Thanks and greetings

Cis
Coordinator
Jan 28, 2008 at 4:19 PM
Hi Cis,



I guess I could just have the BuildEngine's build type set to full when a full build is canceled, regardless of how far it got. That would do the trick. I'll try it out and see if it works

It think this is a behavior which is best fitting for most the users. But, as i remember, if you cancel the rebuild (lets say on step 2) next time he does not continue on step 3, he continues on the "last step" (maybe sending the prepared stuff to the sandcastle help builder?) and this buildstep failes because there are severeal unexecuted buildsteps.

It doesn't force the build to continue from the last step - it just runs a partial build, which might only include a single step. This occurs because all of the required partial-build items exist and the project is not out-of-date. Although, DocProject doesn't attempt to detect whether all required intermediary build output is present in the working directory, it just assumes so. Since the process is dynamic it's just not possible to gather that information ahead of time.

For more information on partial builds and how it works using the Sandcastle build engine, see Build Process.


In my case, i have no need for a forced "fullbuild" if I cancel, if Docsite/Sandcastle would continue with the last unsuccessfull step, that would be fine. (So the buildprocess can finish the rebuild task, continuing with the last unsuccessfull step.)

I don't think it would be an appropriate behavior for DocProject to just assume that it's safe to build from the last step that was canceled.

I've already made the changes to fix the previous bug and it seems to work fine now, however, if a full build is canceled then the build must start from the beginning again. The reason is that the build type is controlled by the presence and timestamps of build items and I don't think it's safe to assume that after a canceled build the process can just be started again from where it left off. It's possible that required files may be modified or deleted after it has been canceled, which would mean that previous build steps must be executed again, but there's no fail-safe way to detect that since the process is so dynamic - one change to a seemingly innocuous setting may cause a full build to be required again. And that behavior might also have a negative affect on build process components that insert dynamic steps.

Here are the changes that I made for 1.10.0 RC:
  • The IDocProject interface has three new events: ReferenceAdded, ReferenceChanged and ReferenceRemoved. DocProjectEnvironment now caches IDocProject implementations and registers handlers for these events. When they are raised the project's related IBuildEngine's BuildType property is assigned the value of Full to force a rebuild the next time the project is built. The ReferenceAdded and ReferenceRemoved events are raised for both project references and external sources. (This solved your original problem.)
  • Previously, the build engine's BuildType property was being set to Default again after each build, but now it's only set back to Default if context.Canceled is not true. When true, the BuildType remains the same. This means that if you cancel a full build then a full build will occur the next time (and the process will start from the beginning again). Likewise, if you cancel a partial build then a partial build will occur, unless of course some change forces a full build, which always has precedence.
  • The Topic Management dialog and the new Topic Explorer tool window now use the following code to determine whether the TOC must be rebuilt or if the existing data in the working directory can be used to save some time:
if (forceRebuild || !referenceTopicsLoaded || rebuildRequired || 
engine.BuildType == BuildType.Full || engine.BuildType == BuildType.Partial || 
engine.SourceAssembliesDirty || !System.IO.File.Exists(tocFile) || !System.IO.File.Exists(reflectionFile))
{
  // rebuild TOC
}
This means that the TOC will be rebuilt if any of the following are true:
  • A caller has requested it (such as when the new Refresh button is clicked).
  • The topics have not yet been loaded into memory (i.e., the first time it's used).
  • Since the last time that the TOC-only was rebuilt an actual help build was executed (i.e., running a true build will cause the TOC to be rebuilt for topic management just in case filters have been applied, because the same files cannot be reused then).
  • If the BuildType property on the project's engine has been set to Full or Partial (e.g., if a project's sources change).
  • If the engine detects that sources' timestamps have changed.
  • If the TOC or reflection files are missing.



instead of having to close Visual Studio you can just use the rebuild command.

Thats something that i don't understand, i think this is my problem, that if i do a rebuild all, on a previous canceled build, he can not continue?

I meant that it would be true in the next release, the one I'm currently working on, not in the release that you're using. This is because I fixed a bug, as noted.

Thanks,
Dave