Announcing godot-playfab 1.3.0</h1> <article> <h1>Announcing godot-playfab 1.3.0</h1> <p>Thu, 05 Dec 2024 00:00:00 GMT</p> <h1 id="godot-playfab-update-1.3.0">Godot-PlayFab Update 1.3.0</h1> <p>After almost a year, I finally found the time to do revamp the CI pipeline that held up some updates. I'd like to take the opportunity to thank <a href="https://github.com/MikeSchulze">Mike Schulze</a> for making an awesome <a href="https://github.com/MikeSchulze/gdUnit4-action">GitHub Action</a> to run <a href="https://github.com/MikeSchulze/gdUnit4">GDUnit</a> Tests!</p> <p>Now, to the changes!</p> <h2 id="steam-login">Steam Login</h2> <p>Thanks to <a href="https://github.com/TheDedemon">TheDedemon</a> aka <em>Rémi Carreira</em>, godot-layfab now has support for Steam Logins! TheDedemon also contributed a guide on how to use it with Gramps Garcia's <a href="https://godotsteam.com/">GodotSteam</a>!</p> <h2 id="cleaner-install">Cleaner Install</h2> <p>One of the issues with versions up until now was, that it included not only the addon, but also the demo scenes and the tests. This was confusing to users, as they had to remove the demo scenes and tests manually. This is now fixed!</p> <p>When you download the addon, you only get the addon. If you want the demo scenes and tests, you can download them separately. More on that in the next section.</p> <h2 id="new-example-project">New Example Project</h2> <p>The new example repository <a href="https://github.com/Structed/godot-playfab-example">Structed/godot-playfab-example</a> includes - at this point - two example projects:</p> <ol> <li>A simple example project that shows how to use the addon</li> <li>The same project, but with a simple Steam Login implementation using <a href="https://godotsteam.com/">GodotSteam</a>.</li> </ol> <h2 id="where-to-get-the-addon">Where to get the Addon?</h2> <ul> <li>The Godot AssetLib: <a href="https://godotengine.org/asset-library/asset/1321">https://godotengine.org/asset-library/asset/1321</a></li> <li>The Itch.io Page: <a href="https://structed.itch.io/godot-playfab">https://structed.itch.io/godot-playfab</a></li> <li>The GitHub Release Page: <a href="https://github.com/Structed/godot-playfab/releases">https://github.com/Structed/godot-playfab/releases</a></li> </ul> </article> <article> <h1>Announcing godot-playfab 1.0</h1> <p>Sat, 03 Jun 2023 00:00:00 GMT</p> <h1 id="announcing-godot-playfab-1.0">Announcing godot-playfab 1.0</h1> <p>After two years of development in my spare time, I am very excited to announce that godot-playfab 1.0 is out!</p> <p>Grab it here while it's still fresh:</p> <p>➡️ <a href="https://github.com/Structed/godot-playfab">GitHub Repo</a>: Clone it to get all the bits!</p> <p>➡️ <a href="https://github.com/Structed/godot-playfab">GitHub Repo</a>: Clone it to get all the bits!</p> <p>➡️ <a href="https://godotengine.org/asset-library/asset/1321">AssetLib</a>: directly within Godot 4!</p> <p>➡️ <a href="https://structed.itch.io/godot-playfab">itch.io</a>: Scratch your itch there!</p> <p>➡️ <a href="https://github.com/Structed/godot-playfab/releases/tag/1.0.0">GitHub Release</a>: The same as what you get via the Godot Editor download</p> <h1 id="whats-new">What's new</h1> <h2 id="godot-4">Godot 4</h2> <p>The biggest change was the upgrade from Godot 3 to Godot 4, which does not mean a change for you as a user of the library per se, but it means that the library is now compatible with Godot 4.0 and up!</p> <h2 id="production-quality">Production Quality</h2> <p>The main reason I am making this a 1.0 release is that I consider the library to be production-ready, and I want to convey this fact via the version number. Since <a href="https://store.steampowered.com/app/1637320/Dome_Keeper/">Dome Keeper</a> (and some other projects) have been using it since earlier this year, I have been able to iron out most of the bugs and issues and feel comfortable recommending it as production-ready.</p> <h2 id="new-unit-testing-framework">New Unit Testing Framework</h2> <p>The Unit Testing Framework I had been using (GUT) was not compatible with Godot 4 at the time I was migrating. But migrating a library like godot-playfab requires to have at least some Unit Test coverage to ensure proper operation and therefore provide operational security to it's users. Particularly when you have a scripting engine with breaking changes.</p> <p>I then found <a href="https://github.com/MikeSchulze/gdUnit4">GDunit4</a> by <a href="https://twitter.com/LpzMikeschulze">Mike Schulze</a>. It's been a joy working with it an Mike has been great in addressing feedback. Special thanks go out to <a href="https://twitter.com/bitbrain">@Bitbrain</a>, who has helped me on this journey as well and inspired me with his GitHub Actions pipeline.</p> <h2 id="godot-3">Godot 3</h2> <p>While the library is now compatible with Godot 4, it is still compatible with Godot 3.5 and up. This is important for me, as may projects are still using Godot 3.5 and I want to continue to support them.</p> <h3 id="assetlib">AssetLib</h3> <p>However, I have migrated the AssetLib entry to it's own entry: <a href="https://godotengine.org/asset-library/asset/1756">godot-playfab-3</a>. This is to ensure that users of Godot 3.5 and up can still get the latest version of the library, while users of Godot 4 can get the latest version of the library for Godot 4.</p> <h3 id="fork">Fork</h3> <p>The codebase has been forked for Godot3, and all the code of the Godot 3 version will now have a <code>godot3</code> prefix in the branch name. The Godot 4 code will now live in the <code>main</code>/<code>develop</code> branches.</p> <h3 id="itch.io-github-releases">Itch.io / GitHub Releases</h3> <p>With the reduced investment and the added complexity by forking the codebase in the same code repository, I have decided to no longer publish releases on GitHub and Itch.io. If you want the latest bits, just use the AssetLib version or download directly from the <a href="https://github.com/Structed/godot-playfab/tree/godot3">godot3 branch</a>.</p> <h1 id="the-future">The Future</h1> <h2 id="godot-3-1">Godot 3</h2> <p>I will continue to support the Godot 3.x version, however I am considering it a legacy version. I will not add any new features to it, but I will continue to fix bugs and issues. But you can always talk to me and convince me otherwise!</p> <h2 id="godot-4-1">Godot 4</h2> <p>I will continue supporting the latest Godot4 version and will be adding new features. However, the most important features are already included. Do let me know if you have any feature requests and I am happy top build those in!</p> <p>Open a <a href="https://github.com/Structed/godot-playfab/discussions">Discussion item</a>, or <a href="https://github.com/Structed/godot-playfab/issues/new/choose">create an Issue</a> on GitHub!</p> <h1 id="commercial-services">Commercial Services</h1> <p>If you are looking for commercial services, such as support, custom development, or integration, please contact me via <a href="mailto:godot-playfab@structed.me">Email</a>, <a href="https://twitter.com/Structed">Twitter</a>, <a href="https://mastodon.social/@structed">Mastodon</a>, <a href="https://www.linkedin.com/in/johannesebner">Linkedin</a> ot our <a href="https://discord.gg/7K7q2YuNXe">godot-playfab Discord</a>.</p> </article> <article> <h1>The Game Developer's Travel Guide</h1> <p>Thu, 16 Mar 2023 00:00:00 GMT</p> <h1 id="why-a-travel-guide">Why a Travel Guide?</h1> <p>With GDC 2023 coming up next week and I see <a href="https://twitter.com/SanderVhove/status/1636040056099176448?s=20">people talking about in on Twitter</a>, I figured I could write down my tips & tricks for traveling as a gamedev I have gathered over the years!</p> <p>It's not inherently for gamedevs (in fact, it's not specific at all), but I consider my target audience to be gamedevs!</p> <h1 id="why-am-i-qualified">Why am I qualified?</h1> <p>I worked as a Gaming Solution Architect for over three years now, and I have had quite a few trips to many studios & events. So I know a thing or two about traveling as a gamedev!</p> <h1 id="show-me-the-tips">Show me the tips!</h1> <h2 id="get-a-good-trolley">1. Get a good trolley</h2> <p>Get a hard-shell trolley for your carry-on luggage. Hard shell, so it can protect your stuff. Like your laptop! Also, there are quite a few nifty ones out there with dedicated laptop opening, powerbank-pouch with a USB port, and even a TSA lock!</p> <p>Speaking of TSA Lock: if you want to lock your luggage, get a TSA lock. TSA locks are locks that can be opened by TSA agents, so they can check your luggage if they want to. If you use a regular lock, they will break it - or your trolley.</p> <h2 id="what-to-pack">2. What to pack?</h2> <h3 id="laptop">💻 Laptop</h3> <p>I always pack my laptop in my carry-on luggage. Specifically on a long-haul flight, you might want to work or play games on it.</p> <h3 id="power">⚡ POWER!</h3> <h4 id="powerbank">🔋 Powerbank</h4> <p>Also pack in your carry-on luggage. You never know when you need to charge your phone or laptop. I always carry a powerbank with me, and I always have a USB-C cable with me.</p> <h4 id="usb-condom">🛡️ USB Condom</h4> <p>You don't want to get your phone compromised by a USB port in an airport or elsewhere. So always use a USB condom.</p> <p>This is a USB adapter which disables the data lane. You can also make it yourself!</p> <p>Check out <a href="https://www.howtogeek.com/364032/how-to-protect-yourself-from-public-usb-charging-ports/">this guide on how you can protect yourself</a>.</p> <h4 id="usb-cables">🧵 USB cables</h4> <p>I need many. I have two Android phones (work and private), Samsung Galaxy Watch charging pad, Headphones, and a powerbank.</p> <p>Make a list, and pack them in a nice bag!</p> <p></p> <h3 id="headphones">🎧 Headphones</h3> <p>Noise canceling headphones are quite nice. I use Microsoft Surface Headphones 2.</p> <h3 id="power-supply">🔌 Power Supply</h3> <p>DO NOT FORGET YOUR POWER SUPPLY FOR YOUR LAPTOP! I have forgotten it once, and I had to buy a new one. It was not fun. And quite expensive.</p> <p>I also carry a multi-USB port power supply, so I can charge multiple devices at once. Each of the ports should have an output of 2A or more to achieve a significant charging speed.</p> <h3 id="outlet-adapter">🐽 Outlet Adapter</h3> <p>Traveling to another country? Make sure you have an outlet converter. There are these great <a href="https://www.amazon.de/dp/B07RPDCC7Z">cubes</a> which can adapt to a lot of different standards and also have USB ports.</p> <p></p> <h3 id="hdmi-cable">📺 HDMI Cable</h3> <p>You probably want to watch TV shows on your laptop or play games. So make sure you have an HDMI cable with you. HDMI is still the most common input for TVs across the world.</p> <p>Perhaps also get adapters for your switch or whatever console you are bringing to play!</p> <h3 id="display-adapter">📺 ➕ 💻Display Adapter</h3> <p>Speaking of adapters: you likely have a modern laptop or console which has only USB-C ports for display adapters. You definitely want to think about bringing one of these. They can be expensive!</p> <p></p> <h3 id="controller">🎮 Controller</h3> <p>If you're like me and use a laptop to play, don't forget to bring a controller.</p> <h2 id="general-travel-advice">General Travel Advice</h2> <h3 id="mobile-connectivity">📶 Mobile Connectivity</h3> <p>Make sure you research your options for local mobile connectivity.</p> <p>The easiest is of course roaming. But be careful! Roaming can be super expensive! Do research your options for your own carrier. If these are prohibitively expensive, you can get a local sim card in many countries. However, some countries like make it extremely hard to get one (legally).</p> <h3 id="download">🔽 Download!</h3> <p>Download whatever you need on your travels and is of significant size or might be market-restricted.</p> <p>You definitely need to use the download functionalities of Netflix, Amazon Prime etc, because it's not only large download sizes you might need to account for- but 🌍🤺 geofencing!</p> <p>I was once in India for a week and I was super remote and I could not get a local sim card, and the Wifi was unstable at best. I could only watch one show because the others were geofenced and I could not download them from India.</p> <h3 id="vpn">❌ VPN</h3> <p>VPNs sound interesting, but they are not a great idea. They're a privacy problem at best, and a massive security problem at worst.</p> <h3 id="book-an-aisle-seat">💺 Book an Aisle Seat!</h3> <p>You will then always be in the last boarding group. This means you can totally chill and you can:</p> <ul> <li>Arrive later at the airport</li> <li>You don;t have to stand in boarding queue forever</li> <li>Less time to sit in on the plane</li> </ul> <p><strong>But there is one important caveat:</strong></p> <blockquote> <p>⚠️ You might not have a lot of space for your carry-on luggage! So be sure to travel with a small piece or only use that strategy on short flights where you can take the bag under your seat.</p> </blockquote> <h1 id="conclusion">Conclusion</h1> <p>I hope my tips helped you with your travel! If they did, or you have some more suggestions, let me know via <a href="https://blog.structed.me/https;/twitter.com/structed" target="_blank">Twitter (@Structed)</a>!</p> <p>Thank you to <a href="https://twitter.com/SanderVhove" target="_blank">@SanderVhove</a> for the inspiration to write this post!</p> <p><span class="alert alert-light">Header Photo by <a href="https://unsplash.com/photos/RRNbMiPmTZY">Denys Nevozhai via Unsplash</a></span></p> </article> <article> <h1>Deep dive into PlayFab Events API</h1> <p>Tue, 14 Mar 2023 00:00:00 GMT</p> <h1 id="what-is-the-events-api">What is the Events API?</h1> <p>The <a href="https://docs.microsoft.com/en-us/rest/api/playfab/events/?view=playfab-rest">Events API</a> is a new API to send Telemetry and PlayStream events to PlayFab for later analysis or reactive programming (or event-driven architectures).</p> <p>The Events API supersedes the legacy <a href="https://docs.microsoft.com/en-us/rest/api/playfab/client/analytics?view=playfab-rest">Client Analytics API</a>. You can, however, still use the legacy API for convenience.</p> <p>But this article details why you should default to the new Events API 😊</p> <h1 id="events-api-vs-legacy-events-api">Events API vs Legacy Events API</h1> <p>The legacy API was designed for ease of use in client applications. It provides a number of convenient endpoints to ingest data pertaining to a certain context (e.g. Player, Character etc) into PlayStream.</p> <p>However, the way the legacy API works is that</p> <ul> <li>you can only ingest one event per call</li> <li>poses limited ingestion capabilities (API rate limits, client HTTP overhead)</li> <li>it does not support Telemetry Events</li> <li>it does not support the <a href="https://docs.microsoft.com/en-us/gaming/playfab/features/data/entities/">Entity Programming Model</a></li> </ul> <p>The Events API resolves all of the above limitations of the legacy API. You can <strong>batch multiple events</strong> in one request, massively increasing the amount of Events you can ingest into PlayFab while at the same time <strong>saving you money</strong> and r<strong>educing the overall bandwidth</strong> used on the client-side. This is particularly important in mobile scenarios. It also supports the <a href="https://docs.microsoft.com/en-us/gaming/playfab/features/data/entities/">Entity Programming Model</a>.</p> <p>The <strong>biggest advantage</strong>, however, is likely the costs savings by enabling you to use <em>Telemetry Events</em>. We will differentiate in the next section.</p> <h1 id="playstream-telemetry">PlayStream & Telemetry</h1> <p>You have read PlayStream and Telemetry a couple of times now - but what are these?</p> <p>PlayStream and Telemetry share the fundamental design. You can think of them as arbitrary events pertaining to a specific Entity (Title Player, Character etc.), holding a list of key-value pairs as payload.</p> <p>When you send any of these events to PlayFab, PlayFab will ingest them into it's data lake for you to later analyse with PlayFab's built-in or external tools.</p> <p>While the two event types look the same when you send them, there is a very big difference when they "arrive" at PlayFab:</p> <ul> <li>Telemetry Events are just ingested into a data lake and you can then run analytics on them</li> <li>PlayStream Events can be reacted upon after they arrive. More on that below.</li> </ul> <h2 id="example-sending-telemetry-events">Example: Sending Telemetry Events</h2> <p>This is how you send a Telemetry Event in the Godot engine using (my own) <a href="https://github.com/structed/godot-playfab">godot-playfab</a> addon. The Payload is completely arbitrary JSON:</p> <pre><code class="language-gdscript">func _on_WriteTelemetryDirectButton_pressed(): var payload = { "Action": "_on_WriteTelemetryDirectButton_pressed" } PlayFabManager.event.write_title_player_telemetry_event(EVENT_NAME_TELEMETRY, payload) </code></pre> <p>And the unity version:</p> <pre><code class="language-csharp">EventsModels.WriteEventsRequest request = new EventsModels.WriteEventsRequest(); request.Events = new List<EventsModels.EventContents>(); // Some metadata (required) EventsModels.EventContents eventInfo = new EventsModels.EventContents(); eventInfo.Name = "unity_client_api_error_occurred"; eventInfo.EventNamespace = eventNamespace; eventInfo.Entity = entityKey; eventInfo.OriginalTimestamp = DateTime.UtcNow; // Custom payload var payload = new Dictionary<string, object>(); payload["ErrorCode"] = errorCode; payload["ErrorType"] = type; eventInfo.Payload = payload; request.Events.Add(eventInfo); var result = await eventApi.WriteTelemetryEventsAsync(request); </code></pre> <h1 id="working-with-the-playstream">Working with the PlayStream</h1> <p>PlayStream is different in the way that PlayStream events can be <strong>used to react to them in near-realtime</strong>: you can not only analyse them after the fact with PlayFab's analytics capabilities - but you can also use them for event-driven architectures and reactive programming!</p> <p>For instance, you can set up a <a href="https://docs.microsoft.com/en-us/gaming/playfab/features/automation/actions-rules/quickstart">Rule</a> in PlayFab to run an Azure Function or gift an item if a specific event is appearing in the PlayStream. Check out my <a href="https://blog.structed.me/posts/extending-playfab-with-azure-functions">in-depth walk-through</a> on how to do this - or have a look at our example project, where we used PlayStream to <a href="https://blog.structed.me/posts/playfab-match-history">implement a Match History</a>!</p> <blockquote> <p>⚠️ Caution: Do <em><strong>not</strong></em> block on PlayStream events, e.g. waiting in your game UI for an event to appear in the PlayStream! PlayStream events are <em><strong>not real-time</strong></em>!</p> </blockquote> <h1 id="built-in-events">Built-in events</h1> <p>Even without implementing your own events, PlayFab already collects a lot of data for you just through built-in events triggered by API usage. For example, whenever a user logs in, events are generated. This data will be available for you to use in analytics, but also - just like your own events - can be used for automation or segmentation of users. When looking at segmentation, PlayFab has already pre-made segmentation for the most common use-cases like "Lapsed players", which shows you a list of users who have not been logging in since more than 30 days.</p> <p></p> <h1 id="using-events">Using Events</h1> <p>Once you ingested Events through the API, whether by creating your own or through built-in facilities, you can start using the data in multiple ways:</p> <h2 id="analysing-telemetry">Analysing Telemetry</h2> <p>Using PlayFab's built-in analytics capabilities, you can analyse player behaviour or your system's performance. If you require even more data analytics capabilities, you can also export the data!</p> <h3 id="title-overview">Title Overview</h3> <p>When you open the PlayFab Game Manager for a given Title, the first page will always be the <em>Title Overview</em>. As you can see, PlayFab is already presenting you with a dashboard based on built-in events!</p> <p>If you switch to the next Tab, PlayStream Monitor, you can see PlayStream events appearing in near-realtime as PlayFab ingests them, so you can inspect them and can even see where they appear on the world map.</p> <p></p> <h3 id="dashboards">Dashboards</h3> <p>A recent addition to the GameManager (and currently in public preview) is the <em>Trends</em> tab in the <em>Dashboards</em> section. There, PlayFab uses built-in events to provide you with a few important trends to see how your game is performing: </p> <p>On the second tab of the <em>Dashboards</em> pane, you can view and download reports. You can also click on a report and get an awesome, detailed dashboard for it! </p> <p></p> <h3 id="data">Data</h3> <p>In the <em>Data</em> section of the Game Manager, you can go really deep. The <em>Data Explorer</em> is an integration of <em>Azure Data Explorer</em> directly into PlayFab's GameManager. There is a "basic" tab, which gives you a basic UI to do some analytics. If you want to go deeper, you can use the "advanced" tab, which lets you write your own queries using the SQL-like <em>Kusto Query Language</em> (abbreviated as "KQL"). You can also export the raw event data, either periodically (<em>Event Export</em>) or continuously (<em>Data Connections</em>) to use the data in other analytics systems of your choice.</p> <p>If you want to learn KQL, here's a fun way to learn it - the <a href="https://detective.kusto.io/inbox">Kusto Detective Agency</a>!</p> <h2 id="automation">Automation</h2> <p>You may use PlayFab's Automation functionality to react to PlayStream Events. Without writing additional code, you can use PlayFab's <em>Rules</em> to react to events. Just specify the event type you invented while creating the event, and set up conditions and actions. For example, you might want to send a welcome Email once a player registered for your game:</p> <p></p> <p>You might as well use use CloudScript Functions to trigger backend code execution via Azure Functions to be even more flexible To achieve that, you can set up a <a href="https://docs.microsoft.com/en-us/gaming/playfab/features/automation/actions-rules/quickstart">Rule</a> in PlayFab to run an Azure Function if a specific event is appearing in the PlayStream. Check out my <a href="https://blog.structed.me/posts/extending-playfab-with-azure-functions">in-depth walk-through</a> on how to do this - or have a look at our example project, where we used PlayStream to <a href="https://blog.structed.me/posts/playfab-match-history">implement a Match History</a>!</p> <h1 id="conclusion">Conclusion</h1> <p>In this post, I showed you the differences of the legacy and the new Events API and why you should use the Events API going forward to reduce cost and overhead and enabling you to write Telemetry events, which can further lower your cost.</p> <p>You als o got a glimpse of the possibilities of PlayFab's built-in analytics capabilities and how you can use PlayStream events to react to them in near-realtime.</p> </article> <article> <h1>Raspberry PI as a Spotify music station</h1> <p>Sat, 30 Jul 2022 00:00:00 GMT</p> <h1 id="introduction">Introduction</h1> <p>In this post, we set up a RaspberryPi to play music via Spotify Connect.</p> <h1 id="prerequisites">Prerequisites</h1> <ul> <li>A Spotify Premium account</li> <li>A RaspberryPI (I uses a RaspberryPi 2 model B), including: <ul> <li>SDCard</li> <li>WiFi Dongle or Ethernet cable</li> <li>Speakers (with audio jack plug)</li> </ul> </li> </ul> <h1 id="overview">Overview</h1> <p>We will first flash a standard image for the RaspberryPi. But we will make custom configurations to connect to a Network or WiFi and set up SSH to allow for remote administration.</p> <h1 id="flashing-the-image">Flashing the image</h1> <p></p> <p>First, plug in your SDCard. Then, get the <a href="https://www.raspberrypi.com/software/">Raspberry Pi Imager</a> from the official website. Once downloaded and install, select an image (1), I used the recommended image.</p> <p>The next step is to select a storage (2). Be <em><strong>VERY</strong></em> careful with this. If you select the wrong storage, you might overwrite another storage drive!</p> <p><strong>Before</strong> clicking the <strong>WRITE</strong> button (4), click on the cogwheel in the lower right corner (3). This will show you advanced configurations. Set the options appropriate to you. If you enable WiFi, you should obviously have a WiFi dongle compatible with the Raspberry Pi.</p> <p></p> <blockquote> <p>If you enable SSH, and you put the RaspberryPi in the same network as another machine, you can then use SSH to administer it. So you don't have to set up a display and keyboard!</p> </blockquote> <p>Once you set your options, exit the dialog and click "WRITE".</p> <h1 id="booting-initial-set-up">Booting & initial set-up</h1> <p>Plugin in the power for your RaspberryPi and wait a bit for it to boot. Then, use <code>ssh</code> to log in. On a Windows 11 machine with <a href="https://docs.microsoft.com/en-us/windows/terminal/install">Windows Terminal</a>, you don't even need to install additional tools. You can just use SSH from the Terminal!</p> <blockquote> <p>If you changed user, hostname and or port in the image configuration before flashing the image, please make sure to use these!</p> </blockquote> <p>Mine would look like this, where <code>structed</code> is my username and <code>raspberrypi</code> the hostname:</p> <pre><code class="language-bash">ssh structed@raspberrypi.local </code></pre> <p>The first logon may take a bit.</p> <h3 id="updating-the-system">Updating the system</h3> <p>Once logged in, fire up the configuration tool. Type:</p> <pre><code>sudo raspi-config </code></pre> <p>Navigate to <code>update</code> and select it to update your system - this will take a while.</p> <p></p> <p>Once the update is complete, <code>raspi-config</code> will automatically restart. You can now make additional changes, or close it.</p> <h3 id="disable-desktop-ui">Disable Desktop UI</h3> <p>If you're like me, you may want to disable the graphical desktop interface to save resources, as I will only run the RaspberriPi without a display.</p> <p>Still in <code>raspi-config</code>, choose <code>System Options</code>. In the next menu, choose <code>Boot / Auto Login</code>. In the last menu, I chose <code>Console Autologin Text console, automatically logged in as '<username>' user</code> (where <code><username></code> is your username)</p> <p>Once you're done configuring, exit with the <code>Finish</code> option in the <code>raspi-config</code> or press <code>ESC</code> until you exit to shell.</p> <h1 id="installing-spotifyd">Installing <code>spotifyd</code></h1> <p><code>spotifyd</code> is a daemon that runs on the Raspberry Pi. It is used to connect to Spotify and play music. Installing <code>spotifyd</code> allows us to play Spotify music on this device controlled by any other Spotify Connect enabled device. So once setup, we can control it e.g. from a phone.</p> <p>For the setup, we'll essentially follow the official <a href="https://spotifyd.github.io/spotifyd/installation/Raspberry-Pi.html"><code>spotifyd</code> installation instructions for RaspberryPi</a>:</p> <ol> <li>Go to the <a href="https://github.com/Spotifyd/spotifyd/releases">Releases page</a> and download the latest release (in my case, my architecture is <code>armhf</code> for RaspberryPi 2): (<code>spotifyd-linux-armhf-default.tar.gz</code>) as well as the sha51 file <code>spotifyd-linux-armhf-default.tar.gz</code></li> </ol> <ul> <li><code>wget https://github.com/Spotifyd/spotifyd/releases/download/v0.3.3/spotifyd-linux-armhf-default.tar.gz</code></li> <li><code>wget https://github.com/Spotifyd/spotifyd/releases/download/v0.3.3/spotifyd-linux-armhf-default.sha512</code></li> </ul> <ol start="2"> <li><p>Verify the integrity of the downloaded file:</p> <ul> <li><code>sha512sum -c spotifyd-linux-armhf-default.sha512</code></li> <li>If the download was OK, it will show this output: <code>spotifyd-linux-armhf-default.tar.gz: OK</code></li> </ul> </li> <li><p>Extract the <code>spotifyd-linux-armhf-default.tar.gz</code> file to the <code>/opt/spotifyd</code> directory:</p> <ul> <li><code>tar -xzf spotifyd-linux-armhf-default.tar.gz -C /usr/bin/</code></li> </ul> </li> <li><p>Create the systemd service file:</p> <blockquote> <p>Depending whether you want to run as root or as the logged in user, the steps would be a bit different. I want to run as my <code>structed</code> user, so I'll use the following steps. IF you want to go for root, <a href="https://spotifyd.github.io/spotifyd/installation/Raspberry-Pi.html">check the docs</a>.</p> </blockquote> <ul> <li>Create the systemd user config directory: <code>mkdir -p ~/.config/systemd/user/</code></li> <li>Create the systemd config file: <code>nano ~/.config/systemd/user/spotifyd.service</code></li> <li>Paste the contents of the <a href="https://github.com/Spotifyd/spotifyd/blob/master/contrib/spotifyd.service">spotifyd.service</a> from the <code>spotifyd</code> repository.</li> <li>Save the file.</li> </ul> </li> <li><p>Configure <code>spotifyd</code>:</p> <ul> <li>Create the config directory: <code>mkdir ~/.config/spotifyd/</code></li> <li>Create the config file: <code>nano ~/.config/spotifyd/spotifyd.conf</code></li> </ul> <blockquote> <p>Please change the values for <code>username</code>, <code>password</code>, <code>device_name</code>!</p> </blockquote> <pre><code class="language-toml">[global] username = "USER" password = "PASS" backend = "alsa" device = "hw" # Given by `aplay -L` mixer = "PCM" volume-controller = "softvol" # or alsa_linear, or softvol #onevent = command_run_on_playback_event device_name = "rpi-kids" bitrate = 320 cache_path = "cache_directory" volume-normalisation = true normalisation-pregain = -10 </code></pre> <p>You might also want to reduce the <code>bitrate</code> (<code>160</code> or <code>96</code>) and/or change the volume <code>volume-controller</code>.</p> <p>For more information on the config file, like how you can work around storing your password in the config file, <a href="https://spotifyd.github.io/spotifyd/config/File.html">see the documentation</a>.</p> </li> <li><p>Reload the daemon: <code>systemctl --user daemon-reload</code></p> </li> </ol> <h1 id="testing-spotifyd">Testing <code>spotifyd</code></h1> <p>Run <code>/usr/bin/spotifyd --no-daemon</code> to test <code>spotifyd</code>. Once started, use another device, like your mobile phone, and open Spotify. There, click the "loudspeaker" button (1) to select the device. In my case, it's <code>raspi-kids</code> (2). Then click play!</p> <p></p> <p>If you have a device plugged in to your headphone jack on the RaspberryPi, you should now hear the music play!</p> <h1 id="installing-the-systemd-daemon">Installing the systemd daemon</h1> <p>First, we start the daemon again, as we want to use the daemon instead of calling the binary from the terminal, which blocks input. And it would nto survive a reboot, anyways.</p> <p><code>systemctl --user start spotifyd.service</code></p> <p>However, for the service to restart and be kept alive upon reboot, we have to issue these commands:</p> <pre><code>sudo loginctl enable-linger <username> systemctl --user enable spotifyd.service </code></pre> <p>The first command is required to enable your user to run long-running services. Without it systemd would kill the <code>spotifyd</code> process as soon as you log out, and only run it when you log in. Now <code>spotifyd</code> is always running on the Pi, so you can use it as a listening device remotely!</p> <h1 id="conclusion">Conclusion</h1> <p>We set up a RaspberryPi for remote administration, so we never require a display or keyboard. We then set up <code>spotifyd</code> to play music on the RaspberryPi, and we can control it from a phone or another device with the Spotify app.</p> </article> <article> <h1>Modern Game Studio - How to transfer builds and large files in a distributed environment?</h1> <p>Mon, 29 Nov 2021 00:00:00 GMT</p> <p>A common topic that came up during the pandemic is the "Modern Game Studio" - a studio that enables everyone to work from wherever they are. Whether you are at home, or a Studio location. Whether you are using a capable workstation with a beefy GPU or just have a "regular" laptop at your disposal.</p> <p>We have talked to many partners who were challenged not only with many studio locations, but folks working from home temporarily or some of them have moved to other countries or continents altogether and are not planning to return to an office.</p> <p>Among the challenges this new way of working poses to studios is the need to transfer - and sync - large files all over a country, continent or the world. These could be, for example:</p> <ul> <li>Debug builds to be <ul> <li>distributed to testers</li> <li>distributed to contractors, publishers etc</li> <li>stored for long-term retention</li> </ul> </li> <li>Full crash dumps for developers to look into</li> <li>Large asset storage</li> </ul> <h1 id="scenario">Scenario</h1> <p>Take, for example, a large game studio which has multiple physical locations around the globe, with one central studio hosting all their services locally.</p> <p>The internet connection of the office locations - and particularly the primary location which hosts the services - needs to scale with the demand. Also the local services hosted on-prem need to be up to the task.</p> <p>Pre-pandemic, this might have been set up specifically and might have been enough. But adding a lot of home office clients, and then opening new studio locations, creates a huge challenge and usually makes the main office internet connection a choke point, specifically when distributing builds or large, full crash dumps.</p> <h2 id="issues-faced">Issues faced</h2> <p>With large file shares, these are the common issues faced with a primary on-site location and multiple other studio locations, and added home office clients:</p> <ul> <li>Main office bandwidth exceeded</li> <li>High latency when requesting and uploading files</li> <li>Potentially increased internet egress cost</li> <li>Non-trivial disaster recovery scenario</li> </ul> <h1 id="solution">Solution</h1> <p>A solution we have come up with to make this a better experience for a distributed studio is to use Azure as the central authority for all file shares.</p> <p></p> <h2 id="architecture">Architecture</h2> <p></p> <p>With <a href="https://docs.microsoft.com/en-us/azure/storage/files/">Azure Files</a> and <a href="https://docs.microsoft.com/en-us/azure/storage/file-sync/file-sync-introduction">File Sync</a>, you have a central file share repository, which can be synced to on-premise locations. At these locations, a Windows File Server with the Azure File Sync service installed, can act as a local cache.</p> <p>While it is possible for Workstations in the cloud or other users to be directly accessing the Storage Account, this is discouraged, because there is no built-in functionality to signal file changes.</p> <h3 id="local-cache-tiered-files">Local Cache & Tiered files</h3> <p>While all files of the shares are available to clients, they are tiered: this means, they will only reside in the cloud unless used. To clients however, they appear as available to them. All file operations hit this local File Server replica, and will be synced to the Azure File Share, using the Azure File Service, which in turn persists it in the Storage Account.</p> <h3 id="improving-studio-locations-uplink-to-azure">Improving Studio locations uplink to Azure</h3> <p>When you transfer files from and to Azure, these will normally be routed via public internet. This will incur additional latency and will be subject to local link degradations and generate data egress cost into the public internet. To improve this quality, security and potentially save on egress cost from Azure, you can set up <a href="https://azure.microsoft.com/en-us/services/expressroute/">Azure Express Route</a>. ExpressRoute can directly connect you with the Microsoft Azure Network and create a private network between your and the Azure network.</p> <h1 id="benefits">Benefits</h1> <ul> <li>Automatic, consistent replication</li> <li>Improved data recovery & business continuity by having a backup in the cloud</li> <li>Cost savings on data egress by <ul> <li>using tiered sync to on-prem locations</li> <li>Creating builds in the cloud</li> <li>Crash dumps created in the cloud by automated test runners or workstations in the cloud</li> </ul> </li> <li>With ExpressRoute <ul> <li>Save on data egress using unlimited data plan on ExpressRoute</li> <li>Increase quality of connection</li> <li>Enhance security</li> </ul> </li> </ul> <h1 id="conclusion">Conclusion</h1> <p>We have looked ar the challenge and how to potentially solve the distribution of large files over very disparate locations.</p> <p>Make sure to check out the following services to learn more about them:</p> <ul> <li><a href="https://docs.microsoft.com/en-us/azure/storage/files/">Azure Files</a></li> <li><a href="https://docs.microsoft.com/en-us/azure/storage/file-sync/file-sync-introduction">File Sync</a></li> <li><a href="https://azure.microsoft.com/en-us/services/expressroute/">Azure Express Route</a></li> </ul> <p>Please do not hesitate to <a href="mailto:Johannes.Ebner@microsoft.com?subject=Modern%20Game%20Studio">contact me</a> - I'd love to see your approach to the Modern Game Studio - or perhaps my team and I can help you build the Modern Game Studio in the Cloud!</p> <blockquote> <p>Title Photo by <a href="https://unsplash.com/@sidharthbhatia?utm_source=unsplash&utm_medium=referral&utm_content=creditCopyText">Sidharth Bhatia</a> on <a href="https://unsplash.com/s/photos/synchronized?utm_source=unsplash&utm_medium=referral&utm_content=creditCopyText">Unsplash</a></p> </blockquote> </article> <article> <h1>PlayFab Match History - Extending PlayFab during Hackweek 2021</h1> <p>Thu, 21 Oct 2021 00:00:00 GMT</p> <p>In my last post, I talked about <a href="https://blog.structed.me/posts/extending-playfab-with-azure-functions">extending PlayFab with Azure Functions</a>.</p> <p>In today's post, we expand on this topic and I will show you what my team mate <a href="https://github.com/annonator">Andreas</a> and I built during Microsoft Global Hackathon (aka Hackweek) 2021:</p> <blockquote> <p>Microsoft Global Hackathon is an internal Hackathon where Microsoft employees all over the world devote full three work-days to a project of their liking.</p> </blockquote> <h1 id="our-project">Our Project</h1> <p>Let me introduce you to: <a href="https://github.com/XBOX-CSM/PlayFabMatchHistoryExtension">PlayFab Match History Extension</a>!</p> <p>This is a proof-of-concept implementation of an extension for <a href="https://playfab.com/">PlayFab</a>, which uses a custom <a href="https://docs.microsoft.com/en-us/gaming/playfab/features/automation/playstream-events/">PlayStream Event</a> to signal the end of a match on a game server.</p> <p></p> <h2 id="components-flow">Components & Flow</h2> <p>We use the PlayStream to trigger an <a href="https://docs.microsoft.com/en-us/azure/azure-functions/functions-overview">Azure Function</a> via <a href="https://docs.microsoft.com/bs-latn-ba/azure/storage/queues/">Azure Storage Queues</a> (instead of HTTP to make it more resilient).</p> <p>The Azure Function, triggered via the Storage Queue, persists the event data in an <a href="https://docs.microsoft.com/en-us/azure/cosmos-db/introduction">Azure Cosmos DB</a> Container. We use the <a href="https://docs.microsoft.com/en-us/azure/cosmos-db/serverless">Serverless SKU</a> here, as we try to generate as less cost as possible during development. If you have higher and constant demand, switching to a <a href="https://docs.microsoft.com/en-us/azure/cosmos-db/how-to-choose-offer">provisioned RU model (manual or automatic)</a> is recommended for performance.</p> <p>Another Azure Function App exposes a Web API, which allows querying the data in the CosmosDb. The API exposes an <a href="https://www.openapis.org/">OpenAPI</a> (Swagger) endpoint and is secured using PlayFab authentication, to also demonstrate this integration.</p> <p></p> <p>Both Azure Function apps have <a href="https://docs.microsoft.com/en-us/azure/azure-monitor/app/app-insights-overview">Application Insights</a> enabled for them to monitor performance, anomalies and usage. Both log to the same Azure Log Analytics Workspace, which enables us to use the <a href="https://docs.microsoft.com/en-us/azure/data-explorer/kusto/query/">Kusto Query Language</a> to analyse the usage of the Functions.</p> <p>The infrastructure is set-up using <a href="https://www.terraform.io/">Terraform</a>, to provide reproducible infrastructure ready to deploy the above mentioned application components on.</p> <p></p> <p>We used <a href="https://github.com/features/actions">GitHub Actions</a> to continuously deploy the applications to the provisioned infrastructure on every push and pull request. <a href="https://github.com/XBOX-CSM/PlayFabMatchHistoryExtension/blob/main/.github/workflows/main.yml">See our workflow</a>.</p> <p>There are still a few manual steps to do, like creating an Azure Service Principal and setting up your PlayFab title and the Azure Functions binding within your title. You can check out my <a href="https://blog.structed.me/extending-playfab-with-azure-functions">post on a detailed walk-through on how to set up Azure Function bindings</a>!</p> <h1 id="going-further">Going Further</h1> <p>While this project is not ready for production use, go ahead and fork the project. Then adapt it to your needs!</p> <p>Here are some ideas of what you can do with it:</p> <ul> <li>Get the amount of matches a player has played/won/lost and a ratio of that</li> <li>Get the top match winners</li> <li>Determine whom a player plays most with</li> <li>Add more meta data and determine the most liked map/weapon etc.</li> <li>Connect the Cosmos DB to PowerBI and use it for visualization!</li> </ul> <h1 id="conclusion">Conclusion</h1> <p>Let me know on <a href="https://twitter.com/structed">Twitter</a> on what you are building with this or let me know your feedback.</p> <p>Do feel free to <a href="https://github.com/XBOX-CSM/PlayFabMatchHistoryExtension">contribute to the project</a> if you have an idea how to make this better usable for others!</p> </article> <article> <h1>Extending PlayFab - Reacting to PlayStream Events with Azure Functions</h1> <p>Wed, 07 Jul 2021 00:00:00 GMT</p> <h1 id="introduction">Introduction</h1> <p>As my teammate Andreas Pohl wrote in his article <a href="https://developer.microsoft.com/en-us/games/blog/build-vs-buy-which-online-service-is-right-for-my-game/">Build vs. Buy - Which online service is right for my game</a>, PlayFab is a great way to get started with a backend for your game.</p> <p>Now you started with PlayFab and you have come to the point where you want to extend the functionality with your own game logic, for example by leveraging <a href="https://docs.microsoft.com/en-us/gaming/playfab/features/automation/playstream-events/">Azure PlayFab's PlayStream</a> and reacting to it's events. How would you do that?</p> <p>Good news: PlayFab has an integration with <a href="https://azure.microsoft.com/en-us/services/functions/">Azure Functions</a>! In this article, I will show you how you can react to PlayStream Events with Azure Functions and Azure Storage.</p> <h2 id="discourse-what-are-azure-functions">Discourse: What are Azure Functions?</h2> <p>From the <a href="https://docs.microsoft.com/en-us/azure/azure-functions/functions-overview">official documentation</a>:</p> <blockquote> <p>Azure Functions allows you to run small pieces of code (called "functions") without worrying about application infrastructure. With Azure Functions, the cloud infrastructure provides all the up-to-date servers you need to keep your application running at scale.</p> <p>A function is "triggered" by a specific type of event. <a href="https://docs.microsoft.com/en-us/azure/azure-functions/functions-triggers-bindings">Supported triggers</a> include responding to changes in data, responding to messages, running on a schedule, or as the result of an HTTP request.</p> <p>While you can always code directly against a myriad of services, integrating with other services is streamlined by using bindings. Bindings give you <a href="https://docs.microsoft.com/en-us/azure/azure-functions/functions-triggers-bindings">declarative access to a wide variety of Azure and third-party services</a>.</p> </blockquote> <h2 id="goal">Goal</h2> <p>This is a detailed end-to-end example on how to extend Azure PlayFab with Azure Functions.</p> <p>We will be using C# & .NET Core to create an Azure Function and bind it to a <a href="https://docs.microsoft.com/en-us/gaming/playfab/features/automation/playstream-events/">PlayStream Event</a>. The event to bind to will be the <code>player_created</code> Event, which fires every time a new player registers. The binding will then call the Azure Function.</p> <p>This Azure Function will add "User Data" to this new Player.</p> <blockquote> <p>Title User Data is title-specific custom data for the user which is readable and writable by the client. But you can of course set this via the Server as well. Player Data and User Data are terms used interchangeable within PlayFab terminology. Please refer to the <a href="https://docs.microsoft.com/en-us/gaming/playfab/features/data/playerdata/quickstart">documentation</a> for more information.</p> </blockquote> <h2 id="prerequisites">Prerequisites</h2> <h3 id="editoride">Editor/IDE</h3> <p>While you can follow along with basically any Editor/IDE, I will be using <a href="https://visualstudio.microsoft.com/">Visual Studio 2019</a> (you may use the the <strong>free</strong> Visual Studio 2019 Community Edition!) because it has all the batteries included for our tasks ahead.</p> <blockquote> <p>If you do not use Visual Studio, but want to use another IDE/Toolset, there are examples for creating & publishing Azure Function Apps with <a href="https://docs.microsoft.com/en-us/azure/azure-functions/functions-create-first-function-vs-code?pivots=programming-language-csharp">Visual Studio Code</a> or via <a href="https://docs.microsoft.com/en-us/azure/azure-functions/functions-create-first-azure-function-azure-cli?tabs=bash%2Cbrowser&pivots=programming-language-csharp">CLI</a>.</p> </blockquote> <h3 id="azure-access">Azure Access</h3> <p>If you do not yet have used Azure, you <a href="https://azure.microsoft.com/en-us/free/gaming/">sign up for free</a> and get some additional goodies with <a href="https://visualstudio.microsoft.com/dev-essentials/">Visual Studio Dev Essentials</a> program.</p> <h3 id="azure-playfab-access">Azure PlayFab access</h3> <p>And, of course, since this is a Tutorial on how to use <a href="https://playfab.com/">Azure PlayFab</a>, you need an existing Title on PlayFab as well. You could use the same Microsoft Account you used for signing up to Azure. Remember: There is a <a href="https://developer.playfab.com/en-US/sign-up">free tier to get you started</a>!</p> <h1 id="getting-started">Getting Started</h1> <p>As there are so many languages and platforms supported by Azure PlayFab and Azure Functions, I had to decide for one and chose the language and platform I am best in: Pure C# & .NET Core. But there are great guides for various Game Engines like Unity and Unreal, and PlayFab provides SDKs for a plethora of languages that are very similar to the C# SDK because they are all auto-generated from the same REST API.</p> <p>So while this is C#, most of what we do here is very similar in other languages/runtimes</p> <h2 id="project-setup">Project Setup</h2> <h3 id="create-an-azure-functions-project">Create an Azure Functions Project</h3> <p>To create an Azure Functions Project, open up Visual Studio and either use the splash screen (see screenshot below) or use File --> New Project…</p> <p></p> <p>Select the project type “Azure Functions” and click “Next”</p> <p></p> <p>Choose a name for your Project and select the folder for it to be placed in:</p> <p></p> <p>This will create a folder named according to your Solution name, in which it will create another folder for the project, with the Project’s name you chose.</p> <p>Now, in the next dialog, you may either choose an <code>HttpTrigger</code> or a <code>QueueTrigger</code> for your Function. Please choose <code>QueueTrigger</code>.</p> <blockquote> <p>Please be aware that Azure PlayFab terminates PlayStream-invoked Azure Functions after 1 second, thus <code>QueueTrigger</code> is the better choice here since it will immediately yield back to Azure PlayFab.</p> </blockquote> <p>For the Storage Account drop-down, you may use Storage Emulator (which comes with Visual Studio or you can use the new <a href="https://docs.microsoft.com/en-us/azure/storage/common/storage-use-azurite">"Azurite"</a>, which is the new generation of the Storage Emulator) or click “Browse…” to select a Storage Account. As we will need to test it with Azure PlayFab anyways, let’s go ahead and use an Azure Storage Account. Please click "Browse…" to create a new Storage Account:</p> <p></p> <p>In the next dialog, click "Create a storage account"</p> <p></p> <p>When creating the storage account, make sure to create a unique name. It actually has to be globally unique, because it will be part of the URI. You will see a warning if it is not unique.</p> <p>Also, you should create a new resource group for this project. A resource group is basically the topmost container in Azure and can contain all the different resources we are going to create. For example, if you want to remove all of the things we are creating in this article, you could just remove the resource group. <a href="https://docs.microsoft.com/en-us/azure/azure-resource-manager/management/overview">You can read more about the Resource Manager deployment model and resource groups in the documentation</a>.</p> <p>Last, let's think about the Account type. While it is enough for the sake of this tutorial to choose "LRS - Locally Redundant Storage", it it is worth considering <a href="https://docs.microsoft.com/en-us/azure/storage/common/storage-redundancy">other redundancy options</a> for different use-cases.</p> <p>Click "Create" when you have filled all fields and created a resource group.</p> <p></p> <p>Now back to the Storage Account select screen, select the one you just created and click "Add".</p> <p></p> <p>The Storage Account should now appear in the drop-down, beneath "Storage Emulator" and "Browse...". Select it.</p> <p>I would advise to leave "Connection string setting name" empty for now. Using this would create a new setting and would be a bit confusing for now.</p> <p>For "Queue name", make up a name for the storage queue (which we will actually create later). It does not have to have a unique name, but it may only use characters, numbers and dashes.</p> <p>Just call it <code>login-events</code> for now.</p> <p></p> <p>Once you are done setting up the Storage Account configuration, click the “Create” button and wait for the project to generate. Visual Studio will eventually open the project and show you the code of the generated Azure Function stub (your namespace name may vary):</p> <pre><code class="language-csharp">using System; using Microsoft.Azure.WebJobs; using Microsoft.Azure.WebJobs.Host; using Microsoft.Extensions.Logging; namespace PlayFabEventStreamHandler { public static class Function1 { [FunctionName("Function1")] public static void Run([QueueTrigger("login-events", Connection = "")]string myQueueItem, ILogger log) { log.LogInformation($"C# Queue trigger function processed: {myQueueItem}"); } } } </code></pre>  <blockquote> <p>You might have noticed, that the Function was named <code>Function1</code>, because Visual Studio just does not know what we want to do. Please rename the File, Class and the Function name in the Annotation as <code>PlayStreamEventHandler</code>.</p> <p>Renaming is done easiest in Visual Studio by right-clicking the Class name in the code editor and selecting "Rename" (or just press F2). This will open a tiny dialog asking you where you want to replace. Select "Rename file" and "Include strings". This will make sure Class and File are renamed as well as the Attribute string.</p> </blockquote> <p></p> <p>While asking for a Connection string setting in the dialog, we did not give it a name. The reason is, that Visual Studio adds a connection string to the Storage Account we previously selected, by default It is called <a href="https://docs.microsoft.com/en-us/azure/azure-functions/functions-app-settings#azurewebjobsstorage"><code>AzureWebJobsStorage</code></a>. This is set in the <code>local.settings.json</code> config file:</p> <p></p> <blockquote> <p><code>local.settings.json</code> is a config file <em>only</em> for local configuration. For deployed functions, you can either use the <a href="https://docs.microsoft.com/en-us/azure/azure-functions/functions-how-to-use-azure-function-app-settings">Application Settings built into Azure Functions</a>, or for more advanced scenarios, you could use <a href="https://docs.microsoft.com/en-us/azure/azure-app-configuration/overview">Azure App Config</a>.</p> </blockquote> <p>But because we did not give the connection setting a name earlier, there was no name set in the function. If you look closely at the Azure Function code, you can spot it in the Signature of the <code>Run</code> method. Look at the <code>Connection = ""</code> property of the <code>QueueTrigger</code> attribute:</p> <pre><code class="language-csharp">public static void Run([QueueTrigger("login-events", Connection = "")]string myQueueItem, ILogger log) </code></pre> <p>We just need to put in <code>AzureWebJobsStorage</code> instead of the empty string to load the right connection string:</p> <pre><code class="language-csharp">public static void Run([QueueTrigger("login-events", Connection = "AzureWebJobsStorage")]string myQueueItem, ILogger log) </code></pre> <h3 id="add-the-azure-playfab-package">Add the Azure PlayFab package</h3> <p>The Azure PlayFab SDK for C# is available via NuGet. You can either add the latest version via the dotnet CLI</p> <pre><code>dotnet add package PlayFabAllSDK </code></pre> <p>Or via the NuGet package manager in Visual Studio: Right-click “Dependencies” and click “Manage NuGetPackages”</p> <p></p> <p></p> <p>Open the “Browse” tab and search for PlayFab. Select the <code>PlayFabAllSDK</code> and click “Install” on the details pane to install. You might need to accept licenses when you do.</p> <blockquote> <p>Please note: you should also update the installed packages because the Visual Studio template ships with a slightly older version of the SDKs for Azure Functions and WebJobs Storage.</p> </blockquote> <h3 id="create-a-storage-queue">Create a Storage Queue</h3> <p>The last missing piece before we have all the infrastructure to test the Function the first time is a <a href="https://azure.microsoft.com/en-us/services/storage/queues/">Storage Queue</a>. Now let's create one!</p> <p>Go to the Azure Portal and open up your Storage Account’s Queue blade:</p> <p></p> <p>Created a Queue by clicking the “+ Queue” button. Make sure to use the same name you specified when creating the Azure Function with the Queue Trigger (see screenshot below). We used to call it <code>login-events</code>´.</p> <p></p> <h3 id="test-the-function">Test the Function</h3> <p>Once you have created the Queue, click the Queue entry in the Portal to get to the detail Blade. Here, click “+ Add message”. In the new Dialog, just add some text and click “OK”.</p> <p></p> <p>Back in Visual Studio, press F5 (or click Build --> Debug) to launch the local Azure Functions runtime in debug mode.</p> <p>Now watch the console window of your Function: it will log out how it processes the queue message you just added!</p> <p></p> <p>Checking back in the Azure Portal’s view of the Queue, you click the “Refresh” button to see how the message disappeared, because it got processed.</p> <blockquote> <p>If you want to inspect the Queue without actually de-queuing it, you can use the <a href="https://storageexplorer.com/">Azure Storage Explorer</a>.</p> </blockquote> <h1 id="set-up-playfab">Set up PlayFab</h1> <p>To call your Azure Function from Azure PlayFab, we need to register the Function binding via the Azure Storage Queue and set up an Event Trigger (aka <em>“Rule”</em>).</p> <h2 id="register-the-function">Register the Function</h2> <p>Log in to <a href="https://playfab.com/">Azure PlayFab</a> and click on the Title you want to register the Azure Function for.</p> <p>Once you are in the Title’s overview, click “Automation” (1), which opens the “Cloud Script” tab. In this tab, select the sub-tab “Functions (Preview)” (2), which will list all the previously registered Azure Functions. Now click the big orange button in the top right labeled “REGISTER FUNCTION” (3) to open the registration dialog.</p> <p></p> <p>Let's go through the individual settings for a registration:</p> <p></p> <ul> <li>Trigger type: set to “Queue”</li> <li>Function name: This is not actually the name of the Azure Function you deployed, but the name of the binding we’re currently setting up – so it’s the identifier you will be working with from PlayFab. Choose a name that fits your needs!</li> <li>Queue name: this is the queue name the <code>QueueTrigger</code> of the Azure Function listens to. In the examples above, this was <code>login-events</code>.</li> <li>Connection string: The ConnectionString to the Azure Storage Account Queue.</li> </ul> <p>To finish registering the Function registration, click <em>“REGISTER FUNCTION”</em>. The Registration should now appear in the overview.</p> <h2 id="set-up-a-rule">Set up a Rule</h2> <p>To set up a Rule, within a PlayFab Title, go to <em>“Automation”</em> (1) in the left pane, select the <em>“Rules”</em> Tab (2) and click <em>“NEW RULE”</em> (3).</p> <p></p> <p>A Rule is a configuration that listens on a <a href="https://docs.microsoft.com/en-us/gaming/playfab/features/automation/playstream-events/"><em>PlayStream</em> event</a> emitted by Azure PlayFab. When such an event occurs, the Rule checks whether the configured <em>Conditions</em> are met and if they are, triggers the configured <em>Action</em>.</p> <p>In our case, we want no conditions, but want to “Execute Azure Function”. In fact, what it does, is calling its own internal binding we just set up and provides it the PlayStream event data and additional arguments you may specify here (in JSON format) as argument to that binding.</p> <p>When that binding is called, it will either call the Function via HTTP trigger, or, as we configured it, by writing the data to the storage queue for the Azure Function to pick up via a <code>QueueTrigger</code>.</p> <p></p> <p>Click “<em>SAVE ACTION</em>” to save (yes, this saves the Rule 😉). You should now see the Rule in the overview.</p> <h2 id="trigger-the-playfab-rule">Trigger the PlayFab Rule</h2> <p>Now we want to test the Rule and trigger the Azure Function via an Azure PlayFab PlayStream Event. To do this, we need to raise an event of type <code>com.playfab.player_logged_in</code>, as we specified when we created the Rule.</p> <p>To achieve this, let’s create a small CLI application to log a Player in.</p> <p>In Visual Studio, create a new .NET Core Application (preferably in the same Solution as the Function app) and then install the <code>PlayFabAllSDK</code>, just like above.</p> <p>Now, you can paste the following C# code to your <code>Program.cs</code> to have a working program that signs into your game and if the Player does not yet exist, it will create a new one.</p> <blockquote> <p>Well, at least it is almost working. You need to substitute XXXX with your own Title ID. You can get the Title ID from your <a href="https://developer.playfab.com/en-US/my-games">Studio’s Overview Page</a>.</p> </blockquote> <p>Below code listing as <a href="https://gist.github.com/Structed/ff3190248833f40f611f0941f33793b9">GitHub Gist</a>.</p> <pre><code class="language-csharp">using PlayFab; using PlayFab.ClientModels; using System; using System.Threading; using System.Threading.Tasks; namespace GameCli { class Program { private static bool running = true; static void Main(string[] args) { PlayFabSettings.staticSettings.TitleId = "XXXXX"; // Please change this value to your own titleId from PlayFab Game Manager var request = new LoginWithCustomIDRequest { CustomId = "Player-" + Guid.NewGuid(), CreateAccount = true }; var loginTask = PlayFabClientAPI.LoginWithCustomIDAsync(request); while (running) { if (loginTask.IsCompleted) // You would probably want a more sophisticated way of tracking pending async API calls in a real game { OnLoginComplete(loginTask); } // Presumably this would be your main game loop, doing other things Thread.Sleep(1); } Console.WriteLine($"Done! Created new player named \"{request.CustomId}\". Press any key to close"); Console.ReadKey(); // This halts the program and waits for the user } private static void OnLoginComplete(Task<PlayFabResult<LoginResult>> taskResult) { var apiError = taskResult.Result.Error; var apiResult = taskResult.Result.Result; if (apiError != null) { Console.ForegroundColor = ConsoleColor.Red; // Make the error more visible Console.WriteLine("Something went wrong with your first API call. :("); Console.WriteLine("Here's some debug information:"); Console.WriteLine(PlayFabUtil.GenerateErrorReport(apiError)); Console.ForegroundColor = ConsoleColor.Gray; // Reset to normal color } else if (apiResult != null) { Console.WriteLine($"Was newly created? {apiResult.NewlyCreated}"); Console.WriteLine("Congratulations, you made your first successful API call!"); } running = false; // Because this is just an example, successful login triggers the end of the program } } } </code></pre> <p>Now execute the program and watch how the event is executed in PlayFab via the PlayStream Monitor!</p> <p></p> <h1 id="backend-implementation">Backend implementation</h1> <p>It's time to start the actual backend implementation!</p> <h2 id="using-the-playfab-context">Using the PlayFab Context</h2> <p>Before we even get started with writing backend code, you will need a <a href="https://github.com/PlayFab/PlayFab-Samples/blob/master/Samples/CSharp/AzureFunctions/CS2AFHelperClasses.cs">Helper classes file</a>, provided by PlayFab. <a href="https://github.com/PlayFab/PlayFab-Samples/blob/master/Samples/CSharp/AzureFunctions/CS2AFHelperClasses.cs">Download the file</a> and save it to your project (directly beneath the <code>*.csproj</code> or the Function class file). Here is why:</p> <p>Every time a Function is triggered, The <code>Context</code> in which it was executed is sent as a parameter. The Context includes the following when the Function is triggered via a PlayStream Event:</p> <ul> <li>The Entity Profile</li> <li>The PlayStream event which triggered the script.</li> <li>A boolean that indicates whether a PlayStream event is sent as part of the function being executed</li> <li>The Payload data you specified when setting up the binding in PlayFab</li> </ul> <blockquote> <p>For more information on the Context and what it contains in other environments (like if an Azure Function is called from a Game Client), please see the <a href="https://docs.microsoft.com/en-us/gaming/playfab/features/automation/cloudscript-af/cloudscript-af-context">Using CloudScript context models Tutorial</a>.</p> </blockquote> <h3 id="parsing-the-context">Parsing the Context</h3> <p>We already receive the Context in the Function we have created, it is the <code>myQueueItem</code> parameter:</p> <pre><code class="language-csharp"> [FunctionName("PlayStreamEventHandler")] public static void Run([QueueTrigger("login-events", Connection = "AzureWebJobsStorage")]string myQueueItem, ILogger log) { log.LogInformation($"C# Queue trigger function processed: {myQueueItem}"); } </code></pre> <p>However, it is just a JSON string, and we want it to be parsed to a C# POCO ("Plain Old C# Object").</p> <p>To do this, we first need the Class to convert to. The easiest way to do this is to use the PlayFab helper classes we downloaded and added above. It will contain all the Context Objects you need for the various deserialization use-cases.</p> <p>Now, we can actually deserialize the Context to <code>PlayerPlayStreamFunctionExecutionContext</code>:</p> <pre><code class="language-csharp"> [FunctionName("PlayStreamEventHandler")] public static void Run([QueueTrigger("login-events", Connection = "AzureWebJobsStorage")]string myQueueItem, ILogger log) { var context = JsonConvert.DeserializeObject<PlayerPlayStreamFunctionExecutionContext<dynamic>>(myQueueItem); log.LogInformation($"C# Queue trigger function processed: {myQueueItem}"); } </code></pre> <h2 id="authentication">Authentication</h2> <p>Authentication in Azure PlayFab might seem a little bit overwhelming at first, but it enables high flexibility and best operational security by allowing you to only make requests in the relevant context.</p> <p>For server-side actions, like we want to do here, this is particularly simple: we only need to set the <code>TitleId</code> and the <code>DeveloperSecretKey</code> on <code>PlayFabSettings.staticSettings</code>. Let's do that!</p> <h3 id="retrieving-the-titleid">Retrieving the <code>TitleId</code></h3> <p>This one is the simplest - you can just get it from the context we have deserialized:</p> <pre><code class="language-csharp"> PlayFabSettings.staticSettings.TitleId = context.TitleAuthenticationContext.Id; </code></pre> <h3 id="retrieving-the-developersecretkey">Retrieving the <code>DeveloperSecretKey</code></h3> <p>The DeveloperSecretKey must be retrieved from the <a href="https://developer.playfab.com/">Azure PlayFab Portal</a>.</p> <p>Log in and go to your Title you are working on. Then, click the little cogwheel beneath your Title's name (1) and select "Title Settings" (2). Last, select the "Secret Keys" Tab (3)</p> <p></p> <p>On This page, go ahead and click "NEW SECRET KEY". Specify a name and click "SAVE SECRET KEY".</p> <p>Now back on the Secret Key Overview, copy the secret key.</p> <h3 id="store-the-secret">Store the secret</h3> <p>Since we do not want to store the secret directly in the code, we will create a new setting <code>PlayFabDeveloperSecretKey</code> in <code>local.settings.json</code>. Substitute <code><YOUR SECRET KEY></code> with the secret you just copied from PlayFab:</p> <pre><code class="language-json"> { "IsEncrypted": false, "Values": { "AzureWebJobsStorage": "<connection string to queue storage>" "PlayFabDeveloperSecretKey": "<YOUR SECRET KEY>", "FUNCTIONS_WORKER_RUNTIME": "dotnet" } } </code></pre> <h3 id="authenticating-using-playfab-static-settings">Authenticating using PlayFab Static Settings</h3> <p>Now that we have all the information, let's go ahead and put together the code.</p> <p>Go to your Function's code, and paste the following code below your parsed context:</p> <pre><code class="language-csharp"> PlayFabSettings.staticSettings.TitleId = context.TitleAuthenticationContext.Id; PlayFabSettings.staticSettings.DeveloperSecretKey = Environment.GetEnvironmentVariable("DeveloperSecretKey"); </code></pre> <p>The function should now look like this:</p> <pre><code class="language-csharp"> namespace PlayFabEventStreamHandler { public static class PlayStreamEventHandler { [FunctionName("PlayStreamEventHandler")] public static async Task Run([QueueTrigger("login-events", Connection = "AzureWebJobsStorage")] string myQueueItem, ILogger log) { var context = JsonConvert.DeserializeObject<PlayerPlayStreamFunctionExecutionContext<dynamic>>(myQueueItem); log.LogInformation($"C# Queue trigger function processed: {myQueueItem}"); PlayFabSettings.staticSettings.TitleId = context.TitleAuthenticationContext.Id; PlayFabSettings.staticSettings.DeveloperSecretKey = Environment.GetEnvironmentVariable("DeveloperSecretKey"); } } } </code></pre> <p>This is already all we need to make requests using <code>PlayFabServerAPI</code> or <code>PlayFabAdminAPI</code> - now we only need to make a request!</p> <h2 id="updating-player-data">Updating Player Data</h2> <p>Create a new Method <code>UpdatePlayerData</code> as below:</p> <pre><code class="language-csharp"> private static async Task UpdatePlayerData(ILogger log, PlayerPlayStreamFunctionExecutionContext<dynamic> context) { var updateUserDataRequest = new PlayFab.ServerModels.UpdateUserDataRequest { PlayFabId = context.PlayerProfile.PlayerId, Data = new Dictionary<string, string> { {"<KEY>", "<VALUE>"} } }; PlayFabResult<PlayFab.ServerModels.UpdateUserDataResult> result = await PlayFabServerAPI.UpdateUserDataAsync(updateUserDataRequest); if (playFabResult.Error != null) { log.LogError($"Code: {playFabResult.Error.Error}\n{playFabResult.Error.ErrorMessage}"); } } </code></pre> <p>an call it in your Function's <code>Run()</code> method:</p> <pre><code class="language-csharp"> await UpdatePlayerData(log, context); </code></pre> <p>Your full function code should now look something like this:</p> <pre><code class="language-csharp"> using Microsoft.Azure.WebJobs; using Microsoft.Extensions.Logging; using Newtonsoft.Json; using PlayFab; using PlayFab.AdminModels; using PlayFab.Samples; using System; using System.Collections.Generic; using System.Threading.Tasks; namespace PlayFabEventStreamHandler { public static class PlayStreamEventHandler { [FunctionName("PlayStreamEventHandler")] public static async Task Run([QueueTrigger("login-events", Connection = "AzureWebJobsStorage")] string myQueueItem, ILogger log) { var context = JsonConvert.DeserializeObject<PlayerPlayStreamFunctionExecutionContext<dynamic>>(myQueueItem); log.LogInformation($"C# Queue trigger function processed: {myQueueItem}"); PlayFabSettings.staticSettings.TitleId = context.TitleAuthenticationContext.Id; PlayFabSettings.staticSettings.DeveloperSecretKey = Environment.GetEnvironmentVariable("DeveloperSecretKey"); await UpdatePlayerData(log, context); await CreateNews(log, context); await CreateItem(log, context); } private static async Task UpdatePlayerData(ILogger log, PlayerPlayStreamFunctionExecutionContext<dynamic> context) { var updateUserDataRequest = new PlayFab.ServerModels.UpdateUserDataRequest { PlayFabId = context.PlayerProfile.PlayerId, Data = new Dictionary<string, string> { {"<KEY>", "<VALUE>"} } }; PlayFabResult<PlayFab.ServerModels.UpdateUserDataResult> result = await PlayFabServerAPI.UpdateUserDataAsync(updateUserDataRequest); if (playFabResult.Error != null) { log.LogError($"Code: {playFabResult.Error.Error}\n{playFabResult.Error.ErrorMessage}"); } } } } </code></pre> <p>Ok, that's quite a chunk. Now what does <code>UpdatePlayerData()</code> do? Let's analyze the different blocks:</p> <h4 id="creating-a-request-object">Creating a Request object</h4> <pre><code class="language-csharp"> var updateUserDataRequest = new PlayFab.ServerModels.UpdateUserDataRequest { PlayFabId = context.PlayerProfile.PlayerId, Data = new Dictionary<string, string> { {"<KEY>", "<VALUE>"} } }; </code></pre> <p>Each PlayFab API request has a corresponding Request object, which is named accordingly and is located in the Namespace <code>PlayFab.<API TYPE>Models</code>, where <code><API TYPE></code> corresponds to one of the many APIs, like the Server, Admin, User or Authentication APIs, among others.</p> <p>The <code>UpdateUserDataRequest</code> <em>requires</em> a <code>PlayFabId</code> to know which Object to update. In our case, we want to update a Player, thus we need to pass a <code>PlayerId</code>, so it knows which Player to update. You can retrieve that from the Context that we deserialized earlier.</p> <p>Now to the core: Adding a <code>Dictionary<string, string></code> as <code>Data</code>, containing Key/Value pairs for the Data we want to set on the Player- e.g. the amount of Mana.</p> <h4 id="sending-the-request">Sending the Request</h4> <pre><code class="language-csharp"> PlayFabResult<PlayFab.ServerModels.UpdateUserDataResult> result = await PlayFabServerAPI.UpdateUserDataAsync(updateUserDataRequest); </code></pre> <p>Sending the request is as simple as calling the static Method <code>PlayFabServerAPI.UpdateUserDataAsync()</code> and passing it the request object we created before as a parameter. This method will return a Result object, we can then check for errors.</p> <h4 id="checking-for-errors">Checking for errors</h4> <pre><code class="language-csharp"> if (playFabResult.Error != null) { log.LogError($"Code: {playFabResult.Error.Error}\n{playFabResult.Error.ErrorMessage}"); } </code></pre> <p>Basically, whenever the <code>Error</code> property on the Request object is non-null, an Error has occurred. There are a couple more Properties on the Error object which help you identify the problem before going further.</p> <h2 id="testing-locally">Testing locally</h2> <p>Start the the Function locally, e.g. by pressing F5 in Visual Studio. Then, launch the <code>game-cli</code> to generate a new Player which then creates a PlayStream event, triggering the Rule which calls the Function. As we trigger the function using a Queue, we can again just read them locally.</p> <p>Once the Function has processed the new trigger, go back to Azure PlayFab and see whether the newly created player is listed in Azure PlayFab's <em>Player</em> listing. Then go to the player's detail view and click "Player Data (Title)". You should now see the newly added key/value pair - in my case it's <code>foo</code> and <code>bar</code>:</p> <p></p> <h2 id="deploying-the-function">Deploying the Function</h2> <p>Now that we have a working Azure Function, let’s deploy it to Azure!</p> <blockquote> <p>If you do not use Visual Studio, but want to use another IDE/Toolset, there are examples for creating & publishing Azure Function Apps with <a href="https://docs.microsoft.com/en-us/azure/azure-functions/functions-create-first-function-vs-code?pivots=programming-language-csharp">Visual Studio Code</a> or via <a href="https://docs.microsoft.com/en-us/azure/azure-functions/functions-create-first-azure-function-azure-cli?tabs=bash%2Cbrowser&pivots=programming-language-csharp">CLI</a>.</p> </blockquote> <h3 id="deploy-with-the-publish-command">Deploy with the "Publish" command</h3> <p>To get started and for the sake of this demo, we will be using “right click deploy”, the deployment mechanism integrated in Visual Studio. While this is convenient for a demo, please consider <a href="https://dev.azure.com/">Azure DevOps</a> or <a href="https://github.com/features/actions">GitHub Actions</a> to build your <strong>automated</strong> Continuous Integration & Continuous Deployment (CI/CD) pipelines for a real project – because manual deployments are error prone, require knowledge by a team member etc. Thus, there is the saying: <em>“Friends don’t let Friends right-click publish!”</em></p> <p>In Visual Studio, right-click the project and click “Publish”:</p> <p></p> <p>This will open a dialog where you can configure to which Azure Function App you want to deploy – and you can even create a new one using this dialog!</p> <p>While this deployment dialog also supports other deployment methods, please select “Azure”.</p> <p></p> <p>Then, “<em>Azure Functions App (Windows)</em>”.</p> <p></p> <p>In the following Dialog you can choose the Azure Function App or slot beneath an app to deploy to.</p> <p>If you haven’t already created an Azure Function App to deploy to, you can use the “<em>Create a new Azure Function…</em>” link to do so:</p> <p></p> <p></p> <p>Now select the Function App you want to deploy to:</p> <p></p> <p>Once selected, Visual Studio will pull the “Publishing Profile” from Azure.</p> <blockquote> <p><strong>WARNING</strong> Never add the user part of the publishing profile (<code>*.pubxml.user</code>) to source control, it contains your encrypted password!</p> </blockquote> <p>Now click “Publish” to deploy your Azure Function App.</p> <h3 id="testing-the-online-function">Testing the online Function</h3> <p>Since you have now deployed the Azure Function, let's go ahead and test it.</p> <p>First, make sure no local instance of the Function is running, so it is not competing against the online Azure Function when reading from the Azure Storage Queue.</p> <p>Next, launch the <code>game-cli</code> again, which should log-in a new Account and trigger the Function via the Storage Queue.</p> <p>You should now see the entry we created in the PlayFab data.</p> <h1 id="taking-it-further">Taking it further</h1> <p>Another possibility is to use Azure Functions to extend PlayFab even further, like enabling real-time messaging with <a href="https://azure.microsoft.com/en-us/services/signalr-service/">Azure SignalR Service</a> or a global database like <a href="https://azure.microsoft.com/en-us/services/cosmos-db/">CosmosDb</a>!</p> <h1 id="conclusion">Conclusion</h1> <p>In this article, we learned how to extend PlayFab by reacting to PlayFab PlayStream events with Azure Functions using Rules in PlayFab.</p> <p>We created the binding, added a rule and set-up an Azure Function app with a Storage Queue trigger. The Azure Function reads a message from the Storage Queue, which contains the PlayFab context. The context is used to reference the registered Player when we update it's Player data on Playfab.</p> <p>Last, we learned about the greater potential of extending Azure PlayFab with Azure Functions.</p> <p>I hope you enjoyed this end-to-end example. You can follow me on <a href="https://twitter.com/structed">Twitter @structed</a> and ask me about this post or all things Azure or have a look at my <a href="https://github.com/structed">GitHub</a>!</p> <p>Please also find the full source for this example at my GitHub repository: <a href="https://github.com/Structed/sample-playfab-eventstream-handler">https://github.com/Structed/sample-playfab-eventstream-handler</a></p> </article> <article> <h1>Deploy Statiq to Azure Static Web App</h1> <p>Tue, 18 May 2021 00:00:00 GMT</p> <h1 id="deploy-statiq-to-azure-static-web-app">Deploy Statiq to Azure Static Web App</h1> <p>Azure Static Web Apps just went GA a few days ago. I took the opportunity to deploy my blog as a "SWA" (Static Web App). In this post, I am writing about my experience with the service and how you can deploy a <a href="https://statiq.dev/">Statiq</a>-based site.</p> <h1 id="what-is-azure-static-web-app">What is "Azure Static Web App"?</h1> <p>It is a new Azure service which lets you deploy a static app (only static resources like images, HTML, JavaScript, CSS etc.). These resources will then automatically be served from "points of Presence" (PoP) around the world to make sure every user gets the site delivered in the fastest possible way. SWA uses Azure's CDN for this.</p> <h2 id="serverless-batteries-included">Serverless Batteries Included</h2> <p>However, with your Static Web App, you <em>can</em> also deploy an API in the form of Azure Functions. You may either use functions deployed with your app, or reference an existing Function App.</p> <h2 id="security">Security</h2> <p>To make your site secure, SWA offers authentication with Azure AD, GitHub and Twitter, so you can cordon-off parts (or all) of your site to authenticated users in roles you define.</p> <p>For this to work, SWA also supports <strong>free TLS certificates</strong> for your custom domains - even for your Apex Domains!</p> <h2 id="great-developer-experience">Great Developer Experience</h2> <p>With GitHub and Azure DevOps integration, you can easily build a CI/CD process with staging environments for your pull requests.</p> <p>This is complemented with a <a href="https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-azurestaticwebapps&WT.mc_id=javascript-11478-cxa">Visual Studio Code extension</a> and a <a href="https://github.com/Azure/static-web-apps-cli">CLI tool</a> for local tests.</p> <h2 id="pricing">Pricing</h2> <p>The free edition should cover most of your needs. Only if you have one of the following requirements, a monthly fee and bandwidth charges (>100GB) are due:</p> <ul> <li>>2 Domains</li> <li>Authentication</li> <li>Bring your own Azure Function (separate plan, not the one included with SWA)</li> <li>Higher storage requirements</li> </ul> <p>Check out the <a href="https://azure.microsoft.com/en-us/pricing/details/app-service/static/">pricing page</a> for more details.</p> <h1 id="what-is-statiq">What is "Statiq"?</h1> <p><a href="https://statiq.dev/">Statiq</a> is a .NET Static Generator Framework written in C#.</p> <p>Essentially, you configure pieces of code which are added to Pipelines. These pipelines process input (like Markdown, images, JSON) to an output.</p> <p>Statiq offers <code>Statiq.Framework</code>, as the base and <code>Statiq.Web</code> as the "happy path" on top to generate static sites.</p> <p>I am using <code>Static.Web</code> for my Blog. Since I usually do not have to change any code when publishing articles, I do not need to recompile all the time, but just run <code>dotnet run</code> to re-generate my content.</p> <p>Check out my <a href="https://blog.structed.me/setting-up-a-blog-with-statiq">previous blog post on how I use Statiq</a>.</p> <h1 id="setting-up-a-github-actions-workflow">Setting up a GitHub Actions Workflow</h1> <p>If you use SWA with GitHub, SWA creates a GitHub Actions workflow in your repo. This sets up two things:</p> <ol> <li>Build and deploy for pushes into the <code>main</code> branch</li> <li>Builds for opening, syncing, re-opening and closing of Pull Requests to the <code>main</code> branch</li> </ol> <p>Here is the YAML that was generated for me (<code>StructedSiteAssembler</code> is my subdirectory for the blog application)</p> <pre><code class="language-yaml">name: Azure Static Web Apps CI/CD on: push: branches: - main pull_request: types: [opened, synchronize, reopened, closed] branches: - main jobs: build_and_deploy_job: if: github.event_name == 'push' || (github.event_name == 'pull_request' && github.event.action != 'closed') runs-on: ubuntu-latest name: Build and Deploy Job steps: - uses: actions/checkout@v2 with: submodules: true - name: Build And Deploy id: builddeploy uses: Azure/static-web-apps-deploy@v1 with: azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_API_TOKEN_WHITE_PEBBLE_014EC7A10 }} repo_token: ${{ secrets.GITHUB_TOKEN }} # Used for Github integrations (i.e. PR comments) action: "upload" ###### Repository/Build Configurations - These values can be configured to match your app requirements. ###### # For more information regarding Static Web App workflow configurations, please visit: https://aka.ms/swaworkflowconfig app_location: "/StructedSiteAssembler" # App source code path api_location: "api" # Api source code path - optional output_location: "output" # Built app content directory - optional ###### End of Repository/Build Configurations ###### 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@v1 with: azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_API_TOKEN_WHITE_PEBBLE_014EC7A10 }} action: "close" </code></pre> <p>This specific config is needed, because it contains all the magic to deploy to SWA, which is not exposed to the public. This bothers me a bit, because it actually locks down the platform quite a bit and makes it harder to debug. But I never mind that, as GitHub Actions provides the flexibility needed, as you will see later.</p> <p>The docker image used here has another thing included: <em><a href="https://github.com/microsoft/Oryx">Oryx</a></em>. It detects which development stack you are using and generates & runs a build script for you. The output of which is then deployed to SWA.</p> <p>The actual "SWA magic" is in here:</p> <pre><code class="language-yaml"> - name: Build And Deploy id: builddeploy uses: Azure/static-web-apps-deploy@v1 with: azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_API_TOKEN_WHITE_PEBBLE_014EC7A10 }} repo_token: ${{ secrets.GITHUB_TOKEN }} # Used for Github integrations (i.e. PR comments) action: "upload" ###### Repository/Build Configurations - These values can be configured to match your app requirements. ###### # For more information regarding Static Web App workflow configurations, please visit: https://aka.ms/swaworkflowconfig app_location: "/StructedSiteAssembler" # App source code path api_location: "api" # Api source code path - optional output_location: "output" # Built app content directory - optional ###### End of Repository/Build Configurations ###### </code></pre> <p>.NET is detected and built correctly, but Statiq requires to run the app afterwards to actually create the output. This is where the "out of the box experience" did not work for me.</p> <h1 id="the-solution">The Solution</h1> <p>While Oryx correctly determines a lot of popular stacks, Statiq is not very widely adopted (yet!), so we have to do a little workaround. Thankfully, the build within the GitHub Action <code>Azure/static-web-apps-deploy@v1</code> can be skipped. Thus, it is only used to upload the artifact and deploy to the Azure Static Web App.</p> <p>To do this, we just need to add a few lines which</p> <ul> <li>Set up .NET</li> <li>Restore packages</li> <li>Build the app</li> <li>Run the app to generate output</li> </ul> <p>between <code>- uses: actions/checkout@v2</code> and <code>- name: Build And Deploy</code>:</p> <pre><code class="language-yaml"> - uses: actions/setup-dotnet@v1 with: dotnet-version: 5.0.203 - run: dotnet restore - run: dotnet build ./StructedSiteAssembler/StructedSiteAssembler.csproj --configuration Release --no-restore - run: dotnet run --project ./StructedSiteAssembler/StructedSiteAssembler.csproj --output output - name: Build And Deploy </code></pre> <p>However, as we still need the <code>Build And Deploy</code> step to deploy to SWA - but not the actual "Build" step with Oryx - we have the option to disable the build. Looking at <a href="https://docs.microsoft.com/en-us/azure/static-web-apps/github-actions-workflow#skip-app-build">the docs</a>, we can learn that you can use <code>skip_app_build: true</code> to skip the build. But it also requires us to set the <code>app_location</code> to the actual output directory. The value of <code>output_location</code> is ignored, if you set <code>skip_app_build: true</code>.</p> <p>Given my folder structure:</p> <pre><code>. ├───.github │ └───workflows └───StructedSiteAssembler ├───bin ├───input │ ├───images │ ├───posts │ └───scss ├───output │ ├───images │ ├───img │ ├───js │ ├───posts │ ├───scss │ ├───tags │ └───vendor ├───theme │ └───input │ ├───img │ ├───js │ ├───scss │ └───vendor └───wwwroot </code></pre> <p>my config would looks like this:</p> <pre><code class="language-yaml"> app_location: "/StructedSiteAssembler/output" # App source code path api_location: "" # Api source code path - optional output_location: "" # Built app content directory - optional skip_app_build: true </code></pre> <p>An here is the full Action setup for my blog:</p> <pre><code class="language-yaml">name: Azure Static Web Apps CI/CD on: push: branches: - main pull_request: types: [opened, synchronize, reopened, closed] branches: - main jobs: build_and_deploy_job: if: github.event_name == 'push' || (github.event_name == 'pull_request' && github.event.action != 'closed') runs-on: ubuntu-latest name: Build and Deploy Job steps: - uses: actions/checkout@v2 with: submodules: true - uses: actions/setup-dotnet@v1 with: dotnet-version: 5.0.203 - run: dotnet restore - run: dotnet build ./StructedSiteAssembler/StructedSiteAssembler.csproj --configuration Release --no-restore - run: dotnet run --project ./StructedSiteAssembler/StructedSiteAssembler.csproj --output output - name: Build And Deploy id: builddeploy uses: Azure/static-web-apps-deploy@v1 with: azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_API_TOKEN_WHITE_PEBBLE_014EC7A10 }} repo_token: ${{ secrets.GITHUB_TOKEN }} # Used for Github integrations (i.e. PR comments) action: "upload" ###### Repository/Build Configurations - These values can be configured to match your app requirements. ###### # For more information regarding Static Web App workflow configurations, please visit: https://aka.ms/swaworkflowconfig app_location: "/StructedSiteAssembler/output" # App source code path api_location: "" # Api source code path - optional output_location: "" # Built app content directory - optional skip_app_build: true ###### End of Repository/Build Configurations ###### 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@v1 with: azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_API_TOKEN_WHITE_PEBBLE_014EC7A10 }} action: "close" </code></pre> <h1 id="conclusion">Conclusion</h1> <p>Azure Static Web Apps is a great service to host a site, or even a browser-based game! With it's very fast response times all over the World thanks to Azure's CDN, the tight integration with Azure Functions and built-in authentications makes it a great, flexible and very low cost choice for many use-cases.</p> <p>I am certain we will be seeing tighter integration with more frontend frameworks and improved monitoring in the coming months.</p> <h1 id="further-reading">Further Reading</h1> <ul> <li><a href="https://github.com/staticwebdev/awesome-azure-static-web-apps">awesome-azure-static-web-apps</a></li> <li><a href="https://github.com/Azure/static-web-apps-cli">Static Web Apps CLI</a></li> <li><a href="https://github.com/Azure/static-web-apps-deploy">GitHub Action for Static Web Apps</a></li> <li><a href="https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-azurestaticwebapps">Visual Studio Code Extension</a></li> </ul> </article> <article> <h1>Setting up my Website & Blog using Statiq</h1> <p>Sun, 18 Apr 2021 00:00:00 GMT</p> <p>I have wished for my own site & blog for a <em>very</em> long time. Yet, I am clearly not a full-stack or even remotely a frontend developer. I am classic backend guy - the sort of which one would now call DevOps engineer or SRE.</p> <p>Basically, I have not the slightest clue about how to build web-frontends with JavaScript, all these frameworks and CSS, LESS, SASS - you name it. I don't know much about these technologies and I think the're a mess. Whenever I do frontend development, I have a strong feeling, it is non-deterministic.</p> <p>So I <em>really</em> struggled with building my site and never did it for many years.</p> <p>Then there comes <a href="https://twitter.com/daveaglick">Dave Glick</a> and his latest creation: <a href="https://statiq.dev/">Statiq</a>.</p> <p>Statiq is is a "Static Site Generator" - effectively a .NET Core CLI application that uses so called <em>Pipelines</em> to ingest arbitrary data from any source, processes it via one or more <em>Modules</em> to <em>Documents</em> (which are an object containing content and metadata) and ultimately generating static content. This generated output could really be anything: a static website, a PDF, JSON data etc.</p> <blockquote> <p>Find out more about <a href="https://statiq.dev/framework/#how-it-works">how Statiq works</a> in the Statiq.Framework docs.</p> </blockquote> <h1 id="layout">Layout</h1> <p>Statiq-based sites, as mentioned above, consist of code for pipelines, metadata and content files.</p> <p>A typical project folder structure looks like this:</p> <pre><code>. └───YourProjectName ├───input │ ├───images │ ├───posts │ └───scss ├───output │ ├───images │ ├───img │ ├───js │ ├───posts │ ├───scss │ ├───tags │ └───vendor ├───theme │ └───input │ ├───img │ ├───js │ ├───scss │ └───vendor └───wwwroot </code></pre> <ul> <li><code>input</code> defines all the content & metadata that is used as input for the Statiq pipelines, which eventually get transformed to <code>ouptput</code></li> <li><code>theme</code> contains all the pipeline code. I am using <a href="https://github.com/statiqdev/CleanBlog">CleanBlog</a> (by the Statiq development team) as a sub-module to my repository. However, I have forked it so I can make my own custom changes and contribute to the upstream repository.</li> <li><code>output</code> is where all the generated content goes. The contents of this folder is what you would deploy to your web-server.</li> </ul> <h1 id="creating-content-publishing">Creating content & publishing</h1> <p>You can create content by adding files to the <code>input</code> directory. Check out the Statiq Docs for more info.</p> <p>To transform the <code>input</code> to <code>output</code>, just run <code>dotnet run</code>. This will run all the pipelines and generate the static content.</p> <p>Since you might not be sure what the effects of your content additions are before generating and loading it in a browser, you can run <code>dotnet run -- preview</code> to start a preview server. It watches the input files for changes and automatically regenerates, refreshing your browser.</p> <p><span class="alert alert-light">Header Photo by <a href="https://unsplash.com/@impatrickt?utm_source=unsplash&utm_medium=referral&utm_content=creditCopyText">Patrick Tomasso</a> on <a href="https://unsplash.com/s/photos/static?utm_source=unsplash&utm_medium=referral&utm_content=creditCopyText">Unsplash</a></span></p> </article> </main></body></html>