Skip to content

Commit 6f03c36

Browse files
kirkonepaule96
kirkone
and
paule96
authored
Add documentation (#1)
* Update dotnet SDK - Update SDK to 3.1.101 +semver: patch * Add Readme.md - this is the first draft * Update Readme and documentation Co-authored-by: Paul Jeschke <[email protected]> * Update dotnet sdk Co-authored-by: Paul Jeschke <[email protected]>
1 parent 5442e67 commit 6f03c36

File tree

5 files changed

+189
-5
lines changed

5 files changed

+189
-5
lines changed

‎README.md

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
# EasyConfig Azure Web App extension
2+
3+
> provided by [codez.one](https://codez.one)
4+
5+
## Introduction
6+
7+
An endpoint for SPA client apps hosted in an Azure Web App to get configuration values stored in environment variables or Azure KeyVault.
8+
9+
If a Single Page Application hosted in an Azure Web App needs configuration values that are only known in a deployed environment it can get a little tricky. A good example is the URI for an API endpoint used by the client app or details for a client-side authentication like MSAL. These values are known at deployment time and can be set as settings in the Web App. But the only way to access these values from the client is having server-side code that can read the values and provide them to the client.
10+
11+
This extension will take care on that and after installation you will get an endpoint like that:
12+
13+
```
14+
https://easyconfigsiteextension.azurewebsites.net/.config/environment.json
15+
```
16+
17+
The response looks like:
18+
19+
```json
20+
{
21+
"section":
22+
{
23+
"setting": "value"
24+
},
25+
"setting1": "value 1"
26+
}
27+
```
28+
29+
## For users
30+
31+
For detail user instruction look at our [user manual](/docs/users/Index.md).
32+
33+
## For contributors
34+
35+
You’re not interested in developing and just want to know more about how to use the software? [Right this way](/docs/contributors/Index.md)
36+
37+
## Nuget Package
38+
39+
The EasyConfig extension is provided as a nuget package and can be found on nuget.org. The extension will be automaticly indexed by the Azure Web App extension provider and added to the selection in the portal.
40+
41+
> **Info**: As a user you do not have to use this nuget package directly.
42+
43+
| Name | Status |
44+
| --- | ---|
45+
| [Internal Feed on AzDO](https://dev.azure.com/czon/EasyConfig.SiteExtension/_packaging?_a=package&feed=31290296-b55e-464b-b92e-d8b8c91cbdfe&package=e97dc02b-bdd8-4299-9f84-2b795b116572&preferRelease=true) | [![EasyConfig.SiteExtension package in EasyConfig.SiteExtension feed in Azure Artifacts](https://feeds.dev.azure.com/czon/d27b319b-5062-4fcb-8dbb-ee3a080e553e/_apis/public/Packaging/Feeds/31290296-b55e-464b-b92e-d8b8c91cbdfe/Packages/e97dc02b-bdd8-4299-9f84-2b795b116572/Badge)](https://dev.azure.com/czon/EasyConfig.SiteExtension/_packaging?_a=package&feed=31290296-b55e-464b-b92e-d8b8c91cbdfe&package=e97dc02b-bdd8-4299-9f84-2b795b116572&preferRelease=true) |
46+
| [nuget.org EasyConfig.SiteExtension](https://www.nuget.org/packages/EasyConfig.SiteExtension/) | [![Nuget Badge](https://img.shields.io/nuget/v/EasyConfig.SiteExtension.svg)](https://www.nuget.org/packages/EasyConfig.SiteExtension/) |
47+
48+
## Authors
49+
50+
- **Kirsten Kluge** - _Initial work_ - [kirkone](https://github.com/kirkone)
51+
- **Paul Jeschke** - _Documentation_ - [paule96](https://github.com/paule96)
52+
53+
See also the list of [contributors](https://github.com/codez-one/EasyConfig/graphs/contributors) who participated in this project.
54+
55+
## License
56+
57+
This project is licensed under the MIT License - see the [LICENSE.md](LICENSE.md) file for details
58+
59+
## Acknowledgments
60+
61+
- Inspired by this [GitHub](https://github.com/mmercan/Creating-Azure-WebSites-Site-Extensions) repo

‎docs/contributors/Index.md

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
# Contributors Guide
2+
3+
> This documenten is for developers that want to improve or extend the EasyConfig SiteExtension.
4+
5+
## Prequest
6+
7+
- VSCode or VisualStudio in a current version
8+
- dotnet sdk as mentioned in [global.json](/global.json)
9+
- NuGet CLI
10+
11+
## Project structure
12+
13+
The project is splitted in different parts for better clarity and maintenance.
14+
This is the current project structure.
15+
- EasyConfig (Root)
16+
- docs: Documents for the whole project
17+
- pipelines: The build-definition for Azure Pipelines
18+
- tools: additional tools for the build pipeline
19+
- src: All source code of the project.
20+
- EasyConfig.SiteExtension: The actual extension
21+
- EasyConfig.SiteExtension.NuGet: The specification for the NuGet package
22+
- tools:
23+
24+
## Workflow to contribute
25+
26+
1. Write a comment on an issue that you start working on it
27+
- if no issue exsist create a new one
28+
2. Fork the repo
29+
3. Create a new branch in your fork for this issue
30+
4. Start implementing your changes
31+
5. Open a pull request to this repo (target branch master)
32+
6. Wait for feedback and repeat step 4 and 6
33+
7. Merge your pull request if all checks are green
34+
35+
## Build
36+
37+
The build environment for this project is on Azure Pipelines and can be found here [dev.azure.com/czon/EasyConfig.SiteExtension](https://dev.azure.com/czon/EasyConfig.SiteExtension/_build)
38+
39+
### Nuget package builds
40+
41+
| Name | Status |
42+
| --- | --- |
43+
| [EasyConfig.SiteExtension CI](https://dev.azure.com/czon/EasyConfig.SiteExtension/_build?definitionId=4) | [![Build Status](https://dev.azure.com/czon/EasyConfig.SiteExtension/_apis/build/status/EasyConfig.SiteExtension%20CI?branchName=master)](https://dev.azure.com/czon/EasyConfig.SiteExtension/_build?definitionId=4) |
44+
| [Internal Release Stage](https://dev.azure.com/czon/EasyConfig.SiteExtension/_release?definitionId=1&_a=releases) | [![Internal Release Stage](https://vsrm.dev.azure.com/czon/_apis/public/Release/badge/d27b319b-5062-4fcb-8dbb-ee3a080e553e/1/1)](https://dev.azure.com/czon/EasyConfig.SiteExtension/_release?definitionId=1&_a=releases) |
45+
| [NuGet Release Stage](https://dev.azure.com/czon/EasyConfig.SiteExtension/_release?definitionId=1&_a=releases) | [![nuget.org release Stage](https://vsrm.dev.azure.com/czon/_apis/public/Release/badge/d27b319b-5062-4fcb-8dbb-ee3a080e553e/1/2)](https://dev.azure.com/czon/EasyConfig.SiteExtension/_release?definitionId=1&_a=releases) |

‎docs/users/Index.md

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
# Usage
2+
3+
> This documenten is for users of the EasyConfig project and describe how you can use it in your Azure Web Apps.
4+
5+
## Requirements
6+
7+
- Extensions can only be installed in Windows basesd App Services at the moment.
8+
- The extension is written in c# using dotnet core 3.1 as self-contained application, so there should be **no** dependency to installed frameworks
9+
10+
## Installation
11+
12+
The Extension can be installed on the Azure Portal or with an ARM Template
13+
14+
### Azure Portal
15+
16+
In the Settings of the Azure Web App under the *Development Tools* section will be an *Extensions* button. On this page you can *Add* an new extension.
17+
In the *Choose extension* dialog have a look for **Easy Config** and select the extension.
18+
After that the *Accept legal terms* dialog has to be confirmed.
19+
20+
The Insatllation will take some moments and when finished you see the extension in the table below the *Add* button.
21+
22+
When an update to is available it will be shown in this table also.
23+
24+
### ARM Template
25+
26+
coming soon &trade;
27+
28+
## Configuration
29+
30+
Which values will be included in the response JSON can be set up either using the *Application Settings*, an *Azure KeyVault* or both.
31+
32+
### Application Settings
33+
34+
In the Azure Portal in the Wep App under *Settings* > *Configuration* the *Application settings* can be edited.
35+
36+
All EasyConfig settings must start with `EASYCONFIG__` followed by the name of the setting. For example:
37+
38+
```
39+
EASYCONFIG__setting1
40+
```
41+
42+
> **Important**: the devider is 2 times `_` (**underscore**)
43+
44+
The *Value* field will be also the value of this setting.
45+
46+
All other *Application settings* which does not start with `EASYCONFIG__` will be ignored by the extension.
47+
48+
### Azure KeyVault
49+
50+
An other way to store the Settings is using an Azure KeyVault.
51+
52+
coming soon &trade;
53+
54+
### Using the endpoint
55+
56+
The endpoint can be accessed by the following ways:
57+
58+
```
59+
...azurewebsites.net/.config/
60+
...azurewebsites.net/.config/environment
61+
...azurewebsites.net/.config/environment.json
62+
```
63+
64+
> **Info**: When using the `.config/` endpoint the trailing `/` (**slash**) is nessesary and not optional.
65+
66+
All these endpoints will return a JSON similar to this one:
67+
68+
```json
69+
{
70+
"section":
71+
{
72+
"setting": "value"
73+
},
74+
"setting1": "value 1"
75+
}
76+
```
77+
78+
This JSON can be used in the client app to initialize the app with all nessesary values.

‎global.json

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
{
22
"sdk": {
3-
"version": "3.1.100"
3+
"version": "3.1.201"
44
}
5-
}
5+
}

‎src/EasyConfig.SiteExtension/EasyConfig.SiteExtension.csproj

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -17,9 +17,9 @@
1717
</PropertyGroup>
1818

1919
<ItemGroup>
20-
<PackageReference Include="Microsoft.AspNetCore.Mvc.NewtonsoftJson" Version="3.1.0" />
21-
<PackageReference Include="Microsoft.Azure.Services.AppAuthentication" Version="1.3.1" />
22-
<PackageReference Include="Microsoft.Extensions.Configuration.AzureKeyVault" Version="3.1.0" />
20+
<PackageReference Include="Microsoft.AspNetCore.Mvc.NewtonsoftJson" Version="3.1.4" />
21+
<PackageReference Include="Microsoft.Azure.Services.AppAuthentication" Version="1.4.0" />
22+
<PackageReference Include="Microsoft.Extensions.Configuration.AzureKeyVault" Version="3.1.4" />
2323
</ItemGroup>
2424

2525
</Project>

0 commit comments

Comments
 (0)