Merge branch 'dev' into netcore

# Conflicts: # appveyor.build.yml # appveyor.yml # azure-pipelines.yml # build/Build-Release.ps1 # build/build.xml # src/Examine.AzureDirectory/Properties/AssemblyInfo.cs # src/Examine.AzureDirectory/app.config # src/Examine.Lucene/Examine.Lucene.csproj # src/Examine.Lucene/Logging/ILoggingService.cs # src/Examine.Lucene/Logging/LogEntry.cs # src/Examine.Lucene/Logging/LogLevel.cs # src/Examine.Lucene/Logging/TraceLoggingService.cs # src/Examine.Lucene/LuceneEngine/LuceneSearchResults.cs # src/Examine.Lucene/LuceneEngine/LuceneSearchResultsBase.cs # src/Examine.Lucene/LuceneEngine/Providers/ErrorLoggingConcurrentMergeScheduler.cs # src/Examine.Lucene/LuceneEngine/Providers/LuceneIndex.cs # src/Examine.Lucene/LuceneEngine/Search/LuceneSearchQuery.cs # src/Examine.Lucene/Properties/AssemblyInfo.cs # src/Examine.Lucene/Search/IFieldSelectableOrdering.cs # src/Examine.Lucene/Search/QueryExtensions.cs # src/Examine.Lucene/Search/SearchResultExtensions.cs # src/Examine.Lucene/SearchResultsBase.cs # src/Examine.Lucene/packages.config # src/Examine.Test/App.config # src/Examine.Test/Examine.Test.csproj # src/Examine.Web.Demo/Web.config # src/SolutionInfo.cs
Shazwazza · Apr 29, 2021 · 7812e27 · 7812e27
2 parents 63a35d7 + 0e735ed
commit 7812e27
Show file tree

Hide file tree

Showing 75 changed files with 2,864 additions and 1,038 deletions.
diff --git a/.github/FUNDING.yml b/.github/FUNDING.yml
@@ -1,6 +1,6 @@
 # These are supported funding model platforms
 
-github: github: [shazwazza]
+github: [shazwazza]
 patreon: # Replace with a single Patreon username
 open_collective: # Replace with a single Open Collective username
 ko_fi: # Replace with a single Ko-fi username

diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
@@ -0,0 +1,58 @@
+name: Examine Build
+
+on: [push, pull_request]
+
+jobs:
+  build:
+
+    runs-on: windows-latest
+
+    env:
+      Solution_File: src\Examine.sln
+      Test_Folder: src\Examine.Test
+      Configuration: Release
+
+    steps:
+    - name: Checkout
+      uses: actions/checkout@v2
+      with:
+        fetch-depth: 0
+
+    - name: Create copyright value
+      run: |
+        $Copyright = "Copyright " + [char]0x00A9 + " Shannon Deminick " + (Get-Date).year
+        echo ("Copyright=" + $Copyright) >> $Env:GITHUB_ENV
+      shell: pwsh
+
+    - name: Add MSBuild to PATH
+      uses: microsoft/[email protected]
+
+    - uses: nuget/setup-nuget@v1
+      with:
+        nuget-version: 'latest'
+
+    - name: Install GitVersion
+      uses: gittools/actions/gitversion/[email protected]
+      with:
+        versionSpec: '5.x'
+
+    - name: Determine Version
+      uses: gittools/actions/gitversion/[email protected]
+
+    - name: Nuget Restore
+      run: nuget restore $env:Solution_File
+
+    - name: MSBuild Clean
+      run: msbuild $env:Solution_File /p:Configuration=Release /t:Clean
+
+    - name: MSBuild Build
+      run: msbuild $env:Solution_File /p:Configuration=$env:Configuration
+
+    - name: Test
+      run: dotnet test "${{ env.Test_Folder }}\bin\${{ env.Configuration }}\Examine.Test.dll" --no-build --verbosity normal --results-directory ${{ github.workspace }}\_TestResults  --logger "trx;logfilename=tests.trx"
+
+    - uses: actions/upload-artifact@v2  # upload test results
+      if: success() || failure()        # run this step even if previous step failed
+      with:
+        name: test-results
+        path:  ${{ github.workspace }}\_TestResults\tests.trx
diff --git a/.github/workflows/test-report.yml b/.github/workflows/test-report.yml
@@ -0,0 +1,16 @@
+name: 'Test Report'
+on:
+  workflow_run:
+    workflows: ['Examine Build']                     # runs after CI workflow
+    types:
+      - completed
+jobs:
+  report:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: dorny/test-reporter@v1
+      with:
+        artifact: test-results            # artifact name
+        name: Publish Tests               # Name of the check run which will be created
+        path: '*.trx'                     # Path to test results (inside artifact .zip)
+        reporter: dotnet-trx              # Format of test results
diff --git a/GitVersion.yml b/GitVersion.yml
@@ -0,0 +1,30 @@
+next-version: 1.0
+assembly-versioning-scheme: MajorMinorPatch
+assembly-file-versioning-scheme: MajorMinorPatchTag
+assembly-informational-format: '{InformationalVersion}'
+mode: ContinuousDelivery
+increment: Inherit
+continuous-delivery-fallback-tag: ci
+tag-prefix: '[vV]'
+major-version-bump-message: '\+semver:\s?(breaking|major)'
+minor-version-bump-message: '\+semver:\s?(feature|minor)'
+patch-version-bump-message: '\+semver:\s?(fix|patch)'
+no-bump-message: '\+semver:\s?(none|skip)'
+legacy-semver-padding: 4
+build-metadata-padding: 4
+commits-since-version-source-padding: 4
+commit-message-incrementing: Enabled
+commit-date-format: 'yyyy-MM-dd'
+ignore:
+  sha: []
+  commits-before: 2020-12-21T00:00:00
+merge-message-formats: {}
+branches:
+  main:
+    regex: ^master(\-0\.x)?$|^main(\-0\.x)?$
+    source-branches: []
+  develop:
+    regex: ^dev(elop)?(ment)?(\-0\.x)?$
+    source-branches:
+    - main
+
diff --git a/README.md b/README.md
@@ -1,6 +1,4 @@
-[![Build Status](https://shazwazza.visualstudio.com/Examine/_apis/build/status/Shazwazza.Examine?branchName=master)](https://shazwazza.visualstudio.com/Examine/_build/latest?definitionId=4&branchName=master)
-
-[![Build status](https://ci.appveyor.com/api/projects/status/j4o4finsu8xs45r1?svg=true)](https://ci.appveyor.com/project/Shandem/examine)
+![Nuget](https://img.shields.io/nuget/v/Examine) [![Examine Build](https://github.com/Shazwazza/Examine/actions/workflows/build.yml/badge.svg)](https://github.com/Shazwazza/Examine/actions/workflows/build.yml) [![Build Status](https://dev.azure.com/shazwazza/Examine/_apis/build/status/Shazwazza.Examine?branchName=dev)](https://dev.azure.com/shazwazza/Examine/_build/latest?definitionId=4&branchName=dev) [![Build status](https://ci.appveyor.com/api/projects/status/j4o4finsu8xs45r1?svg=true)](https://ci.appveyor.com/project/Shandem/examine)
 
 Examine
 ===

diff --git a/azure-pipelines.yml b/azure-pipelines.yml
@@ -61,4 +61,4 @@ steps:
     command: 'push'
     packagesToPush: '$(Build.ArtifactStagingDirectory)/**/*.nupkg;!$(Build.ArtifactStagingDirectory)/**/*.symbols.nupkg'
     nuGetFeedType: 'internal'
-    publishVstsFeed: 'd11973ab-03e9-497f-bc94-e3f06abceea2/c8782af5-9b38-42ea-bb11-2dd85542c3bd'
+    publishVstsFeed: 'Examine/Examine-Beta'
diff --git a/build/Build-Release.ps1 b/build/Build-Release.ps1
@@ -62,7 +62,7 @@ $SolutionInfoPath = Join-Path -Path $SolutionRoot -ChildPath "SolutionInfo.cs"
 $Copyright = "Copyright " + [char]0x00A9 + " Shannon Deminick " + (Get-Date).year
 (gc -Path $SolutionInfoPath) `
 	-replace "(?<=AssemblyCopyright\(`").*(?=`"\))", $Copyright |
-	sc -Path $SolutionInfoPath -Encoding UTF8
+	Set-Content -Path $SolutionInfoPath -Encoding UTF8
 
 $SolutionPath = Join-Path -Path $SolutionRoot -ChildPath "Examine.sln"
 
@@ -87,11 +87,11 @@ foreach($project in $root.ChildNodes) {
 
 		(gc -Path $projectAssemblyInfo) `
 			-replace "(?<=Version\(`")[.\d]*(?=`"\))", "$projectVersion.0" |
-			sc -Path $projectAssemblyInfo -Encoding UTF8
+			Set-Content -Path $projectAssemblyInfo -Encoding UTF8
 
 		(gc -Path $projectAssemblyInfo) `
 			-replace "(?<=AssemblyInformationalVersion\(`")[.\w-]*(?=`"\))", $project.version |
-			sc -Path $projectAssemblyInfo -Encoding UTF8
+			Set-Content -Path $projectAssemblyInfo -Encoding UTF8
 	}
 }
 

diff --git a/docs/Gemfile b/docs/Gemfile
@@ -36,3 +36,4 @@ end
 # Performance-booster for watching directories on Windows
 gem "wdm", "~> 0.1.1", :install_if => Gem.win_platform?
 
+gem "kramdown-parser-gfm"
diff --git a/docs/Gemfile.lock b/docs/Gemfile.lock
@@ -4,24 +4,24 @@ GEM
     addressable (2.7.0)
       public_suffix (>= 2.0.2, < 5.0)
     colorator (1.1.0)
-    concurrent-ruby (1.1.5)
+    concurrent-ruby (1.1.6)
     em-websocket (0.5.1)
       eventmachine (>= 0.12.9)
       http_parser.rb (~> 0.6.0)
     eventmachine (1.2.7)
-    ffi (1.11.1)
+    ffi (1.13.1)
     forwardable-extended (2.6.0)
     http_parser.rb (0.6.0)
     i18n (0.9.5)
       concurrent-ruby (~> 1.0)
-    jekyll (3.8.6)
+    jekyll (3.9.0)
       addressable (~> 2.4)
       colorator (~> 1.0)
       em-websocket (~> 0.5)
       i18n (~> 0.7)
       jekyll-sass-converter (~> 1.0)
       jekyll-watch (~> 2.0)
-      kramdown (~> 1.14)
+      kramdown (>= 1.17, < 3)
       liquid (~> 4.0)
       mercenary (~> 0.3.3)
       pathutil (~> 0.9)
@@ -43,26 +43,32 @@ GEM
       jekyll-target-blank
     jekyll-watch (2.2.1)
       listen (~> 3.0)
-    kramdown (1.17.0)
+    kramdown (2.3.0)
+      rexml
+    kramdown-parser-gfm (1.1.0)
+      kramdown (~> 2.0)
     liquid (4.0.3)
-    listen (3.2.0)
+    listen (3.2.1)
       rb-fsevent (~> 0.10, >= 0.10.3)
       rb-inotify (~> 0.9, >= 0.9.10)
     mercenary (0.3.6)
-    mini_portile2 (2.4.0)
+    mini_portile2 (2.5.0)
     minima (2.5.1)
       jekyll (>= 3.5, < 5.0)
       jekyll-feed (~> 0.9)
       jekyll-seo-tag (~> 2.1)
-    nokogiri (1.10.8)
-      mini_portile2 (~> 2.4.0)
+    nokogiri (1.11.1)
+      mini_portile2 (~> 2.5.0)
+      racc (~> 1.4)
     pathutil (0.16.2)
       forwardable-extended (~> 2.6)
-    public_suffix (4.0.1)
-    rb-fsevent (0.10.3)
-    rb-inotify (0.10.0)
+    public_suffix (4.0.5)
+    racc (1.5.2)
+    rb-fsevent (0.10.4)
+    rb-inotify (0.10.1)
       ffi (~> 1.0)
-    rouge (3.12.0)
+    rexml (3.2.4)
+    rouge (3.21.0)
     safe_yaml (1.0.5)
     sass (3.7.4)
       sass-listen (~> 4.0.0)
@@ -83,10 +89,11 @@ DEPENDENCIES
   jekyll-feed (~> 0.11)
   jekyll-readme-index (~> 0.2.0)
   jekyll-theme-cayman-blog
+  kramdown-parser-gfm
   minima (~> 2.5)
   tzinfo (~> 1.2)
   tzinfo-data
   wdm (~> 0.1.1)
 
 BUNDLED WITH
-   2.0.2
+   2.1.2
diff --git a/docs/index.md b/docs/index.md
@@ -5,7 +5,7 @@
 layout: default
 ---
 
-Examine
+Examine Documentation
 ===
 
 ## What is Examine?

diff --git a/docs/indexing.md b/docs/indexing.md
@@ -110,6 +110,25 @@ myIndex.IndexItem(new ValueSet(
     }));
 ```
 
+### Synchronously
+
+Be default all indexing is done asynchronously. If you need to run indexing synchronously you should create a synchronous scope. This is for instance a necessary step for unit tests.
+
+```cs
+using (myIndex.ProcessNonAsync())
+{
+    myIndex.IndexItem(new ValueSet(
+        "SKU987",
+        "Product",             
+        new Dictionary<string, object>()
+        {
+            {"Name", "USB-C Cable" },
+            {"Brand", "Cablez-R-Us" },
+            {"Price", 19.99}  // non-string value
+        }));
+}
+```
+
 ## Events
 
-_TODO: Fill this in..._
+_TODO: Fill this in..._
diff --git a/docs/sorting.md b/docs/sorting.md
@@ -13,7 +13,7 @@ _**Tip**: There are many examples of sorting in the [`FluentApiTests` source cod
 
 ## Score
 
-_TODO: Fill this in..._
+By default search results are ordered by Score descending so there's nothing specific that needs to be done to support this. If you use a different sorting operation then the `Score` value will be 0 for all results.
 
 ## Custom sorting
 
@@ -25,4 +25,36 @@ _TODO: Fill this in..._
 
 ## Paging
 
-_TODO: Fill this in..._
+There's a [blog post writeup here](https://shazwazza.com/post/paging-with-examine/) on how to properly page with Examine (and Lucene).
+
+There are 2 important parts to this:
+
+* The [Skip](https://github.com/Shazwazza/Examine/blob/master/src/Examine/ISearchResults.cs#L11) method on the `ISearchResults` object
+* The [Search](https://github.com/Shazwazza/Examine/blob/master/src/Examine/Providers/BaseSearchProvider.cs#L22) overload on the `BaseSearchProvider` where you can specify `maxResults`
+
+`ISearchResults.Skip` is very different from the Linq Skip method so you need to be sure you are using the `Skip` method on the `ISearchResults` object. This tells Lucene to skip over a specific number of results without allocating the result objects. If you use Linq’s Skip method on the underlying `IEnumerable<SearchResult>` of `ISearchResults`, this will allocate all of the result objects and then filter them in memory which is what you don’t want to do.
+
+Lucene isn't perfect for paging because it doesn’t natively support the Linq equivalent to "Skip/Take" _(UPDATE: In an upcoming Examine version, it can natively support this!)_. It understands Skip (as above) but doesn't understand Take, instead it only knows how to limit the max results so that it doesn’t allocate every result, most of which you would probably not need when paging.
+
+With the combination of `ISearchResult.Skip` and `maxResults`, we can tell Lucene to:
+
+* Skip over a certain number of results without allocating them and tell Lucene
+* only allocate a certain number of results after skipping
+
+### Example
+
+```cs
+//for example purposes, we want to show page #4 (which is pageIndex of 3)
+var pageIndex = 3;   
+//for this example, the page size is 10 items
+var pageSize = 10;
+var searchResult = searchProvider.Search(criteria, 
+   //don't return more results than we need for the paging
+   //this is the 'trick' - we need to load enough search results to fill
+   //all pages from 1 to the current page of 4
+   maxResults: pageSize*(pageIndex + 1));
+//then we use the Skip method to tell Lucene to not allocate search results
+//for the first 3 pages
+var pagedResults = searchResult.Skip(pageIndex*pageSize);
+var totalResults = searchResult.TotalItemCount;
+```
diff --git a/src/AssemblyCopyright.cs b/src/AssemblyCopyright.cs
@@ -0,0 +1,4 @@
+using System;
+using System.Reflection;
+
+[assembly: AssemblyCopyright("Copyright © Shannon Deminick 2021")]
diff --git a/src/AssemblyCopyright.tt b/src/AssemblyCopyright.tt
@@ -0,0 +1,5 @@
+<#@ template language="C#" #>
+using System;
+using System.Reflection;
+
+[assembly: AssemblyCopyright("Copyright <#= "\u00a9" #> Shannon Deminick <#=DateTime.Now.Year#>")]
Original file line number	Diff line number	Diff line change
Expand Up		@@ -36,3 +36,4 @@ end
		# Performance-booster for watching directories on Windows
		gem "wdm", "~> 0.1.1", :install_if => Gem.win_platform?

		gem "kramdown-parser-gfm"
-Original file line number
+Diff line change
@@ Expand Up / @@ -5,7 +5,7 @@ @@
     layout: default
     ---
-    Examine
+    Examine Documentation
     ===
     ## What is Examine?
@@ Expand Down @@