Azure Static Web Apps - TBD</h1> <article> <h1>Azure Static Web Apps - TBD</h1> <p>2023-04-01T00:00:00Z</p> <p>As the demand for fast, scalable, and secure web solutions continues to grow, Azure Static Web Apps have emerged as a powerful and flexible platform for developers. This series is will guide you through the fundamentals of Azure Static Web Apps, deployment process, and look at comprehensive examples. By the end of this journey, you'll be well-equipped to harness the full potential of Azure Static Web Apps and take your web development projects to new heights.</p> <h2 id="what-is-azure-static-web-apps">What is Azure Static Web Apps?</h2> <p>Azure Static Web Apps is a cloud-based platform that streamlines the process of building and deploying static web apps. It's a fully managed service that provides a simple, cost-effective, and secure way to host your static web apps. Azure Static Web Apps is built on top of Azure App Service, which means you can take advantage of all the benefits of App Service, including:</p> <ul> <li><strong>Scalability</strong> - Azure Static Web Apps can scale up or down to meet your needs. You can also scale out to multiple instances to handle increased traffic.</li> <li><strong>Security</strong> - Azure Static Web Apps is built on top of Azure App Service, which provides a secure and reliable platform for hosting your static web apps.</li> <li><strong>Reliability</strong> - Azure Static Web Apps is built on top of Azure App Service, which provides a secure and reliable platform for hosting your static web apps.</li> <li><strong>Performance</strong> - Azure Static Web Apps is built on top of Azure App Service, which provides a secure and reliable platform for hosting your static web apps.</li> </ul> <h2 id="why-use-azure-static-web-apps">Why use Azure Static Web Apps?</h2> <p>For me the biggest reason to use Azure Static Web Apps is the simplicity. With the <a href="https://aka.ms/swa/database-connections">recent annoucement</a> that you can automatically generate REST and GraphQL APIs from your static web apps, you can now build a full stack web application without having to worry about the tedious part of writing a backend. This is a huge win for developers who want to focus on building great user experiences. Now you can easily bundle a multi-tier application including:</p> <ul> <li>Frontend - HTML, CSS, JavaScript, and other static assets</li> <li>Backend - Azure Function</li> <li>Database - Azure SQL Database, Azure Cosmos DB, or any other database that supports REST or GraphQL APIs</li> <li>Authentication - Azure Active Directory, Facebook, Google, Twitter, or any other identity provider that supports OpenID Connect</li> <li>CI/CD - GitHub Actions or Azure DevOps Pipelines auto generated and configured for you</li> <li><strong>Forces Serverless Patterns</strong> - Apps that are built for serverless architectures are inherently easier to scalable, secure, and are (in my opinion) more reliable. This is likely the most challenging point for developers to get their head around. The idea of not having a server to manage is a foreign concept to many developers. However, the benefits of serverless architectures are well documented and are becoming more and more popular. If you are interested in learning more about serverless architectures I would recommend checking out <a href="https://learn.microsoft.com/en-us/dotnet/architecture/serverless/">Serverless apps: Architecture, patterns, and Azure implementation</a>.</li> </ul> <p>All of this in your choice of programming language. You can even use your own custom domain name and provided SSL certificate to get your app production ready.</p> <h2 id="pre-requisites">Pre-requisites</h2> <p>There are a couple of things you will need to get started.</p> <ol> <li><p><strong>An Azure account</strong></p> <p>This should be obvious but you will need an Azure account to use Azure Static Web Apps. If you don't have one you can create one <a href="https://azure.microsoft.com/en-us/free/">here</a>.</p> </li> <li><p><strong>A git based repository</strong></p> <p>Everything to do with Azure Static Web Apps is done through a git repository hosted in either Github or Azure DevOps. If you don't have a repository you can create one for free on your platform of choice.</p> </li> <li><p><strong>Command line tools</strong></p> <p>I used the winget command line tool to install the following tools. You can find more information about winget <a href="https://docs.microsoft.com/en-us/windows/package-manager/winget/">here</a>.</p> <pre class='language-powershell line-numbers' style='white-space:pre-wrap;'><code>winget install CoreyButler.NVMforWindows nvm install 16 nvm use 16 winget install -e Git.Git</code></pre> <p>All of these are fairly straight forward</p> <ul> <li>[1] : I recommend using NVMforWindows to manage your node versions. This will allow you to easily switch between different versions of node.</li> <li>[2-3] : Azure CLI and Azure Function Core Tools are both installed using npm. As of the time of authoring this I ran into issues with later versions of npm with some types of apps so I recommend using npm version 16.</li> <li>[1] : Azure CLI that enables you to interact with Azure resources</li> <li>[2] : StaticWebApps CLI specifically for interacting with Azure Static Web Apps</li> <li>[3] : Azure Function Core Tools that enables you to interact with Azure Functions <ul> <li>Note: You should be able to install the Azure Function Core Tools using npm but I had issues with this. I would recommend using winget to install this.</li> </ul> </li> <li>[4] : Git CLI that enables you to interact with git repositories (you likely already have this installed but just in case)</li> </ul> </li> <li><p><strong>An Application</strong></p> <p>Last you will obviously need an application to deploy. The front end must be able to be statically built along with (optionally) an api that is written to be serverless. In following posts I will be demonstrating how to build simple applications in different languages & frameworks to serve as examples and also demonstrating differences between them.</p> </li> </ol> <h2 id="my-approach">My Approach</h2> <p>It took me a while to come up with what I felt was the best approach to implementing Azure Static Web Apps. I wanted to be able to build a simple application that could be deployed to Azure Static Web Apps and then be able to easily add additional functionality to it. I also wanted to be able to easily switch between different languages and frameworks to demonstrate the differences between them. And most importantly I wanted the ultimate solution to be intuitive and easy to understand. A solution that makes sense today but is confusing tomorrow is not a solution.</p> <pre><code>1. use an npm package.json to manage dependencies and scripts 2. use a .env file to manage environment variables 3. use efcore to manage database migrations 4. use Azure B2C for authentication </code></pre> <p>I know what you are thinking, "This blog is almost always about C# based solutions and now I need npm?" I hear you however there are a few reasons why I chose this approach. First, I wanted a solution that would work regardless of the language or framework you are using. My first example will be in C# & Blazor however I often am building out front ends in Angular, React, etc. and I wanted a solution that would work for all of them so that I didn't need do more than update the scripts that are being called. Second, I wanted a solution that is easy to maintain. The various CLI tools that I want to use are all available as npm packages and from what I could see the npm versions of these commands are available faster than other package managers such as choco or winget. Third, I wanted the final solution to allow devs to locally run and setup everything they need to run the application as closely to how it would be running in production as possible. Lastly, I needed the solution to be easy to tweak and customize. Not every solution is going to be the same, not every project will have the same requirements or conventions. I wanted a solution that would allow developers to easily customize it to fit their needs and not try to force them to accomodate an approach that may not fit perfectly.</p> <p>I also wanted this solution to work no matter what environment I was developing in. I primary use Visual Studio however when I'm working on a front end I often use VS Code because the tooling is better. For the rest of this series I will be validating everything in VS Code because its more accessible to the majority of developers but I will call out how to do things in Visual Studio as well.</p> <h2 id="core-directory-structure-files">Core Directory Structure & Files</h2> <pre><code class="language-text">. ├── Api/ │ └── local.settings.json │ └── ... ├── Db/ │ └── staticwebapp.database.config.json │ └── ... ├── Web/ │ └── Properties/launchSettings.json (Blazor WSAM) │ └── ... ├── .env ├── package.json ├── ... </code></pre> <p>Obviously the actual Api/Db/Web code will contain your actual</p> <h4 id="the-npm-package.json">The NPM package.json</h4> <pre class='language-json line-numbers' style='white-space:pre-wrap;'><code>{ "scripts": { "start": "concurrently \"npm run start-api\" \"npm run start-web\" \"npm run start-swa\"", "start-api": "cd Api && func start --csharp", "start-web": "cd Web && dotnet watch run", "start-swa": "swa start --data-api-location db", "db-reset": "cd Db && dotnet ef database drop -f && dotnet ef database update && dotnet run", "db-migrate": "cd Db && dotnet ef migrations add \"$(date +%s)\"", "db-update": "cd Db && dotnet ef database update", "db-drop": "cd Db && dotnet ef database drop -f" }, "devDependencies": { "@azure/static-web-apps-cli": "^1.1.1", "azure-functions-core-tools": "^4.0.5095", "concurrently": "^8.0.1" } }</code></pre> <p>There's a lot going on here so let's break it down.</p> <ul> <li>[3] : start script - the main entry point for the application. This will start the api, web, and swa cli tools all at once. This is accomplished by using the concurrently npm package to start 3 other scripts in parallel.</li> <li>[5-7] : start-* scripts - these scripts are used to start the various parts of the application. The important part about this approach <ul> <li>start-api script will start the api using the Azure Function Core Tools. In my case I am using C# however this approach can accomodate other languages simply by updating the argument to the func command.</li> <li>start-web script will start the web application using dotnet watch. This example is using Blazor WebAssembly however this approach can accomodate other frameworks simply by updating the command that is being run.</li> <li>start-swa script will start the Azure Static Web Apps (SWA) CLI w/ the --data-api-location parameter to tell it where the database definition is located.</li> </ul> </li> <li>[9-12] : db-* scripts - these scripts are used to manage the database using efcore <ul> <li>db-reset script will drop the database, run all migrations, and then seed the database.</li> <li>The db-migrate script will create a new migration using the current timestamp as the name. A helper script for devs to be able to build out migrations without needing to look up the efcore commands or the standard naming convention for the current project.</li> <li>The db-update script will ensure the target Database is up to date.</li> <li>The db-drop script will drop the database. This will be important when we are automating creating a database per staging environment.</li> </ul> </li> <li>[15-17] : devDependencies - the various npm packages that are used to manage the application. These are all installed using npm install.</li> </ul> <h3 id="the.env-file">The .env file</h3> <p>Another key consideration in this approach was where environment specific configurations were going to pulled from and to streamline the process as much as possible for the developers without needing them to read a long setup doc to set everything up. I adopted using an .env file because support for it was already built into the swa cli and it was relatively easy to use that for other parts of the application as well. In my simple case I ended up with a very simple .env file that looks like this:</p> <pre class='language-json line-numbers' style='white-space:pre-wrap;'><code>DB_CONNECTION_STRING=[REDACTED]</code></pre> <p>The DB_CONNECTION_STRING is used by the data-api to auto-generate Rest & GraphQL endpoints for the application to use. And I was able to easily use this with efcore migrations and the api.</p> <p>The biggest advantage of this is that the .env file is ONLY used in development. When the application is deployed and runnin in Azure the environment variables are pulled from the configuration settings in Azure.</p> <h3 id="the-local.settings.json-file-and-launchsettings.json-file">The local.settings.json file and launchSettings.json file</h3> <p>The npm scripts are all expecting the Api and Web projects to run locally on a certain</p> <h2 id="tradeoffs">Tradeoffs</h2> <p>Like any approach there are tradeoffs. The biggest tradeoff with this approach is that using <code>npm start</code> to start the application will start 3 processes. This is not a huge deal but it does mean you need to understand that when you are launching the application you need to kill all 3 processes when you are done. That is one of the reasons why I broke the start script into 3 parts so that if you want you can start them in separate terminal windows, or use VS Code / Visual Studio to start pieces that you want to attach debuggers to.</p> <p>Not a huge deal but something to be aware of.</p> <h2 id="whats-next">What's Next</h2> <p>Depending on yours needs you can take a look at other posts in this series to understand how to set those up to work with this approach. What types of front ends are you developing with? What do you use for auth? Leave a comment below and let me know.</p> <ul> <li><a href="xref:azure-swa-api-csharp">Api - C#</a></li> <li><a href="xref:azure-swa-db-efcore">Db - EF Core</a></li> <li><a href="xref:azure-swa-db-rest">Db - Rest APIs</a></li> <li><a href="xref:azure-swa-db-graphql">Db - GraphQL APIs</a></li> <li><a href="xref:azure-swa-db-auth">Db - Integrated Auth</a></li> <li><a href="xref:azure-swa-web-blazor">Web - Blazor WebAssembly</a></li> <li><a href="xref:azure-swa-web-react">Web - React</a></li> </ul> </article> <article> <h1>Azure Static Web Apps - Blazor WebAssembly</h1> <p>2023-03-02T00:00:00Z</p> <p>Comming Soon</p> </article> <article> <h1>Azure Static Web Apps - Blazor WebAssembly</h1> <p>2023-03-02T00:00:00Z</p> <p>Comming Soon</p> </article> <article> <h1>Azure Static Web Apps - Blazor WebAssembly</h1> <p>2023-03-02T00:00:00Z</p> <p>Comming Soon</p> </article> <article> <h1>Azure Static Web Apps - Blazor WebAssembly</h1> <p>2023-03-02T00:00:00Z</p> <p>Comming Soon</p> </article> <article> <h1>Azure Static Web Apps - Blazor WebAssembly</h1> <p>2023-03-02T00:00:00Z</p> <h1 id="azure-static-web-apps-blazor-webassembly">Azure Static Web Apps - Blazor WebAssembly</h1> <p>In the (Getting Started)[xref:azure-swa-getting-started] post, we discussed the basics of Azure Static Web Apps and how to get started with a simple static web app. In this post, we will take a look at an example of a Blazor WebAssembly app and how to deploy it to Azure Static Web Apps.</p> <h2 id="create-a-new-blazor-webassembly-app">Create a new Blazor WebAssembly app</h2> <p>To get started, we will create a new Blazor WebAssembly app using the .NET CLI. Open a terminal and run the following commands:</p> <pre class='language-powershell line-numbers' style='white-space:pre-wrap;'><code>winget install npm install --save-dev @azure/static-web-apps-cli dotnet new blazorwasm -o App cd App dotnet add package Microsoft.AspNetCore.Components.WebAssembly.StaticWebAssets cd .. func init MyProject.Api --dotnet Rename-Item MyProject.Api Api </code></pre> <p><span>Special Thanks to <a href="https://unsplash.com/@pankajpatel?utm_source=unsplash&utm_medium=referral&utm_content=creditCopyText">Pankaj Patel</a> on <a href="https://unsplash.com/photos/u2Ru4QBXA5Q?utm_source=unsplash&utm_medium=referral&utm_content=creditCopyText">Unsplash</a> for the photo used for this post</span></p> </article> <article> <h1>Azure Static Web Apps - Blazor WebAssembly</h1> <p>2023-03-02T00:00:00Z</p> <p>Comming Soon</p> </article> <article> <h1>Azure Static Web Apps - Blazor WebAssembly</h1> <p>2023-03-02T00:00:00Z</p> <p>Comming Soon</p> </article> <article> <h1>Deploying Statiq to Azure Static Web App</h1> <p>2020-12-01T00:00:00Z</p> <p><a href="https://statiq.dev/">Statiq</a> is a <a href="https://en.wikipedia.org/wiki/Web_template_system#Static_site_generators">static content generator</a> written in C# that is used to generate the site you are reading right now. It is an incredibly robust and feature full project, Below is a series of steps that you can walk through to create your own blog similar to this one.</p> <p>The source for the app that generates this site is open source at <a href="https://github.com/e13tech/blog">https://github.com/e13tech/blog</a>. Feel free to browse the source and get inspiration for your own project.</p> <h3 id="deploy-to-azure-static-web-app-using-github-actions">Deploy to Azure Static Web App using Github Actions</h3> <p><a href="https://azure.microsoft.com/en-us/services/app-service/static/">Static Web Apps</a> is an offering in Azure that is currently in preview that streamlines the deployment of applications from GitHub. It has a few limitations in preview but being able to quickly setup</p> <ol> <li><p>Create new Static Web App resource in the Azure Portal <a href="/images/posts/azure-swa.png"></a></p> <p>Note this is still in preview so it may not be ideal for widespread production use however while it is in preview having a platform to host a static site with a custom domain over https for free is an incredible value.</p> </li> <li><p>Enter the details to your github repository <a href="/images/posts/azure-swa-details.png"></a></p> <p>The important details here are using the <code>Custom</code> Build Preset with the App location of <code>output</code>. For Statiq there is no need for an Api or App artifact location so clear those out. However being able to tie the deployment of an Api as an Azure Function opens up some incredible opportunities for expanding to a more dynamic solution.</p> </li> <li><p>Wait for the resource to be created <br><br> I don't normally document wait steps but this one is important. As part of the resource creation a new GitHub workflow will be created in the branch specific at creation time complete with the secrets to access the newly created resource. Once you have verified that the GitHub workflow has been created successfully then we can modify it.</p> </li> <li><p>Update the auto generated workflow yml to run the Statiq console app and produce the output that will actually get published to Azure. Note: do not attempt to rename the file because the created azure resource refers to it for some of it's functionality.</p> <pre class="language-yaml line-numbers" style="white-space:pre-wrap;"><code>name: Azure Static Web Apps CI/CD on: pull_request: types: [opened, synchronize, reopened, closed] branches: [main] jobs: build: if: github.event_name == 'push' || (github.event_name == 'pull_request' && github.event.action != 'closed') runs-on: ubuntu-latest name: Build And Update Pull Request steps: - uses: actions/checkout@v2 - uses: actions/setup-dotnet@v1 with: dotnet-version: 5.0.100 - run: dotnet restore - run: dotnet build --configuration Release --no-restore - run: dotnet run --output output - name: Build And Deploy id: builddeploy uses: Azure/static-web-apps-deploy@v0.0.1-preview with: azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_API_TOKEN_... }} repo_token: ${{ secrets.GITHUB_TOKEN }} action: "upload" app_location: "output" # App source code path api_location: "" # Api source code path - optional output_location: "" # Built app content directory - optional close_pull_request_job: if: github.event_name == 'pull_request' && github.event.action == 'closed' runs-on: ubuntu-latest name: Close Pull Request Job steps: - name: Close Pull Request id: closepullrequest uses: Azure/static-web-apps-deploy@v0.0.1-preview with: azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_API_TOKEN_... }} action: "close"</code></pre> <p>This is a large file but my changes can be broken down into a few segments</p> <ul> <li>[1] : Keep the workflow name the auto-generated one because there is a link w/in Azure that is looking specifically for that</li> <li>[3-6] : Setup a trigger on pull requests going into the main branch. My preference is to have feature branches for my blog articles and to create a PR for each into main branch while I work on them.</li> <li>[14-21] : The series of standard steps that prepares a .NET 5 environment <ul> <li>[21] : Run the console app directing the generated content to an <code>output</code> directory</li> </ul> </li> <li>[22-31] : The original step that was generated by Azure to do the actual publish <ul> <li>[29] : app_location needs to match the same path that was used on [24], in this example <code>output</code></li> <li>[30,31] : api_location and output_location are not required for this Statiq example but ensure they are left blank</li> </ul> </li> <li>[33-43] : This job triggers on the closure of a pull request to clean up the staging url that can be used to preview the output of a branch that is still in development</li> <li>[26,42] : These lines point to the secret that is generated in the github repository, this name will be uniquely generated and set to your application</li> </ul> </li> </ol> <h3 id="recap">Recap</h3> <p>Now even though it was not defined as a template originally we are able streamline the process of developing content using Statiq and having it automatically deploy to Azure. The best part of this workflow is that I can create a branch for each topic that I am beginning blogs on and as long as there is an open pull request attached to the branch then the github action will create a unique url. This allows you to share that url with anyone to review the actual generated content exactly as it would in production, and once the PR is merged and accepted no additional steps are required in order to publish to production.</p> <p>This is convenient for a personal blog like this so I can loop in colleagues for help proofing a post before it's done. You can probably also see how beneficial this could be for a corporate blog or anywhere that content needs to be reviewed or approved. Setting up a CI/CD flow is usually more complex involving setting up environments, approval processes, etc. Microsoft has done a fantastic job creating this offering and especially while it's in preview you'd be hard pressed to find a more appealing option while it is free to use.</p> <p>What kind of projects will you setup using this workflow? What adjustments will you make to improve it? Share with others in the comments below!</p> <p><span>Special Thanks to <a href="https://unsplash.com/@ninovisalli?utm_source=unsplash&utm_medium=referral&utm_content=creditCopyText">Antonino Visalli</a> on <a href="https://unsplash.com/t/technology?utm_source=unsplash&utm_medium=referral&utm_content=creditCopyText">Unsplash</a>for the photo that was used in this post</span></p> </article> <article> <h1>Blog using Statiq - Getting Started</h1> <p>2020-11-01T00:00:00Z</p> <p><a href="https://statiq.dev/">Statiq</a> is a <a href="https://en.wikipedia.org/wiki/Web_template_system#Static_site_generators">static content generator</a> written in c# that is used to generate the site you are reading right now. It is an incredibly robust and feature full project, Below is a series of steps that you can walk through to create your own blog similar to this one.</p> <p>The source for the app that generates this site is open source at <a href="https://github.com/e13tech/blog">https://github.com/e13tech/blog</a>. Feel free to browse the source and get inspiration for your own project.</p> <ol> <li><p>Create a new .NET console app and add the Statiq.Web Package</p> <pre class='language-powershell line-numbers' style='white-space:pre-wrap;'><code>dotnet new console --name AwesomeBlog cd AwesomeBlog dotnet add package Statiq.Web --version 1.0.0-beta.13 md input md theme\input</code></pre> <p>Most of this is fairly intuitive but in case you need some more details</p> <ul> <li>[1] : Create a .NET console app that will be the generator for your site</li> <li>[2] : Navigate into the directory for your new console app</li> <li>[3] : Add the Statiq.Web nuget package, at the time of writing this Statiq is still prerelease so specify the version</li> <li>[4] : Create the input directory that will host</li> <li>[5] : Create the theme input directory that will contain the layout and other site assets</li> </ul> </li> <li><p>Create a bootstrapper Program.cs</p> <pre class='language-csharp line-numbers match-braces' style='white-space:pre-wrap;'><code>using System.Threading.Tasks; using Statiq.App; using Statiq.Web; namespace Your.AwesomeBlog { public class Program { public static async Task<int> Main(string[] args) => await Bootstrapper .Factory .CreateWeb(args) .RunAsync(); } }</code></pre> <p>A very straight forward Program.cs, notable lines:</p> <ul> <li>[2] : The core Statiq framework namespace with the original Bootstrapper.Factory comes from</li> <li>[3] : The Statiq Web namespace which provides the .CreateWeb(..)</li> <li>[9-13] : Have the Main(string[]) method await the call to the Statiq </code></pre></li> </ul> </li> <li><p>Create a new <code>index.md</code> file within the <code>input</code> directory with the following content</p> <pre class='language-markdown line-numbers' style='white-space:pre-wrap;'><code>Title: My First Statiq page --- # Hello World! Hello from my first Statiq page.</code></pre> <p>There are countless great sources online explaining how <a href="https://statiq.dev/framework/content/template-languages#markdown">Markdown</a> works including the official Statiq website. In a follow-up post I will go through an example of how I am utilizing this input files.</p> </li> <li><p>Launch the built-in previewer from a <a href="xref:windows-terminal-getting-started">terminal window</a></p> <pre class='language-powershell line-numbers' style='white-space:pre-wrap;'><code>dotnet run -- preview</code></pre> <p>If all went well Statiq will display a bunch of diagnostic information and then host your new site at https://localhost:5080 with livereload meaning that you can edit your site content in your favorite editor such as VS Code and the browser will reload to display your changes as you save.</p> </li> </ol> <p>Most of these steps here are borrowed directly from the <a href="https://statiq.dev/web/#quick-start">Statiq Quick Start</a> and adjusted for my content. Combining <a href="https://github.com/statiqdev/CleanBlog">Clean Blog Template</a> with a responsive web template such as one from as a starting point will get you most of the way towards having a blog of your own, lets look at some of the modifications I made beyond this.</p> <p><a href="https://statiq.dev/web/">Statiq Web</a> is built on top of <a href="https://statiq.dev/framework">Statiq Framework</a> and this series covers a small fraction of the functionality of this fantastic project. So far I am very happy with this platform and am anticipating the release of <a href="https://statiq.dev/docs/">Statiq Docs</a> which is built on top of the Statiq Web with a focus on generating .NET API documentation.</p> <p>What static content generator have you used? Do you have a blog of your own that's statically generated? Share your experiences in the comments below.</p> <p><span>Special Thanks to <a href="https://unsplash.com/@fantasyflip?utm_source=unsplash&utm_medium=referral&utm_content=creditCopyText">Philipp Katzenberger</a> on <a href="https://unsplash.com/?utm_source=unsplash&utm_medium=referral&utm_content=creditCopyText">Unsplash</a> for the photo used for this post</span></p> </article> </main></body></html>