Merge pull request #46 from HeidiSteen/master

HeidiSteen · web-flow · commit 6a551384b6b0 · 2020-10-08T14:32:20.000-07:00
Readme updates for v10/v11 versions
diff --git a/README.md b/README.md
@@ -1,33 +1,57 @@
 # Azure Cognitive Search .NET Samples
 
-This repository contains C# sample code used in Azure Cognitive Search quickstarts, tutorials, and examples. All samples run on the shared (free) Azure Cognitive Search service.  
+This repository contains C# sample code used in Azure Cognitive Search quickstarts, tutorials, and examples in product documentation. Unless otherwise noted, all samples run on the shared (free) pricing tier of an Azure Cognitive Search service.  
 
-## Quickstart v11
+## Quickstart
 
-This version of the quickstart is updated to use the new Azure.Search.Documents client library (version 11) of the Azure SDK for .NET. This is a NET Core console app that uses the new library to create, load, and query an index. 
+"Day One" introduction to the fundamental tasks of working with a search index: create, load, and query. This quickstart is a .NET Core console application that outputs the status of each operation, concluding with a series of sample queries as a validation step that the index exists and contains content. The index is modeled on a subset of the Hotels dataset, widely used in Cognitive Search samples, but reduced here for readability and comprehension. 
 
-## Quickstart v10
+This sample is available in two versions:
 
-This .NET Core console app uses the Azure Cognitive Search .NET SDK (version 10) to create an index, load it with documents, and execute a few queries. The index is modeled on a subset of the Hotels dataset, reduced for readability and comprehension. Index definition and documents are included in the code.
++ **v10** uses the previous [Microsoft.Azure.Search](https://docs.microsoft.com/en-us/dotnet/api/overview/azure/search/client10) client libraries
++ **v11** uses the new [Azure.Search.Documents](https://docs.microsoft.com/dotnet/api/overview/azure/search.documents-readme) client library, highly recommended for all new projects
 
 ## Create your first app
 
-This MVC sample is a collection of projects that demonstrate a user experience using fictitious hotels data. The first project creates a basic search page. Additional projects build on the first, adding results handling, and typeahead. The index is pre-built and hosted so that you can focus on the application itself.
+This MVC sample is a collection of projects that demonstrate a user experience using fictitious hotels data. The first project creates a basic search page. Additional projects build on the first, adding pagination, autocomplete and suggested queries, and ordered results. The index is pre-built and hosted so that you can focus on the application itself.
+
+This sample is available in two versions:
+
++ **v10** uses the previous [Microsoft.Azure.Search](https://docs.microsoft.com/en-us/dotnet/api/overview/azure/search/client10) client libraries
++ **v11** uses the new [Azure.Search.Documents](https://docs.microsoft.com/dotnet/api/overview/azure/search.documents-readme) client library, highly recommended for all new projects
 
 ## Multiple data sources
 
 This .NET Core console app uses Azure Cognitive Search indexers and the .NET SDK to import data from Azure Cosmos DB and Azure Blob storage, combing data from two sources into one search index.
 
+This sample is available in two versions:
+
++ **v10** uses the previous [Microsoft.Azure.Search](https://docs.microsoft.com/en-us/dotnet/api/overview/azure/search/client10) client libraries
++ **v11** uses the new [Azure.Search.Documents](https://docs.microsoft.com/dotnet/api/overview/azure/search.documents-readme) client library, highly recommended for all new projects
+
 ## Backup and restore an index
 
-This .NET Core console app uses the .NET SDK and Azure Cognitive Search REST API to backup an index (schema and documents) to your computer and then uses the stored back up to recreate the index in a target search service that you specify. This tool is useful if you want to move an index into a different pricing tier. For example, you may use the Basic or Free pricing tier to develop your index, and then want to move it to the Standard or higher tier for production use. You can also use it to backup the index to your computer, so you can restore it at a later time, if needed.
+This .NET Core console app backs up an index (schema and documents) to your local computer and then uses the stored backup to recreate the index in a target search service that you specify. This sample can be helpful if you want to move an index into a different pricing tier. For example, you may use the Basic or Free pricing tier to develop your index, and then move it to the Standard or higher tier for production use.
+
+This sample is available in two versions:
 
-**IMPORTANT** Search indexes are different from other datastores because they are constantly ranking and scoring results and data may shift. It is possible to miss some data during data extraction. This sample code also only works for indexes with less than 100,000 documents. However, it can be amended for larger indexes. See the README in the index-backup-restore folder for more details.
++ **v10** uses the previous [Microsoft.Azure.Search](https://docs.microsoft.com/en-us/dotnet/api/overview/azure/search/client10) client libraries
++ **v11** uses the new [Azure.Search.Documents](https://docs.microsoft.com/dotnet/api/overview/azure/search.documents-readme) client library, highly recommended for all new projects
 
 ## Optimize data indexing
 
 This .NET Core console app builds off of the code used in the Quickstart and uses the Azure Cognitive Search .NET SDK to create an index, and efficiently load it with documents. The app allows users to test various batch sizes to understand the optimal batch size and then demonstrates how to efficiently upload 100,000 documents to a search index. This is done by splitting the data into batches, and spinning up several threads to upload the documents. Any failures are monitored and then retried using the exponential backoff retry strategy. The index is modeled on a subset of the Hotels dataset, reduced for readability and comprehension. Index definition and documents are included in the code.
 
+This sample is available in two versions:
+
++ **v10** uses the previous [Microsoft.Azure.Search](https://docs.microsoft.com/en-us/dotnet/api/overview/azure/search/client10) client libraries
++ **v11** uses the new [Azure.Search.Documents](https://docs.microsoft.com/dotnet/api/overview/azure/search.documents-readme) client library, highly recommended for all new projects
+
 ## AI Enrichment
 
-This .NET Core console app creates an AI enrichment pipeline consisting of an index, indexer, data source, and skillset. The skillset calls Azure Cognitive Services image analysis, natural language processing, and OCR to extract information and structure from heterogeneous blob content, making it searchable in Azure Cognitive Search.
+This .NET Core console app creates an AI enrichment pipeline consisting of an index, indexer, data source, and skillset. The skillset calls Azure Cognitive Services image analysis and OCR, and natural language processing, extract information and structure from heterogeneous blob content, making it searchable in Azure Cognitive Search.
+
+This sample is available in two versions:
+
++ **v10** uses the previous [Microsoft.Azure.Search](https://docs.microsoft.com/en-us/dotnet/api/overview/azure/search/client10) client libraries
++ **v11** uses the new [Azure.Search.Documents](https://docs.microsoft.com/dotnet/api/overview/azure/search.documents-readme) client library, highly recommended for all new projects
diff --git a/create-first-app/README.md b/create-first-app/README.md
@@ -18,24 +18,9 @@ In this sample, start with a basic search page layout and then enhance it with p
 
 This MVC sample is featured in [C# tutorial: Create your first app - Azure Cognitive Search](https://docs.microsoft.com/azure/search/tutorial-csharp-create-first-app). It's a collection of projects that demonstrate a user experience using fictitious hotels data. The first project creates a basic search page. Additional projects build on the first, adding results handling, and typeahead. The index is pre-built and hosted so that you can focus on the application itself.
 
-## Contents
-
-| File/folder | Description |
-|-------------|-------------|
-| `1-basic-search-page`       | Initial project providing the page layout. |
-| `2a-add-paging`       | Adds a vertical scroll bar and page controls |
-| `2b-add-infinite-scroll`       | Demonstrates an infinite scrolling|
-| `3-add-typeahead`       | Adds autocomplete query |
-| `4-add-facet-navigation`       | Adds a facet navigation structure backed by filtering|
-| `5-order-results`       | Adds results sorting |
-| `.gitignore` | Define what to ignore at commit time. |
-| `CONTRIBUTING.md` | Guidelines for contributing to the sample. |
-| `README.md` | This README file. |
-| `LICENSE`   | The license for the sample. |
-
 ## Prerequisites
 
-- [Visual Studio 2019](https://visualstudio.microsoft.com/downloads/)
+- [Visual Studio](https://visualstudio.microsoft.com/downloads/)
 
 In contrast with other tutorials, this one uses a read-only hotels index on an existing demo search service maintained by Microsoft. No preliminary service or index setup is required.
 
@@ -44,19 +29,28 @@ In contrast with other tutorials, this one uses a read-only hotels index on an e
 1. Clone or download this sample repository.
 1. Extract contents if the download is a zip file. Make sure the files are read-write.
 
-## Running create-first-app
+This sample is available in two versions:
 
-1. Choose which version of the client libraries to work with:
++ **v10** uses the previous [Microsoft.Azure.Search](https://docs.microsoft.com/en-us/dotnet/api/overview/azure/search/client10) client libraries
 
-   + **v10** uses the [Microsoft.Azure.Search](https://docs.microsoft.com/dotnet/api/overview/azure/search/client10) legacy client libraries. With the exception of security bug fixes, there will be no further development in this library. If you have existing search solutions that use this library, use the v10 samples to learn about the APIs.
++ **v11** uses the new [Azure.Search.Documents](https://docs.microsoft.com/dotnet/api/overview/azure/search.documents-readme) client library, highly recommended for all new projects
 
-   + **v11** uses the [Azure.Search.Documents](https://docs.microsoft.com/dotnet/api/overview/azure/search.documents-readme) library, which has been redesigned for consistency with other Azure client libraries. Moving forward, all new features will roll out in this library. If you are new to Cognitive Search, use this version in your search applications.
+## Contents
+
+| File/folder | Description |
+|-------------|-------------|
+| `1-basic-search-page`       | Initial project providing the page layout. |
+| `2a-add-paging`       | Adds a vertical scroll bar and page controls |
+| `2b-add-infinite-scroll`       | Demonstrates an infinite scrolling|
+| `3-add-typeahead`       | Adds autocomplete query |
+| `4-add-facet-navigation`       | Adds a facet navigation structure backed by filtering|
+| `5-order-results`       | Adds results sorting |
 
-1. Open the first folder: **1-basic-search-page**.
+## Run the sample
 
-1. Open the **FirstAzureSearchApp.sln** project in Visual Studio.
+1. Open a solution in Visual Studio.
 
-1. Compile and run the project.
+1. Press **F5** to compile and run the project.
 
 The solutions in this sample have template modifications. Methods in Startup.cs have been reordered, with app.UseCookiePolicy() relocated below app.UseMvc(...). This change addresses a known issue in .NET Core 2.x MVC apps where TempData is not persisted.
 
diff --git a/index-backup-restore/README.md b/index-backup-restore/README.md
@@ -28,14 +28,6 @@ Also, as an extra precaution, it is best if there are no changes being made to t
 
 **If your index has more than 100,000 documents**, this sample, as written, will not work. This is because the REST API $skip feature, that is used for paging, has a 100K document limit. However, you can work around this limitation by adding code to iterate over, and filter on, a facet with less that 100K documents per facet value.
 
-| File/folder | Description |
-|-------------|-------------|
-| `AzureSearchBackupRestoreIndex.sln`  | .NET Core console solution file |
-| `AzureSearchBackupRestoreIndex`  | Source files |
-| `CONTRIBUTING.md` | Guidelines for contributing to the sample. |
-| `README.md` | This README file. |
-| `LICENSE`   | The license for the sample. |
-
 ## Prerequisites
 
 - [Visual Studio](https://visualstudio.microsoft.com/downloads/)
@@ -46,11 +38,18 @@ Also, as an extra precaution, it is best if there are no changes being made to t
 1. Clone or download this sample repository.
 1. Extract contents if the download is a zip file. Make sure the files are read-write.
 
-### Running the backup-restore application
+This sample is available in two versions:
+
++ **v10** uses the previous [Microsoft.Azure.Search](https://docs.microsoft.com/en-us/dotnet/api/overview/azure/search/client10) client libraries
+
++ **v11** uses the new [Azure.Search.Documents](https://docs.microsoft.com/dotnet/api/overview/azure/search.documents-readme) client library, highly recommended for all new projects
+
+## Run the sample
 
 [!NOTE] In this application the term "source" identifies the search service and index and that you are backing up. The term "target" identifies the search service and index that will contain the restored (copied) index
 
 1. Open the AzureSearchBackupRestoreIndex.sln project in Visual Studio.
+
 1. By default, this application will copy the source index to the target search service using the target index name you provide. 
     - If you only want to back up the index and not restore it immediately, do this:
         - Comment out the code in the **Main** method after the **BackupIndexAndDocuments** method call.
diff --git a/multiple-data-sources/README.md b/multiple-data-sources/README.md
@@ -20,20 +20,9 @@ Demonstrates Azure Cognitive Search indexing from Azure Cosmos DB and Azure Blob
 
 This .NET Core console application is featured in [C# Tutorial: Combine data from multiple data sources in one search index](https://docs.microsoft.com/azure/search/tutorial-multiple-data-sources). When you run the program, a console window emits output messages for each step. This sample runs on an Azure Cognitive Search service, importing content from Azure Cosmos DB and Azure Blob storage, using services and connection information that you provide.
 
-## Contents
-
-| File/folder | Description |
-|-------------|-------------|
-| `AzureSearchMultipleDataSources.sln`       | .NET Core console solution file |
-| `src`       | Source files |
-| `.gitignore` | Define what to ignore at commit time. |
-| `CONTRIBUTING.md` | Guidelines for contributing to the sample. |
-| `README.md` | This README file. |
-| `LICENSE`   | The license for the sample. |
-
 ## Prerequisites
 
-- [Visual Studio 2019](https://visualstudio.microsoft.com/downloads/)
+- [Visual Studio](https://visualstudio.microsoft.com/downloads/)
 - [Azure Cognitive Search service](https://docs.microsoft.com/azure/search/search-create-service-portal)
 - [Azure Cosmos DB](https://docs.microsoft.com/azure/cosmos-db/create-cosmosdb-resources-portal)
 - [Azure Storage](https://docs.microsoft.com/azure/storage/common/storage-quickstart-create-account)
@@ -59,9 +48,15 @@ This .NET Core console application is featured in [C# Tutorial: Combine data fro
    + Select this container, click **Upload**, and then upload all of the JSON files in the *src/blobs* folder, ranging from *Rooms1.json* through *Rooms15.json*. These files contain room details for each of the seven hotels.
    + In the left pane, go to **Settings > Access Keys** and get the connection string for key1. It also goes into the project's *appsettings.json* file.
 
+This sample is available in two versions:
+
++ **v10** uses the previous [Microsoft.Azure.Search](https://docs.microsoft.com/en-us/dotnet/api/overview/azure/search/client10) client libraries
+
++ **v11** uses the new [Azure.Search.Documents](https://docs.microsoft.com/dotnet/api/overview/azure/search.documents-readme) client library, highly recommended for all new projects
+
 ## Run the sample
 
-1. Open the sample solution in Visual Studio 2019.
+1. Open the sample solution in Visual Studio.
 
 1. Edit the  *appsettings.json* and fill in the appropriate account names, keys, and connection strings:
 
diff --git a/optimize-data-indexing/README.md b/optimize-data-indexing/README.md
@@ -33,16 +33,6 @@ The index is modeled on a subset of the Hotels dataset, reduced for readability
 > [!NOTE]
 > Network transfer speeds can be a limiting factor when indexing data. You might get a better sense of indexing efficiency if your Visual Studio client is on an [Azure virtual machine](https://azure.microsoft.com/services/virtual-machines/) in the cloud in the same location as Azure Cognitive Search. The [Data Science VM](https://azure.microsoft.com/services/virtual-machines/data-science-virtual-machines/) is a good choice because Visual Studio is preinstalled.
 
-## Contents
-
-| File/folder | Description |
-|-------------|-------------|
-| `OptimizeDataIndexing.sln`       | .NET Core console solution file |
-| `OptimizeDataIndexing`       | Source files |
-| `CONTRIBUTING.md` | Guidelines for contributing to the sample. |
-| `README.md` | This README file. |
-| `LICENSE`   | The license for the sample. |
-
 ## Prerequisites
 
 - [Visual Studio](https://visualstudio.microsoft.com/downloads/)
@@ -53,7 +43,13 @@ The index is modeled on a subset of the Hotels dataset, reduced for readability
 1. Clone or download this sample repository.
 1. Extract contents if the download is a zip file. Make sure the files are read-write.
 
-### Running the solution
+This sample is available in two versions.
+
++ **v10** uses the previous [Microsoft.Azure.Search](https://docs.microsoft.com/en-us/dotnet/api/overview/azure/search/client10) client libraries
+
++ **v11** uses the new [Azure.Search.Documents](https://docs.microsoft.com/dotnet/api/overview/azure/search.documents-readme) client library, highly recommended for all new projects
+
+## Run the sample
 
 1. Open the OptimizeDataIndexing.sln project in Visual Studio.
 1. Update appsetting.json to use your search service name and admin api-key. The admin key is necessary for creating objects and loading data.
diff --git a/quickstart/README.md b/quickstart/README.md
diff --git a/tutorial-ai-enrichment/README.md b/tutorial-ai-enrichment/README.md
