Merge pull request #347 from nzdev/v4/feature/v3-v4-api-compat

Fix  V4 compatibility with V3 API

.github/workflows/build.yml

@@ -11,7 +11,9 @@ on:
       - 'v*'
   pull_request:
     branches:
-      - '*'  
+      - 'master'
+      - 'dev'
+      - 'release/*'
 
 jobs:
   build:
@@ -35,15 +37,13 @@ jobs:
         echo ("Copyright=" + $Copyright) >> $Env:GITHUB_ENV
       shell: pwsh
 
-    - name: Setup .NET Core SDK 5.0.x
-      uses: actions/setup-dotnet@v1.7.2
+    - name: Setup dotnet
+      uses: actions/setup-dotnet@v3
       with:
-        dotnet-version: 5.0.x
-
-    - name: Setup .NET SDK 6.0.x
-      uses: actions/setup-dotnet@v2
-      with:
-        dotnet-version: 6.0.x
+        dotnet-version: | 
+          5.0.x
+          6.0.x
+          7.0.x
 
     - name: Install GitVersion
       uses: gittools/actions/gitversion/[email protected]
@@ -90,6 +90,3 @@ jobs:
       with:
         name: examine-nuget-${{ env.GitVersion_SemVer }}
         path:  ${{ github.workspace }}/_NugetOutput/*.*
-
-    - name: Publish to GitHub Packages
-      run: dotnet nuget push "${{ github.workspace }}/_NugetOutput/*.nupkg"  --api-key ${{ secrets.GITHUB_TOKEN }} --source "https://nuget.pkg.github.com/shazwazza/index.json"

README.md

@@ -62,16 +62,18 @@ Information and downloads for Examine releases
 
 ## Documentation
 
+The [documentation site is here](https://shazwazza.github.io/Examine/index.html)
+
 _**Tip**: There are many unit tests in the source code that can be used as Examples of how to do things. There is also a test web project that has plenty of examples of how to configure indexes and search them._
 
-* [Indexing](https://shazwazza.github.io/Examine/indexing)
-* [Configuration](https://shazwazza.github.io/Examine/configuration)
-* [Searching](https://shazwazza.github.io/Examine/searching)
-* [Sorting](https://shazwazza.github.io/Examine/sorting)
+* [Indexing](https://shazwazza.github.io/Examine/articles/indexing.html)
+* [Configuration](https://shazwazza.github.io/Examine/articles/configuration.html)
+* [Searching](https://shazwazza.github.io/Examine/articles/searching.html)
+* [Sorting](https://shazwazza.github.io/Examine/articles/sorting.html)
 
 ## Copyright & Licence
 
-© 2021 by Shannon Deminick
+© 2023 by Shannon Deminick
 
 This is free software and is licensed under the [Microsoft Public License (Ms-PL)](http://opensource.org/licenses/MS-PL)
 

docs/indexing.md

@@ -142,7 +142,9 @@ Data is easily deleted from the index by the unique identifier you provided in y
 
 <!-- Tabs -->
 <div class="container">
-  <input type="radio" id="tab-link-20" name="docwriting" checked />
+  <input type="radio" id="tab-link-30" name="docwriting" checked />
+  <label for="tab-link-30">V3</label>
+  <input type="radio" id="tab-link-20" name="docwriting" />
   <label for="tab-link-20">V2</label>
   <input type="radio" id="tab-link-21" name="docwriting" />
   <label for="tab-link-21">V1</label>
@@ -189,6 +191,125 @@ If using Examine with the default Lucene implementation then the `IIndex` implem
 
 You can use this event to entirely customize how the data is stored in the Lucene index, including adding custom boosting profiles, changing the `Document`'s field values or types, etc...
 
+</section>
+<section class="tab-panel" id=tab-30>
+
+### IIndex.IndexOperationComplete
+
+This event is part of the base interface `IIndex` so it is available to use on any implementation of an Examine index. This can be useful to know when an indexing operation is completed.
+
+Example of how to listen the event:
+
+```csharp
+if (!_examineManager.TryGetIndex(indexName, out var index))
+{
+    throw new ArgumentException($"Index '{indexName}' not found");
+}
+
+index.IndexOperationComplete += IndexOperationComplete;
+```
+
+```csharp
+private void IndexOperationComplete(object sender, IndexOperationEventArgs e)
+{
+    // Index operation completed
+}
+```
+
+### IIndex.TransformingIndexValues
+
+This event is part of the base interface `IIndex` so it is available to use on any implementation of an Examine index. This event allows for customizing the `ValueSet` before it is passed to the indexer to be indexed. You can use this event to add additional field values or modify existing field values.
+
+Example of how to listen the event:
+
+```csharp
+if (!_examineManager.TryGetIndex(indexName, out var index))
+{
+    throw new ArgumentException($"Index '{indexName}' not found");
+}
+
+index.TransformingIndexValues += TransformingIndexValues;
+```
+
+```csharp
+private void TransformingIndexValues(object sender, IndexingItemEventArgs e)
+{
+    // Customize the ValueSet
+}
+```
+
+### IIndex.IndexingError
+
+This event is part of the base interface `IIndex` so it is available to use on any implementation of an Examine index. This event can be used for reacting to when an error occurs during index. For example, you could add an event handler for this event to facilitate error logging.
+
+Example of how to listen the event:
+
+```csharp
+if (!_examineManager.TryGetIndex(indexName, out var index))
+{
+    throw new ArgumentException($"Index '{indexName}' not found");
+}
+
+index.IndexingError += IndexingError;
+```
+
+```csharp
+private void IndexingError(object sender, IndexingErrorEventArgs e)
+{
+    // An indexing error occored
+}
+```
+
+### LuceneIndex.DocumentWriting
+
+If using Examine with the default Lucene implementation then the `IIndex` implementation will be `LuceneIndex`. This event provides access to the Lucene `Document` object before it gets added to the Lucene Index. 
+
+You can use this event to entirely customize how the data is stored in the Lucene index, including adding custom boosting profiles, changing the `Document`'s field values or types, etc...
+
+Example of how to listen the event:
+
+```csharp
+if (!_examineManager.TryGetIndex(indexName, out var index))
+{
+    throw new ArgumentException($"Index '{indexName}' not found");
+}
+
+if (index is LuceneIndex luceneIndex){
+    luceneIndex.DocumentWriting += DocumentWriting;
+}
+```
+
+```csharp
+private void DocumentWriting(object sender, DocumentWritingEventArgs e)
+{
+    // Customize how the data is stored in the Lucene index
+}
+```
+
+### LuceneIndex.IndexCommitted
+
+If using Examine with the default Lucene implementation then the `IIndex` implementation will be `LuceneIndex`. This event is triggered when the index is commited. For example when clearing the index this event is run once when commiting. When rebuilding the event will be run once the rebuild commits a clearing of the index and when it's commiting the rebuilt index.
+
+Example of how to listen the event:
+
+```csharp
+if (!_examineManager.TryGetIndex(indexName, out var index))
+{
+    throw new ArgumentException($"Index '{indexName}' not found");
+}
+
+if (index is LuceneIndex luceneIndex){
+    luceneIndex.IndexCommitted += IndexCommited;
+}
+```
+
+```csharp
+private void IndexCommited(object sender, EventArgs e)
+{
+    // Triggered when the index is commited
+}
+```
+
 </section>
   </div>
 </div>

docs/v2/articles/indexing.md

@@ -144,16 +144,112 @@ Data is easily deleted from the index by the unique identifier you provided in y
 
 This event is part of the base interface [`IIndex`](xref:Examine.IIndex) so it is available to use on any implementation of an Examine index. This can be useful to know when an indexing operation is completed.
 
+Example of how to listen the event:
+
+```csharp
+if (!_examineManager.TryGetIndex(indexName, out var index))
+{
+    throw new ArgumentException($"Index '{indexName}' not found");
+}
+
+index.IndexOperationComplete += IndexOperationComplete;
+```
+
+```csharp
+private void IndexOperationComplete(object sender, IndexOperationEventArgs e)
+{
+    // Index operation completed
+}
+```
+
 #### [IIndex.TransformingIndexValues](xref:Examine.IIndex#Examine_IIndex_TransformingIndexValues)
 
-This event allows for customizing the [`ValueSet`](xref:Examine.ValueSet) before it is passed to the indexer to be indexed. You can use this event to add additional field values or modify existing field values.
+This event is part of the base interface [`IIndex`](xref:Examine.IIndex) so it is available to use on any implementation of an Examine index. This event allows for customizing the [`ValueSet`](xref:Examine.ValueSet) before it is passed to the indexer to be indexed. You can use this event to add additional field values or modify existing field values.
+
+Example of how to listen the event:
+
+```csharp
+if (!_examineManager.TryGetIndex(indexName, out var index))
+{
+    throw new ArgumentException($"Index '{indexName}' not found");
+}
+
+index.TransformingIndexValues += TransformingIndexValues;
+```
+
+```csharp
+private void TransformingIndexValues(object sender, IndexingItemEventArgs e)
+{
+    // Customize the ValueSet
+}
+```
 
 #### [IIndex.IndexingError](xref:Examine.IIndex#Examine_IIndex_IndexingError)
 
-This event can be used for reacting to when an error occurs during index. For example, you could add an event handler for this event to facilitate error logging.
+This event is part of the base interface [`IIndex`](xref:Examine.IIndex) so it is available to use on any implementation of an Examine index. This event can be used for reacting to when an error occurs during index. For example, you could add an event handler for this event to facilitate error logging.
+
+Example of how to listen the event:
+
+```csharp
+if (!_examineManager.TryGetIndex(indexName, out var index))
+{
+    throw new ArgumentException($"Index '{indexName}' not found");
+}
+
+index.IndexingError += IndexingError;
+```
+
+```csharp
+private void IndexingError(object sender, IndexingErrorEventArgs e)
+{
+    // An indexing error occored
+}
+```
 
 #### [LuceneIndex.DocumentWriting](xref:Examine.Lucene.Providers.LuceneIndex#Examine_Lucene_Providers_LuceneIndex_DocumentWriting)
 
 If using Examine with the default Lucene implementation then the [`IIndex`](xref:Examine.IIndex) implementation will be [`LuceneIndex`](xref:Examine.Lucene.Providers.LuceneIndex). This event provides access to the Lucene [`Document`](https://lucenenet.apache.org/docs/4.8.0-beta00016/api/core/Lucene.Net.Documents.Document.html) object before it gets added to the Lucene Index.
 
-You can use this event to entirely customize how the data is stored in the Lucene index, including adding custom boosting profiles, changing the [`Document`](https://lucenenet.apache.org/docs/4.8.0-beta00016/api/core/Lucene.Net.Documents.Document.html)'s field values or types, etc...
+You can use this event to entirely customize how the data is stored in the Lucene index, including adding custom boosting profiles, changing the [`Document`](https://lucenenet.apache.org/docs/4.8.0-beta00016/api/core/Lucene.Net.Documents.Document.html)'s field values or types, etc...
+
+Example of how to listen the event:
+
+```csharp
+if (!_examineManager.TryGetIndex(indexName, out var index))
+{
+    throw new ArgumentException($"Index '{indexName}' not found");
+}
+
+if (index is LuceneIndex luceneIndex){
+    luceneIndex.DocumentWriting += DocumentWriting;
+}
+```
+
+```csharp
+private void DocumentWriting(object sender, DocumentWritingEventArgs e)
+{
+    // Customize how the data is stored in the Lucene index
+}
+```
+
+### [LuceneIndex.IndexCommitted](xref:Examine.Lucene.Providers.LuceneIndex#Examine_Lucene_Providers_LuceneIndex_IndexCommitted)
+If using Examine with the default Lucene implementation then the [`IIndex`](xref:Examine.IIndex) implementation will be [`LuceneIndex`](xref:Examine.Lucene.Providers.LuceneIndex). This event is triggered when the index is commited. For example when clearing the index this event is run once when commiting. When rebuilding the event will be run once the rebuild commits a clearing of the index and when it's commiting the rebuilt index.
+Example of how to listen the event:
+
+```csharp
+if (!_examineManager.TryGetIndex(indexName, out var index))
+{
+    throw new ArgumentException($"Index '{indexName}' not found");
+}
+
+if (index is LuceneIndex luceneIndex){
+    luceneIndex.IndexCommitted += IndexCommited;
+}
+```
+
+```csharp
+private void IndexCommited(object sender, EventArgs e)
+{
+    // Triggered when the index is commited
+}
+```

src/Examine.Core/EmptySearchResults.cs

@@ -33,14 +33,19 @@ IEnumerator IEnumerable.GetEnumerator()
         /// <inheritdoc/>
 		public long TotalItemCount => 0;
 
+
+#pragma warning disable IDE0060 // Remove unused parameter
         /// <inheritdoc/>
         public IEnumerable<ISearchResult> Skip(int skip)
-		{
+#pragma warning restore IDE0060 // Remove unused parameter
+        {
 			return Enumerable.Empty<ISearchResult>();
 		}
 
         /// <inheritdoc/>
+#pragma warning disable IDE0060 // Remove unused parameter
         public IEnumerable<ISearchResult> SkipTake(int skip, int? take = null)
+#pragma warning restore IDE0060 // Remove unused parameter
         {
 			return Enumerable.Empty<ISearchResult>();
 		}

src/Examine.Core/Examine.Core.csproj

@@ -8,13 +8,18 @@
     <GenerateDocumentationFile>True</GenerateDocumentationFile>
     <Nullable>enable</Nullable>
     <LangVersion>9</LangVersion>
+    <NoWarn>RS0036</NoWarn>
   </PropertyGroup>
 
   <ItemGroup>
     <Content Include="..\..\assets\logo-round-small.png" Link="logo-round-small.png" Pack="true" PackagePath="" />
   </ItemGroup>
 
   <ItemGroup>
+    <PackageReference Include="Microsoft.CodeAnalysis.PublicApiAnalyzers" Version="3.3.4">
+      <PrivateAssets>all</PrivateAssets>
+      <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
+    </PackageReference>
     <PackageReference Include="Microsoft.Extensions.Logging.Abstractions" Version="6.0.3" />
     <PackageReference Include="Microsoft.Extensions.Options" Version="6.0.0" />
   </ItemGroup>