{"id":19101168,"url":"https://github.com/ravendb/demo","last_synced_at":"2025-07-28T10:36:49.999Z","repository":{"id":38306115,"uuid":"202318033","full_name":"ravendb/demo","owner":"ravendb","description":null,"archived":false,"fork":false,"pushed_at":"2025-03-10T23:40:24.000Z","size":26124,"stargazers_count":4,"open_issues_count":3,"forks_count":9,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-04-09T16:15:10.185Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"C#","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ravendb.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-08-14T09:24:08.000Z","updated_at":"2024-12-13T07:35:13.000Z","dependencies_parsed_at":"2023-02-13T00:00:49.528Z","dependency_job_id":"055e3a8b-deac-4dcb-a41c-2b9063016260","html_url":"https://github.com/ravendb/demo","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ravendb%2Fdemo","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ravendb%2Fdemo/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ravendb%2Fdemo/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ravendb%2Fdemo/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ravendb","download_url":"https://codeload.github.com/ravendb/demo/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248065282,"owners_count":21041872,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-09T03:53:11.595Z","updated_at":"2025-04-09T16:15:26.585Z","avatar_url":"https://github.com/ravendb.png","language":"C#","funding_links":[],"categories":["others"],"sub_categories":[],"readme":"## Setup\nIn the `DemoServer` folder:\n```\nnpm install --legacy-peer-deps\nnpm run webpack\n```\n\nNode version needed: v14+  \nASP.NET core: 3.1.x\n\n## Running the application\nRun the `DemoServer` project in Visual Studio, Rider or `dotnet run`.  \nThe application should run on http://localhost:9090/  \nIn order for the demos to execute, a RavenDB instance must be running on http://localhost:8080\n\n## Testing locally before new release\n\n1. Start Docker.\n2. In powershell, go to the main solution directory.\n3. Run `.\\test-image.ps1` script\n    \n    The script will build the application in a similar way that the release version is built.\n    Then it runs the application locally and automatically opens web browser on http://localhost:8081\n4. Test the application in the newly opened browser window.\n\n## General description\nThe demo application contains source code examples that will be displayed as demo pages. The demo pages are divided into categories.  \nThe majority of the demos can be executed on the server side, which will result in modifying user database.  \nUser can go to their database using the \"Open in studio\" button, in order to examine the changes introduced by running a demo.\n\nEach demo contains description, assets (links to an external or internal resource) and walkthrough steps.  \nEach walkthrough step guides the user through the RavenDB knowledge by highlighting and describing relevant code, as well as providing a set of resources.\n\n## User database\nEach user has their own database. On production, it resides on the live-test server.  \nThe default database contains Northwind data. Some of the demos require special Media database, which will be created automatically when needed.\n\n## Source code\nC# is the main demo application language.  \nThe code that is displayed on each C# demo page will be also executed when the \"Run\" button is clicked.\n\nThe additional language demos contain their own descriptions, assets and walkthroughs.  \nHowever, they should be designed to present the semantically identical code as their C# counterpart.  \nWhen the \"Run\" button is clicked on a multi-language demo, the application will execute the C# source code.\n\n## demos.json\nThe `demos.json` file contains a list of categories and the corresponding demos.  \nEach demo language folder should contain its own `demos.json` file.\n\n`demos.json` locations:\n- C# `DemoServer/Controllers/Demos/demos.json`\n- GO `DemoServer/AdditionalLanguages/go/demos.json`\n- Java `DemoServer/AdditionalLanguages/java/src/main/java/net/ravendb/demo/demos.json`\n- Node.js `DemoServer/AdditionalLanguages/nodejs/demo/demos.json`\n\nThe JSON structure of the `demos.json` file is an array of such entries:\n```\n    {\n        \"category\": {\n            \"slug\": \"basics\",\n            \"directory\": \"Basics\"\n        },\n        \"demos\": [\n            \"theDocumentStore\",\n            \"theSession\",\n            \"createDocument\",\n            \"editDocument\",\n            \"deleteDocument\"\n        ]\n    }\n```\n\n### category item\nEach category should contain `slug` and `directory` fields.\n\n`slug` should identify the category and should be identical for all languages (i.e. the `basics` slug is the same for C#, GO, Java \u0026 Node.js).\n\nThe `directory` field indicates the directory name of the category. Please remember that it's case-sensitive on Linux.\n\n### demos array\nThe `demos` array contains a list of the demo **folders** located inside the category folder. The values are also case-sensitive on Linux.\n\n**Important:** in order for a demo to be visible in the application, it's **directory name** needs to be added to the proper category in the `demos.json` file.\n\n## Demo folder\nEach demo resides in its own folder which name should correspond with the `demos.json` entry.  \nEach demo directory should contain `metadata.json` file and a source code file.\n\n### `metadata.json`\n`metadata.json` contains the demo settings, wordings, etc.\n\n**Important:** `metadata.json` should be added to the project as Content file.\n\nExample content:\n\n```\n    \"Slug\": \"create-document\",\n    \"SourceFileName\": \"CreateDocument.java\",\n    \"Title\": \"Create Document\",\n    \"DescriptionLines\": [\n        \"**Create a new JAVA entity and save it as a document** in the Database.\",\n        ...\n    ],\n\t\"Assets\": [ ... ],\n\t\"Walkthroughs: [ ... ]\n```\n\n- `Slug` may be treated as a human-readable identifier of the demo. It is a part of the demo URL and should be the same for all language versions.\n- `SourceFileName` points to the file that contains the demo source code. It is case-sensitive.\n- `Title` contains the displayed demo title.\n- `DescriptionLines` contains the demo description.\n- `Assets` contains the general demo assets listed in the left-hand-side menu.\n- `Walkthroughs` contains the walkthrough step definitions.\n\n### Optional `metadata.json` fields\n- `NonInteractive` - the demo is not interactive. The \"Run\" and \"Open in studio\" buttons won't be visible.\n- `StudioLinkToMediaDatabase` - the \"Open in studio\" button will lead to the media database instead of the regular DemoUser database.\n- `StudioLinkToIndexList` - the \"Open in studio\" button will lead to the index list page.\n- `ConferenceOnly` - the demo will be available only in the conference mode.\n\n### Assets\nAssets are displayed as a webpage link. They can be placed in the general demo section (under demo description etc.) or in the walkthrough step panel.\n\nExample definition:\n\n```\n{\n\t\"Title\": \"Document Modeling\",\n\t\"Type\" : \"link\",\n\t\"Url\"  : \"https://github.com/ravendb/book/blob/v4.0/Ch03/Ch03.md#document-modeling\"\n}\n```\nAvailable asset types: `link`, `downloadable`, `document`, `demo`\n\n### Walkthroughs\nThe `Walkthroughs` element is an array of walkthrough steps. Example walkthrough step:\n\n```\n{\n\t\"Title\": \"Create a new JAVA object to be saved\",\n\t\"Slug\" : \"step-1\",\n\t\"DescriptionLines\": [\n\t\t\"* Define the JAVA object to be saved.\",\n\t\t\"\",\n\t\t\"TODO\"\n\t],\n\t\"Assets\": [ ...\t]\n}\n```\n\n- `Slug` is the identifier of the walkthrough step in the context of this demo. It will be part of the walkthrough step URL.\n- `Assets` contains the same type of data as the demo general assets.\n\n## Source code\nThe demo source code file should contain additional region sections in order to make the demo parser know which code parts should be displayed on the demo page.  \nThe region begin\\end syntax is language-dependent. For example, in C# it should be as below:\n\n```\n#region Usings\nusing Raven.Client.Documents.Session;\n#endregion\n```\n\n```\n#region Demo \n#region Step_1\nSupplier supplier = new Supplier\n{\n    Name = supplierName,\n    Phone = supplierPhone\n};\n\nCategory category = new Category\n{\n    Name = \"NoSQL Databases\",\n    Description = \"Non-relational databases\"\n};\n#endregion\n#endregion\n```\n\nSupported region names:\n- `Usings` - there should be only one such a region.\n- `Demo` - there can be multiple such regions.\n- `Step_N` (for example: `Step_1`, `Step_2`, etc.). The `Step` region should be nested inside a `Demo` region.\n\n### C# Source code\nThe C# demo source code is displayed on the demo pages, but it's also executed when the \"Run\" button is clicked.  \nA demo can be marked as `NonInteractive` in `metadata.json` to ensure that the code won't be executed and will be only treated as a read-only code example.\n\n### Non-C# source code\nThe source code that is not written in C# **won't be compiled**. Only the C# demos are compiled and executed in the runtime of the application.\n\nFor example, a Java source code can be found here:\n`DemoServer/AdditionalLanguages/java/src/main/java/net/ravendb/demo/basics/createDocument/CreateDocument.java`\n\nThe Java source code is divided into regions that start with `//region REGION_NAME` line and end with `//endregion` line, for example:\n\n```\n//region Usings\nimport net.ravendb.client.documents.DocumentStore;\nimport net.ravendb.client.documents.session.IDocumentSession;\nimport net.ravendb.client.documents.session.QueryStatistics;\nimport net.ravendb.client.primitives.Reference;\n//endregion\n```\n\n## Troubleshooting\nAll directory and file names are case sensitive on Linux, but may be case-insensitive on the developer machine (if the application is being developed on windows).  \nIf a demo is missing on production but was working on the developer's machine, please make sure that all paths and file names (including the values provided in `demos.json`) match the correct casing.\n\nA log file is created in folder: `DemoServer\\bin\\Debug\\netcoreapp2.1`\n\nChecklist:\n\n1. `demos.json`:\n    - `category` item: ensure that `slug` is correct and the `directory` value matches the existing folder name and the casing is correct\n    - `demos` array: ensure that the demo name matches the directory name inside a given category\n2. `metadata.json`\n    - ensure it is added as a content file to the `DemoServer` project\n    - for non-C# demos: make sure that the `Slug` value matches the corresponding C# demo slug\n    - ensure that `SourceFileName` matches the source code file name located in the same folder as `metadata.json`. Please remember to include the file extension.\n\n### All examples of a specific language are missing in the Production environment\n\n...but are present locally.\n\nUsually this is caused by a file name casing error. The production environment is running on Linux, so it's case sensitive. \nQuite often, the application is developed on Windows, which is not so strict - naming problems do not surface there.\n\nWhat to do:\n1. Run the application locally using the `test-image.ps1` script\n2. If the problem is reproduced, check the logs of the application.\n    The logs can be either accessed in the docker container or seen in a console window that is opened once the application starts. \n    The logs should contain the exact path of the file that could not be loaded.\n    E.g.:\n```\nDemoParser.Utils.ParsingException: File AdditionalLanguages/java/src/main/java/net/ravendb/demo/queries/projectingUsingFunctions/ProjectingUsingFunctions.java does not exist.\n```\n3. Check the casing of all directories in the path and the file name. Fix where applicable. \n\n## When adding a new C# demo:\n\n1. Add demo to `demos.json`\n2. Add slug to `slugs.ts`\n3. Add the demo `Controller.cs` file\n4. Add the demo `metadata.json` file\n5. Add the demo `*.svg` file under `wwwroot\\img\\demo-icons\\`\n6. Add the demo `*.tsx` file under `client\\src\\components\\demos\\`\n7. Add the demo to file: `DemoFactory.tsx`\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fravendb%2Fdemo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fravendb%2Fdemo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fravendb%2Fdemo/lists"}