Skip to content

Commit

Permalink
Azure Search Sample Readme for C#
Browse files Browse the repository at this point in the history
  • Loading branch information
@JuanAr
JuanAr committed Sep 21, 2016
1 parent 3c30206 commit e763980
Show file tree
Hide file tree
Showing 17 changed files with 348 additions and 29 deletions.
137 changes: 137 additions & 0 deletions CSharp/Search/JobListingBot/azuredeploy.json
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,137 @@
{
"$schema": "http://schema.management.azure.com/schemas/2014-04-01-preview/deploymentTemplate.json#",
"contentVersion": "1.0.0.0",
"parameters": {
"siteName": {
"defaultValue": "BotBuilder-Samples",
"type": "string"
},
"hostingPlanName": {
"type": "string"
},
"siteLocation": {
"type": "string"
},
"sku": {
"type": "string",
"allowedValues": [
"Free",
"Shared",
"Basic",
"Standard"
],
"defaultValue": "Free"
},
"workerSize": {
"type": "string",
"allowedValues": [
"0",
"1",
"2"
],
"defaultValue": "0"
},
"repoUrl": {
"type": "string"
},
"branch": {
"type": "string"
},
"Project": {
"type": "string",
"defaultValue": "CSharp/Search/JobListingBot"
},
"MicrosoftAppId": {
"type": "string"
},
"MicrosoftAppPassword": {
"type": "string"
},
"SearchDialogsServiceName": {
"type": "string",
"defaultValue": "azs-playground"
},
"SearchDialogsServiceKey": {
"type": "string",
"defaultValue": "512C4FBA9EED64A31A1052CFE3F7D3DB"
},
"SearchDialogsIndexName": {
"type": "string",
"defaultValue": "nycjobs"
}
},
"resources": [
{
"apiVersion": "2014-06-01",
"name": "[parameters('hostingPlanName')]",
"type": "Microsoft.Web/serverFarms",
"location": "[parameters('siteLocation')]",
"properties": {
"name": "[parameters('hostingPlanName')]",
"sku": "[parameters('sku')]",
"workerSize": "[parameters('workerSize')]",
"numberOfWorkers": 1
}
},
{
"apiVersion": "2014-06-01",
"name": "[parameters('siteName')]",
"type": "Microsoft.Web/Sites",
"location": "[parameters('siteLocation')]",
"dependsOn": [
"[concat('Microsoft.Web/serverFarms/', parameters('hostingPlanName'))]"
],
"tags": {
"[concat('hidden-related:', resourceGroup().id, '/providers/Microsoft.Web/serverfarms/', parameters('hostingPlanName'))]": "empty"
},
"properties": {
"name": "[parameters('siteName')]",
"serverFarm": "[parameters('hostingPlanName')]"
},
"resources": [
{
"apiVersion": "2014-04-01",
"type": "config",
"name": "web",
"dependsOn": [
"[concat('Microsoft.Web/Sites/', parameters('siteName'))]"
],
"properties": {
"appSettings": [
{
"name": "Project",
"value": "[parameters('Project')]"
},
{
"name": "MicrosoftAppId",
"value": "[parameters('MicrosoftAppId')]"
},
{
"name": "MicrosoftAppPassword",
"value": "[parameters('MicrosoftAppPassword')]"
},
{
"name": "MicrosoftBingMapsKey",
"value": "[parameters('MicrosoftBingMapsKey')]"
}
]
}
},
{
"apiVersion": "2014-04-01",
"name": "web",
"type": "sourcecontrols",
"dependsOn": [
"[resourceId('Microsoft.Web/Sites', parameters('siteName'))]",
"[concat('Microsoft.Web/Sites/', parameters('siteName'), '/config/web')]"
],
"properties": {
"RepoUrl": "[parameters('repoUrl')]",
"branch": "[parameters('branch')]",
"IsManualIntegration": true
}
}
]
}
]
}
96 changes: 70 additions & 26 deletions CSharp/Search/README.md
View file
Original file line number Diff line number Diff line change
@@ -1,35 +1,79 @@
# Search Dialogs Sample
# Azure Search Samples

Depending on the nature any given bot, sometimes you want to present structured dialogs that take users through tight paths, while in other cases you want to
Depending on the nature of any given bot, sometimes you want to present structured dialogs that take users through tight paths, while in other cases you want to
help users navigate a large amount of content. In many cases you'll have a mix of dialogs of both kinds in a single bot.

These samples illustrate how to approach dialogs that need to help the user navigate large amounts of content, creating a data-driven exploration experience.
We model content as a catalog of items where each item has several attributes we may want to use for navigation, keyword search or display.
These samples illustrate how to approach dialogs that need to help the user navigate large amounts of content, creating a data-driven exploration experience.

We use [Azure Search](https://azure.microsoft.com/en-us/services/search/) as the backend for these dialogs. This is an Azure service that offers most of the
pieces of functionality we needed, including keyword search, built-in linguistics, custom scoring, faceted navigation and more. Azure Search can also index
content from various sources (Azure SQL DB, DocumentDB, Blob Storage, Table Storage), supports "push" indexing for other sources of data, and can crack open
PDFs, Office documents and other formats containing unstructured data. The content catalog goes into an Azure Search index, which we can then query from
dialogs.
Content is modeled as a catalog of items where each item has several attributes that may be used for navigation, keyword search or display.

We included a few different dialogs that are ready to use directly, or can be subtyped to override various pieces of functionality as needed:
* SearchSelectRefinerDialog helps users pick a refiner (facet). It's a simple wrapper around a "choice" prompt dialog that can use a shared instance of
SearchQueryBuilder to ensure you don't prompt users for a field you already refined on.
* SearchRefineDialog allows users to see different values for a given field and select one. This is typically used for filtering later on but can be applied
to any case where you want to list distinct values for a given field in the catalog and let the user pick one.
* SearchDialog offers a complete keyword search + refine experience over a search index, and uses the other search dialogs as building blocks. Users can explore
the catalog by refining (using facets) and by using keyword search. They can also select items and review their selection. At the end of this dialog a list of
one or more selected items is returned. You'll need to subtype this class and at a minimum override GetTopRefiners() (to list refiners (facets) to expore) and
ToSearchHit() (to convert your index entries into a common representation that can be rendered).
| Real Estate Sample | Job Listing Sample|
|--------------------|-------------------|
|[![Deploy to Azure][Deploy Button]][Deploy CSharp/Search/RealEstateBot]|[![Deploy to Azure][Deploy Button]][Deploy CSharp/Search/JobListingBot]|

To stitch together multiple instances of these dialogs and have filters and other search options carry over, you can use a shared instance of
SearchQueryBuilder, which captures all the search-related state.

[Deploy Button]: https://azuredeploy.net/deploybutton.png
[Deploy CSharp/Search/RealEstateBot]: https://azuredeploy.net?ptmpl=CSharp/Search/RealEstateBot/azuredeploy.json
[Deploy CSharp/Search/JobListingBot]: https://azuredeploy.net?ptmpl=CSharp/Search/JobListingBot/azuredeploy.json

### Prerequisites

The minimum prerequisites to run this sample are:
* The latest update of Visual Studio 2015. You can download the community version [here](http://www.visualstudio.com) for free.
* The Bot Framework Emulator. To install the Bot Framework Emulator, download it from [here](https://aka.ms/bf-bc-emulator). Please refer to [this documentation article](https://docs.botframework.com/en-us/csharp/builder/sdkreference/gettingstarted.html#emulator) to know more about the Bot Framework Emulator.

### Azure Search

The samples use [Azure Search](https://azure.microsoft.com/en-us/services/search/) as the backend for these dialogs. This is an Azure service that offers most of the needed pieces of functionality, including keyword search, built-in linguistics, custom scoring, faceted navigation and more. Azure Search can also index content from various sources (Azure SQL DB, DocumentDB, Blob Storage, Table Storage), supports "push" indexing for other sources of data, and can crack open PDFs, Office documents and other formats containing unstructured data. The content catalog goes into an Azure Search index, which we can then query from dialogs.

> As a good practice, all the Azure Search specific components are implemented in the [Search.Azure](Search.Azure/) project while implementation agnostic interfaces and models can be found in the [Search.Contracts](Search.Contracts/) project.
### Dialogs

The samples include a few different dialogs that are ready to use directly, or can be subtyped to override various pieces of functionality as needed:
* [SearchSelectRefinerDialog](Search.Dialogs/SearchSelectRefinerDialog.cs) helps users pick a refiner (facet). It's a simple wrapper around a "choice" prompt dialog that can use a shared instance of SearchQueryBuilder to ensure you don't prompt users for a field you already refined on.
* [SearchRefineDialog](/Search.Dialogs/SearchRefineDialog.cs) allows users to see different values for a given field and select one. This is typically used for filtering later on but can be applied to any case where you want to list distinct values for a given field in the catalog and let the user pick one.
* [SearchDialog](Search.Dialogs/SearchDialog.cs) offers a complete keyword search + refine experience over a search index, and uses the other search dialogs as building blocks. Users can explore the catalog by refining (using facets) and by using keyword search. They can also select items and review their selection. At the end of this dialog a list of one or more selected items is returned. You'll need to subtype this class and at a minimum override GetTopRefiners() (to list refiners (facets) to expore) and ToSearchHit() (to convert your index entries into a common representation that can be rendered).

> You can find these dialogs in the [Search.Dialogs](Search.Dialogs/) project which is ready to reuse in your own bot.
To stitch together multiple instances of these dialogs and have filters and other search options carry over, you can use a shared instance of [SearchQueryBuilder](Search.Contracts/Models/SearchQueryBuilder.cs), which captures all the search-related state.

### Samples

We included two samples here:
1. RealEstateBot is a bot for exploring a real estate catalog. It starts by taking an arbitrary set of keywords. From there you can go back and forth between
keyword search and refinement using region, city and type of property. You can pick one or more properties and at the end you'll get a list of your choices
(a real bot would probably contact your agent with your elections, or send you a summary email for future reference).
2. JobListingBot is a bot for browing a catalog of job offerings. It starts by asking for a top-level refinement, a useful things to do in order to save
users from an initial open-ended interation with the bot where they don't know what they can say.

All samples target a shared, ready-to-use Azure Search service, so you don't need to provision your own to try these out.
1. RealEstateBot is a bot for exploring a real estate catalog.
It starts by taking an arbitrary set of keywords.

| Emulator | Facebook | Skype |
|----------|-------|----------|
|![Search](images/realstate-keywords-emulator.png)|![Search](images/realstate-keywords-facebook.png)|![Search](images/realstate-keywords-skype.png)|

From there you can go back and forth between keyword search and refinement using region, city and type of property.

| Emulator | Facebook | Skype |
|----------|-------|----------|
|![Search](images/realstate-refine-emulator.png)|![Search](images/realstate-refine-facebook.png)|![Search](images/realstate-refine-skype.png)|

You can pick one or more properties and at the end you'll get a list of your choices (a real bot would probably contact your agent with your elections, or send you a summary email for future reference).

| Emulator | Facebook | Skype |
|----------|-------|----------|
|![Search](images/realstate-pick-emulator.png)|![Search](images/realstate-pick-facebook.png)|![Search](images/realstate-pick-skype.png)|

2. JobListingBot is a bot for browing a catalog of job offerings.
It starts by asking for a top-level refinement, a useful things to do in order to save users from an initial open-ended interation with the bot where they don't know what they can say.

| Emulator | Facebook | Skype |
|----------|-------|----------|
|![Search](images/joblisting-refine-emulator.png)|![Search](images/joblisting-refine-facebook.png)|![Search](images/joblisting-refine-skype.png)|

> All samples target a shared, ready-to-use Azure Search service, so you don't need to provision your own to try these out.
### More Information

To get more information about how to get started in Bot Builder for .NET please review the following resources:

* [Dialogs](https://docs.botframework.com/en-us/csharp/builder/sdkreference/dialogs.html)
* [Azure Search](https://azure.microsoft.com/en-us/services/search/)
137 changes: 137 additions & 0 deletions CSharp/Search/RealEstateBot/azuredeploy.json
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,137 @@
{
"$schema": "http://schema.management.azure.com/schemas/2014-04-01-preview/deploymentTemplate.json#",
"contentVersion": "1.0.0.0",
"parameters": {
"siteName": {
"defaultValue": "BotBuilder-Samples",
"type": "string"
},
"hostingPlanName": {
"type": "string"
},
"siteLocation": {
"type": "string"
},
"sku": {
"type": "string",
"allowedValues": [
"Free",
"Shared",
"Basic",
"Standard"
],
"defaultValue": "Free"
},
"workerSize": {
"type": "string",
"allowedValues": [
"0",
"1",
"2"
],
"defaultValue": "0"
},
"repoUrl": {
"type": "string"
},
"branch": {
"type": "string"
},
"Project": {
"type": "string",
"defaultValue": "CSharp/Search/RealEstateBot"
},
"MicrosoftAppId": {
"type": "string"
},
"MicrosoftAppPassword": {
"type": "string"
},
"SearchDialogsServiceName": {
"type": "string",
"defaultValue": "realestate"
},
"SearchDialogsServiceKey": {
"type": "string",
"defaultValue": "82BCF03D2FC9AC7F4E9D7DE1DF3618A5"
},
"SearchDialogsIndexName": {
"type": "string",
"defaultValue": "listings"
}
},
"resources": [
{
"apiVersion": "2014-06-01",
"name": "[parameters('hostingPlanName')]",
"type": "Microsoft.Web/serverFarms",
"location": "[parameters('siteLocation')]",
"properties": {
"name": "[parameters('hostingPlanName')]",
"sku": "[parameters('sku')]",
"workerSize": "[parameters('workerSize')]",
"numberOfWorkers": 1
}
},
{
"apiVersion": "2014-06-01",
"name": "[parameters('siteName')]",
"type": "Microsoft.Web/Sites",
"location": "[parameters('siteLocation')]",
"dependsOn": [
"[concat('Microsoft.Web/serverFarms/', parameters('hostingPlanName'))]"
],
"tags": {
"[concat('hidden-related:', resourceGroup().id, '/providers/Microsoft.Web/serverfarms/', parameters('hostingPlanName'))]": "empty"
},
"properties": {
"name": "[parameters('siteName')]",
"serverFarm": "[parameters('hostingPlanName')]"
},
"resources": [
{
"apiVersion": "2014-04-01",
"type": "config",
"name": "web",
"dependsOn": [
"[concat('Microsoft.Web/Sites/', parameters('siteName'))]"
],
"properties": {
"appSettings": [
{
"name": "Project",
"value": "[parameters('Project')]"
},
{
"name": "MicrosoftAppId",
"value": "[parameters('MicrosoftAppId')]"
},
{
"name": "MicrosoftAppPassword",
"value": "[parameters('MicrosoftAppPassword')]"
},
{
"name": "MicrosoftBingMapsKey",
"value": "[parameters('MicrosoftBingMapsKey')]"
}
]
}
},
{
"apiVersion": "2014-04-01",
"name": "web",
"type": "sourcecontrols",
"dependsOn": [
"[resourceId('Microsoft.Web/Sites', parameters('siteName'))]",
"[concat('Microsoft.Web/Sites/', parameters('siteName'), '/config/web')]"
],
"properties": {
"RepoUrl": "[parameters('repoUrl')]",
"branch": "[parameters('branch')]",
"IsManualIntegration": true
}
}
]
}
]
}
Loading

0 comments on commit e763980

Please sign in to comment.