diff --git a/src/dotnet/docs/source-stepping.md b/src/dotnet/docs/source-stepping.md new file mode 100644 index 0000000000..f7d8e1e723 --- /dev/null +++ b/src/dotnet/docs/source-stepping.md @@ -0,0 +1,65 @@ +--- +title: How to step into source in the Visual Studio debugger +uid: source-stepping +summary: *content +--- + + + +Debuggers can step into the source code, set breakpoints, watch variables, etc. It's easy to drop into Lucene.NET code any time you want to understand what's going on. + +If you're getting ready to report a bug in Lucene.NET, figuring out how to create a minimal repro is much easier since you aren't dealing with a black box! + +> [!NOTE] +> This feature is enabled using [Source Link](https://github.com/dotnet/sourcelink#readme), which also has support for source stepping in [Visual Studio Code](https://devblogs.microsoft.com/dotnet/improving-debug-time-productivity-with-source-link/#visual-studio-code). + +As Source Link downloads files from the internet, Visual Studio has it disabled by default. Enabling it requires changing a few of the Visual Studio settings: + +1. Go to **Tools > Options > Debugging > Symbols** and ensure that the `NuGet.org Symbol Server` option is checked. It may also be a good idea to specify a cache directory once you have Source Link set up so Visual Studio won't need to repeatedly download the same source files each time you step into them. + + ![Enabling Source Symbols](https://lucenenet.apache.org/images/contributing/source-link-setup/debugging-with-source-link01.png) + + > [!NOTE] + > If you are on .NET Framework, you'll also need to check the `Microsoft Symbol Servers` option. + +2. Disable `Just My Code` in **Tools > Options > Debugging > General** to allow Visual Studio to debug code outside of your solution. Also, verify that `Enable Source Link support` is enabled. + + ![Enabling Source Link](https://lucenenet.apache.org/images/contributing/source-link-setup/debugging-with-source-link02.png) + + > [!NOTE] + > If you are on .NET Framework, you'll also need to check `Enable .NET Framework source stepping`. + +## Verifying Source Link + +1. To confirm Source Link is working, set a breakpoint before or on a line of code that calls a Lucene.NET type and start debugging the application. + + ![Breakpoint at BytesRef](https://lucenenet.apache.org/images/contributing/source-link-setup/debugging-with-source-link03.png) + +2. Step into the code, just as you would for any local method (F11 is the default keyboard shortcut). If all is configured correctly, you will be prompted to download the source code file for the type you are stepping into. Click on either `Download Source and Continue Debugging` option to continue. + + ![Download Source and Continue Debugging](https://lucenenet.apache.org/images/contributing/source-link-setup/debugging-with-source-link04.png) + +3. After a short pause, The debugger will step into the next line after your breakpoint inside the Lucene.NET source code. + + ![Step into BytesRef](https://lucenenet.apache.org/images/contributing/source-link-setup/debugging-with-source-link05.png) + +Congratulations! You can now step into Lucene.NET code to figure stuff out and to help put together a thorough bug report or PR. + + + + diff --git a/websites/apidocs/docfx.core.json b/websites/apidocs/docfx.core.json index 7d276f72aa..17f090ee81 100644 --- a/websites/apidocs/docfx.core.json +++ b/websites/apidocs/docfx.core.json @@ -34,13 +34,19 @@ "**.md" ], "src": "obj/docfx/api/core" - }, + }, { "files": [ "toc.yml", "core/toc.yml" ], "src": "toc" + }, + { + "files": [ + "source-stepping.md" + ], + "src": "../../src/dotnet/docs" } ], "overwrite": [ diff --git a/websites/apidocs/index.md b/websites/apidocs/index.md index a72fdd3af8..1a198e591d 100644 --- a/websites/apidocs/index.md +++ b/websites/apidocs/index.md @@ -1,6 +1,6 @@ --- -title: Lucene.Net Docs - The documentation website for Lucene.Net -description: The documentation website for Lucene.Net +title: Lucene.Net Docs - The documentation website for Lucene.NET +description: The documentation website for Lucene.NET --- Apache Lucene.Net Documentation @@ -8,7 +8,7 @@ Apache Lucene.Net Documentation --------------- -Lucene is a _.NET full-text search engine_. Lucene.NET is not a complete application, +Lucene.NET is a _.NET full-text search engine_. Lucene.NET is not a complete application, but rather a code library and API that can easily be used to add search capabilities to applications. @@ -32,7 +32,8 @@ on some of the conceptual or inner details of Lucene: - [Changes](https://github.com/apache/lucenenet/releases/tag/): List of changes in this release. - [Migration Guide](xref:Lucene.Net.Migration.Guide): What changed in Lucene 4; how to migrate code from Lucene 3.x. -- [File Formats](xref:Lucene.Net.Codecs.Lucene46) : Guide to the supported index format used by Lucene. This can be customized by using [an alternate codec](xref:Lucene.Net.Codecs). +- [Source Stepping](xref:source-stepping): How to use the Visual Studio debugger to step into Lucene.NET source code. +- [File Formats](xref:Lucene.Net.Codecs.Lucene46): Guide to the supported index format used by Lucene. This can be customized by using [an alternate codec](xref:Lucene.Net.Codecs). - [Search and Scoring in Lucene](xref:Lucene.Net.Search): Introduction to how Lucene scores documents. - [Classic Scoring Formula](xref:Lucene.Net.Search.Similarities.TFIDFSimilarity): Formula of Lucene's classic [Vector Space](http://en.wikipedia.org/wiki/Vector_Space_Model) implementation. (look [here](xref:Lucene.Net.Search.Similarities) for other models) - [Classic QueryParser Syntax](xref:Lucene.Net.QueryParsers.Classic): Overview of the Classic QueryParser's syntax and features.